CLI for agents

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.

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 by default, a compact format that uses fewer tokens than JSON.
Every error is one JSON object on stderr. See 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

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

{
  "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

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

Documentation

AI agents

Learn

Migrations

Resources

Agent mode

Learn a command

Output

Errors and exit codes

Set up a project without prompts

In CI

​Agent mode

​Learn a command

​Output

​Errors and exit codes

​Set up a project without prompts

​In CI

Agent mode

Learn a command

Output

Errors and exit codes

Set up a project without prompts

In CI