circleci local execute: Run a Job Locally

circleci local execute runs one job from your config in a local Docker container, so you can test a step change without triggering a cloud pipeline.

Iterating on a CircleCI job by pushing commits is slow. local execute reproduces a single job on your machine. It cannot do workflows, contexts, or workspaces, but it is perfect for debugging one job.

What it does

circleci local execute processes the config, then runs the chosen job inside Docker on your machine. Only the docker executor is supported locally; workflows, persist_to_workspace, contexts, and approval jobs are not.

Common usage

Terminal

circleci local execute --job build
circleci local execute --job test -c .circleci/config.yml
circleci local execute --job build \
  -e MY_ENV=value          # inject an env var
# older CLI syntax
circleci local execute --job build

Options

Flag	What it does
--job <name>	The job to run locally
-c, --config <path>	Config file path
-e, --env <KEY=val>	Set an environment variable in the job
--debug	Verbose execution output

In CI

This is a local dev tool. Use it to validate a single job before you push; use circleci config validate and process for structural checks in the PR gate. Do not rely on it to test workflow-level behavior it cannot reproduce.

Common errors in CI

Cannot connect to the Docker daemon means Docker is not running. Error: You must specify a job to run ... means --job is missing. Steps that reference persist_to_workspace or restore_cache may warn skipping this step: running locally because those features are not supported locally. machine executor jobs fail with local executor only supports docker.