Problem:
When attempting to run circleci run release as described in the Configure Deploy Markers documentation, users may encounter the following error:
Error: unknown command "run" for "circleci"Did you mean this? runner Run 'circleci --help' for usage.
This occurs when the CircleCI Local CLI is installed and used instead of the build-agent binary, which is what actually supports the run subcommand. Both use the binary name circleci, so it's easy to confuse the two.
Solutions:
Solution 1: Confirm which binary is being executed
In a job step, run:
ls -l `which circleci`
Expected Output:
If using the correct build-agent, the path should be/usr/bin/circleci.
Considerations:
If the output path is anything else (e.g.,
/usr/local/bin/circleci), you're likely invoking the Local CLI instead.
Solution 2: Avoid installing the Local CLI
Check your project setup or
config.ymlto ensure you're not downloading or installing the Local CLI during job execution. The execution environment used for self-hosted runners already includes that command, so thecircleci run releasecommand can be used on the YAML configuration file. In general the local CLI is used out side of your CICD workflows.
Notes:
The Local CLI is not included in CircleCI base images and is not required for deploy marker support.
Solution 3: Use full path to call build-agent directly
If you must keep the Local CLI in your environment (e.g., for other scripts), use the full path to the correct binary:
/usr/bin/circleci run release ...
Considerations:
This bypasses
PATHand ensures the right binary is executed regardless of environment.
Outcome:
Once the correct circleci binary (the build-agent) is used, the run release command will execute successfully, creating the appropriate deploy marker. If the error persists, double-check your image, shell environment, and any scripts that may alter PATH.
Additional Notes:
This issue can arise in custom Docker images or workflows where multiple versions of the circleci CLI are installed or altered at runtime.