CircleCI-Public / CircleCI-Public/circleci-cli

circleci local execute will not be reimplemented in the v1 CLI

Open
#1,674 0 comments 0 reactions 0 assignees View on GitHub
Local Builds
Dominant language
Go
Stars
459
Forks
255
Avg merge
1d 4h
Merged PRs (30d)
59

Description

## Summary

`circleci local execute` will not be reimplemented in the v1 CLI. This issue explains
why, and records what we suggest instead. Every open `local execute` issue is being
closed as *not planned* and linked here.

## Why it is going away

`local execute` was never a self-contained feature of this CLI. The CLI was a thin
launcher: it pulled the `circleci/picard` image and handed your config to a copy of
our internal **build-agent** running inside it. Almost everything people report against
`local execute` — checkout, caching, workspaces, SSH keys, `store_test_results`,
networking, cgroups — is build-agent behaviour, not CLI behaviour.

That arrangement stopped working properly some time ago:

- **The build-agent it launches is pinned to a very old version.** The image digest is
hardcoded (see [`local/local.go`](https://github.com/CircleCI-Public/circleci-cli/blob/v0/local/local.go)),
so `Fetching latest build environment...` fetches an artifact that is years old and
no longer matches how jobs actually run on CircleCI. Newer build-agent images no
longer ship the subcommand the CLI invokes, so `--build-agent-version` does not
rescue it either (see #1130).
- **The environment it emulates has diverged from the real one.** Docker moved to
cgroup v2, containerd image storage, rootless daemons and Apple Silicon; Podman and
Colima became common. Each of those is a separate open issue against a component we
no longer build (#676, #811, #588, #1079, #464, #774).
- **The feature set was always a subset.** No `machine` executors, no workspaces, no
caching, no contexts, no parallelism, no test-result upload. Those are the parts of
a job most worth reproducing, and the ones a local Docker container cannot honestly
reproduce.

Reviving it would mean taking ownership of, versioning, and shipping a public
build-agent — a much larger commitment than a CLI subcommand, and one that would still
give an approximation of the real execution environment rather than the real thing.

## What we suggest instead

**[Chunk sidecars](https://circleci.com/chunk-sidecars/)** address the same need —
validate a change before pushing — but by running it in a real CircleCI cloud
environment rather than emulating one locally. The `chunk` CLI detects your stack,
generates a Dockerfile, provisions the sidecar, and runs your configured validation
commands remotely, streaming results back.

- Docs:
- CLI:
- Background:

Chunk sidecars are in Preview for Performance and Scale plans.

Two things the v1 CLI does cover that people often reached for `local execute` to get:

- **`circleci config validate` / `circleci config process`** — catch config errors,
expand orbs and resolve parameters without running anything.
- **`circleci run watch` / `circleci job output` / `circleci testresult list`** — get
the failure back in the terminal after a push, instead of clicking through the UI.

## Scope of this decision

- The `local` command group does not exist in the v1 CLI (`main`) and will not be added.
- The v0 implementation stays on the `v0` branch as-is; it receives critical fixes only.
- Comment here if Chunk sidecars do not cover your use case — that feedback is what
would justify revisiting this.

Contributor guide

Open the contributing guide

Research direction

Read the decision in this issue and inspect local/local.go and the v0 branch to confirm where the old implementation remains. Check the v1 main command group and the listed config and run commands; done means the v1 CLI remains without local execute and the documented alternatives and scope stay accurate.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, go
Domain
cli, devops, documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.