# Documentation for circleci-agent

**URL:** <https://discuss.circleci.com/t/documentation-for-circleci-agent/36594>\
**Category:** Documentation\
**Tags:** docs\
**Created:** [July 8, 2020, 9:30am UTC](https://discuss.circleci.com/t/documentation-for-circleci-agent/36594 "2020-07-08T09:30:31Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![OPeyrusse](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/opeyrusse/32/25382_2.png) [@OPeyrusse](https://discuss.circleci.com/u/OPeyrusse)\
**Post date:** [July 8, 2020, 9:30am UTC](https://discuss.circleci.com/t/documentation-for-circleci-agent/36594/1 "2020-07-08T09:30:31Z")

</div>

The documentation only mentions one use of `circleci-agent`, being `circleci-agent step halt` [1].  
Because this call is made of 2 params “step” and “halt”, I was wondering if any other values for those parameters were allowed.  
Without any trace of documentation in the official website and this forum, I also inspected the Dockerfile but found not trace of it. I tried running a container from the images supposedly including it, but there are no functions nor binaries with this name.  
My current guess is that it is injected as a docker volume by the CircleCI engine, so my only option is to run a job in ssh in order to debug it.

Being a very cumbersome operation, we should include somewhere a reference to this utility.

Cheers

[1] [https://circleci.com/docs/2.0/configuration-reference/#ending-a-job-from-within-a-step](https://circleci.com/docs/2.0/configuration-reference/#ending-a-job-from-within-a-step)

---

<div class="post-metadata">

**Author:** ![OPeyrusse](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/opeyrusse/32/25382_2.png) [@OPeyrusse](https://discuss.circleci.com/u/OPeyrusse)\
**Post date:** [July 29, 2020, 8:45am UTC](https://discuss.circleci.com/t/documentation-for-circleci-agent/36594/2 "2020-07-29T08:45:02Z")

</div>

For the record, `circleci-agent` is actually `circleci-cli` [1] with another name.  
With a dedicated Go module handling the `step` method [2].  
This is the better documentation I have found so far.

[1] [https://github.com/CircleCI-Public/circleci-cli](https://github.com/CircleCI-Public/circleci-cli)  
[2] [https://github.com/CircleCI-Public/circleci-cli/blob/c5d1aee86245d9600d532274097b0a1239b46f09/cmd/step.go](https://github.com/CircleCI-Public/circleci-cli/blob/c5d1aee86245d9600d532274097b0a1239b46f09/cmd/step.go)

---

<div class="post-metadata">

**Author:** ![glenjamin.circleci](https://avatars.discourse-cdn.com/v4/letter/g/73ab20/32.png) [@glenjamin.circleci](https://discuss.circleci.com/u/glenjamin.circleci)\
**Post date:** [July 29, 2020, 8:51am UTC](https://discuss.circleci.com/t/documentation-for-circleci-agent/36594/3 "2020-07-29T08:51:05Z")

</div>

I only just saw this message, sorry for the late response.

`circleci-agent` is the process which executes jobs in your container  
`circleci-cli` is the CLI which can be installed locally and in jobs to perform a variety of actions

In the past these used to be the same thing, but they were later split apart. To add to the confusion, they are often both executed using the name `circleci`.

The `circleci step ...` commands, and all `circleci test ...` commands are handled by `circleci-agent`. If you have `circleci-cli` installed then it will pass those commands through.

If you don’t have `circleci-cli` installed inside a job, then the `circleci` command will be handled directly by `circleci-agent`.

This isn’t an ideal situation, but it’s where we ended up after a series of changes over time while maintaining backwards compatibility of existing jobs.

---

<div class="post-metadata">

**Author:** ![OPeyrusse](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/opeyrusse/32/25382_2.png) [@OPeyrusse](https://discuss.circleci.com/u/OPeyrusse)\
**Post date:** [July 29, 2020, 12:38pm UTC](https://discuss.circleci.com/t/documentation-for-circleci-agent/36594/4 "2020-07-29T12:38:23Z")

</div>

Many thanks @glenjamin.circleci. Was I correct to read the “documentation” and possible actions for `circleci-agent` from the code base of circleci-cli?  
Or is the documentation just missing and will be added in the future?

---

<div class="post-metadata">

**Author:** ![cjerdonek](https://sea2.discourse-cdn.com/circleci/user_avatar/discuss.circleci.com/cjerdonek/32/33589_2.png) [@cjerdonek](https://discuss.circleci.com/u/cjerdonek)\
**Post date:** [October 15, 2025, 4:45pm UTC](https://discuss.circleci.com/t/documentation-for-circleci-agent/36594/5 "2025-10-15T16:45:34Z")

</div>

FYI, in CI you can also run `circleci-agent --help`, which gives what I’ve pasted below.

It’s possible this is the best that can be done for `circleci-agent` since `circleci-agent`’s options are different from `circleci-cli`’s, and the repo’s linked above are only for `circleci-cli` and not `circleci-agent` (maybe `circleci-agent` isn’t open source like `circleci-cli`).

```plaintext
$ circleci-agent --help
The CLI tool to be used in CircleCI.

Usage:
  circleci [command]

Available Commands:
  completion Generate the autocompletion script for the specified shell
  env Manage environment variables
  help Help about any command
  run Invokes a task-agent subcommand by name
  task Manage tasks
  tests Collect and split tests so they may be run in parallel.
  version Output version info

Flags:
  -h, --help help for circleci
      --verbose enable verbose logging output

Use "circleci [command] --help" for more information about a command.

```