Skip to main content

The CLI’s own commands

agentrail --help lists them, and agentrail <command> --help shows one command’s options.

Agentrail commands

Every Agentrail tool your role can use is a command: agentrail <area> <action>. Run agentrail tools to list them. A command that only reads changes nothing in your workspace. Agentrail sends the CLI its list of commands, so a command Agentrail adds works without updating the CLI.

Inputs

agentrail <area> <action> --help lists a command’s inputs, each one a flag. An input’s name becomes the flag in lowercase words joined by -, so agentModelId is --agent-model-id. The help says which are required.
  • A yes-or-no input is true when you give the flag alone. Pass false to say no: --include-community false.
  • A number takes digits: --limit 20.
  • A list or an object takes JSON, in single quotes so the shell keeps it whole: --finding-ids '["<finding id>", "<finding id>"]'.
  • --input '<json object>' or --input-file <path> gives the whole input at once, and any flag you also give overrides it:
A command missing a required input names the flags it needs, and exits with code 2.

Pages of results

A list comes a page at a time. --limit sets the page size. When there are more, the result has a nextCursor: pass it back as --cursor for the next page.

Choose a workspace

A command acts in the first of these that is set:
  1. --workspace <id>
  2. the AGENTRAIL_WORKSPACE environment variable
  3. the workspace linked to this directory, or to a directory above it, with agentrail link <id>
  4. your default workspace
agentrail workspaces list shows each workspace’s ID, and agentrail whoami shows the one commands use here.
A link is the file .agentrail/link.json in the directory you ran it in. agentrail unlink removes it.

Output

In a terminal, data is a table. It is JSON when the output goes to a file or another program, with --json, and when a coding agent runs the CLI. Data goes to stdout and messages to stderr, so a script can read one without the other: