CircleCI-Public / CircleCI-Public/circleci-cli
circleci local execute will not be reimplemented in the v1 CLI
- 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
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