> ## Documentation Index
> Fetch the complete documentation index at: https://agentrail.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Commands

> The CLI's own commands, the Agentrail commands your role can use, and how inputs, workspaces and output work.

## The CLI's own commands

| Command | What it does |
| - | - |
| `agentrail login` | Sign in. `--insecure-storage` keeps the sign-in in a file only you can read, instead of the keychain. |
| `agentrail logout` | Remove this computer's sign-in. |
| `agentrail whoami` | Who you are signed in as, and the workspace commands use. |
| `agentrail tools` | Every Agentrail command your role can use, and whether it only reads. |
| `agentrail link <workspaceId>` | Use a workspace for every command run in this directory and the ones under it. |
| `agentrail unlink` | Stop using the workspace linked to this directory. |
| `agentrail doctor` | Check what commands need, and say what to fix. |
| `agentrail update` | Whether a newer CLI exists, and the command that installs it. |
| `agentrail agent setup` | Set up Claude Code, Codex and Cursor to use Agentrail. See [Coding agents](https://agentrail.co/docs/cli/coding-agents.md). |

`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.

| Area | What its commands cover |
| - | - |
| `analytics` | How agents use your MCP servers, your pages' WebMCP tools and your API, as in **Analytics** |
| `brand` | Your **Brand Vault** |
| `evaluations` | Workflows and plugins: create and edit workflows, read their performance, attempts and production tracking, and check a plugin for directory submission |
| `feedback` | Your feedback projects, their placements and reports |
| `leaderboard` | The public agent-readiness leaderboard |
| `organizations` | The organizations you belong to, the one commands act in, and whether agent access is on in each |
| `readiness` | Agent readiness scans: start one, read its findings and evidence, compare two and get a prompt that fixes what a scan found |
| `simulations` | Scenarios and their runs: each run's log, changes, network, journey and files, analytics, recommendations, PR checks and the run schedule |
| `tags` and `topics` | Your topics and tags |
| `workspaces` | The workspaces you can use |

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.

```sh theme={null}
agentrail simulations list-runs --help
agentrail topics create --name "Payments"
agentrail leaderboard list-companies --include-community
```

* 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:

```sh theme={null}
agentrail simulations create-scenario --input-file scenario.json
```

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.

```sh theme={null}
agentrail simulations list-runs --limit 50 --cursor "<nextCursor>"
```

## 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.

```sh theme={null}
agentrail link <workspaceId>
```

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:

```sh theme={null}
agentrail tools --json > commands.json
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.