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

# CLI for agents

> How coding agents use the Moderation API CLI: agent mode, JSON output, structured errors, exit codes and setup without prompts.

The `modapi` CLI is built for agents as well as people. An agent can learn every command from the CLI itself, check a request before it sends it, and read every result and error as data.

To install the CLI and set up a project, see the [CLI quickstart](https://docs.moderationapi.com/quickstart/cli.md).

## Agent mode

The CLI turns on agent mode when it runs inside a known coding agent, such as Claude Code, Cursor, Codex, Windsurf, Cline, Aider or GitHub Copilot. To turn it on yourself, add `--agent-mode`. To turn it off, add `--agent-mode=false`.

In agent mode:

* The CLI never asks a question. Pass every input as a flag.
* Output is [TOON](https://github.com/toon-format/spec) by default, a compact format that uses fewer tokens than JSON.
* Every error is one JSON object on stderr. See [errors and exit codes](#errors-and-exit-codes).

## Learn a command

An agent does not need to guess flags or request bodies:

| Run | You get |
| - | - |
| `modapi --help`, `modapi content submit --help` | Commands, flags and examples |
| `modapi --usage` | Every command, flag, default and environment variable, as data |
| `modapi content submit --schema` | The JSON Schema of the request body |
| `modapi content submit --dry-run` | The exact HTTP request, without sending it |

`--dry-run` makes no network call and uses no quota. It shows keys as `[REDACTED]`. Add `-o json` to get the preview as JSON.

## Output

```bash theme={"theme":"nord"}
# JSON on stdout
modapi actions list -o json

# Reshape the output with a jq expression
modapi actions list --jq '.[].key'

# Every page, one JSON value per line
modapi actions list --all -o json
```

`-o` is short for `--output-format`. It takes `pretty`, `json`, `yaml`, `table` and `toon`.

## Errors and exit codes

With agent mode, `-o json` or `--jq`, every error is one JSON object on stderr:

```json theme={"theme":"nord"}
{
  "error": "...",
  "error_type": "validation_error",
  "error_reason": "CLI_VALIDATION",
  "exit_code": 2,
  "message": "human-readable message",
  "hints": ["what to try next"]
}
```

| Exit code | Meaning |
| - | - |
| `0` | Success |
| `1` | The request or the command failed |
| `2` | Usage error, such as a missing or invalid flag |
| `3` | Authentication or authorization error |

`hints` says what to try next. Read it before you retry.

## Set up a project without prompts

```bash theme={"theme":"nord"}
# Sign in on a computer without a browser: confirm a code on another device
modapi login --device

# Link an existing project, or create a new one
modapi init --project "Acme Marketplace"
modapi init --new --domain acme.com

# Check the setup
modapi doctor -o json
```

`init` writes the keys to your env file, so the agent never sees them. `doctor` checks the key, the webhook secret, `.gitignore` and the SDK. Each check has a `status` (`ok`, `warn`, `fail` or `skip`), and a check that is not `ok` has a `remedy` with the command to run. `doctor` exits `1` when a check fails.

## In CI

Skip `login`. Set the keys as environment variables:

* `MODAPI_SECRET_KEY`: a project key, for content, queues, actions and the other project commands.
* `MODAPI_ORGANIZATION_KEY`: an [organization key](https://docs.moderationapi.com/api-reference/management-api.md), for `init`, `link`, `modapi projects` and `modapi channels`.

When both are set, the project key wins. To run a management command then, pass the organization key: `modapi projects list --secret-key "$MODAPI_ORGANIZATION_KEY"`.