The CLI for AI agents and automation

Agent mode, command discovery, the JSON contract, exit and error codes, confirmations, scopes, and the embedded agent skill.

This page is the contract for AI agents and scripts that operate Manage Runners through manage-runners. It is also available as Markdown, and the whole documentation as one file at /llms-full.txt.

Roles: the human sets up, the agent operates

A human installs the CLI, logs in and decides what the agent may do:

1. Install the CLI.
2. Give the agent a token, either:
   • interactive login with manage-runners setup or auth login, which yields a read-only token for 30 days, plus write scopes only if the human adds them with --scope, or
   • a dashboard token with exactly the scopes and expiry the task needs, provided to the agent through its secret store. See Personal access tokens.
3. Optionally install the agent skill.

The agent then runs commands with --agent, reads the results as JSON, and asks the human before anything that costs money or deletes data.

Agent mode

manage-runners runner list --agent

--agent means JSON output and no prompts. It is the same as --output json --non-interactive. In agent mode, a command that would need an answer fails instead of waiting for one.

Discover commands

manage-runners commands --agent
manage-runners help runner delete --agent

commands returns the catalog of every command. Each entry has:

help <command> --agent returns the same entry plus every flag with its usage text and whether it is required. The command reference shows the catalog and the help text of every command.

Output

Success:

{
  "ok": true,
  "command": "runner.get",
  "data": {
    "profile": "default",
    "origin": "https://api.managerunners.com",
    "runner": { "runnerId": "812999368881481087", "name": "build-01", "state": "READY" }
  },
  "meta": { "schema_version": "1", "cli_version": "1.0.0", "api_version": "1", "request_id": "deploy-42" },
  "warnings": []
}

Failure:

{
  "ok": false,
  "command": "runner.delete",
  "error": {
    "type": "usage",
    "code": "USAGE",
    "message": "--yes is required in non-interactive mode",
    "retryable": false,
    "unknown_outcome": false,
    "http_status": null,
    "field_errors": [],
    "details": {}
  },
  "meta": { "schema_version": "1", "cli_version": "1.0.0" },
  "warnings": []
}

The examples are abbreviated: the shape of data depends on the command, so read it from a real response. Both results and errors are written to standard output; prompts and nothing else go to standard error. Always check the exit code and ok.

• --request-id ID sends a request ID (1 to 128 safe characters) to the API and echoes it in meta.request_id, which helps to correlate logs.
• --output jsonl writes one JSON line per item of a list, and one line {"type": "warning", ...} per warning. An empty list writes nothing.
• IDs of runners and organizations are decimal strings. Keep them as strings; they do not fit into a double-precision number.

Exit codes

Error codes

The most important values of error.code:

Warnings in warnings do not change the exit code. Examples: TOKEN_ENV and TOKEN_ENV_OVERRIDES_STORE (a token came from the environment), RANGE_EXCEEDS_HISTORY (metrics history is shorter than the range), RUNNER_WARNING (a message from the API about the runner).

Confirmations

In agent mode the CLI never prompts. Commands that would ask a human must be confirmed with flags, and the agent may only add these flags when the human has approved the specific action.

runner update needs --yes only with --product-id, --gitlab-host, --runner-token-env, --concurrency, --executor, --ssh-key-id or --monitoring, because those recreate an active runner’s server. --name, --label and --hetzner-token-env alone do not.

A missing confirmation fails with exit code 2 before anything is sent. self-update reads the release manifest first, so it can report that nothing needs to change, but downloads nothing without confirmation.

Never run self-update unless the human asked for it or agreed to it; version --check is safe to run.

Paid and destructive commands

Treat every command with mutation: true as potentially billable, and check paid_resource_effect:

• create: runner create, runner resume and runner duplicate create Hetzner servers, which Hetzner bills to the user.
• recreate: runner update may delete and recreate an active runner’s server, interrupting its jobs.
• delete: runner pause and runner delete delete servers. runner delete also deletes the IP addresses and the schedule.

runner forget only removes an UNKNOWN runner’s record and leaves the server untouched. It is never a substitute for runner delete.

Scopes

runner update needs both runners:read and runners:write, because it reads the runner before writing the merged settings. --wait on create, update, pause, resume or duplicate polls the runner and needs runners:read as well. If polling fails, for example with exit code 4 for a missing scope or 7 for a timeout, the change itself was already accepted and is not undone: read the runner before doing anything else.

The token’s scopes and the member’s role both apply. A token cannot manage billing, organizations, members, invitations or other tokens. Imported tokens keep the scopes they were created with; the CLI cannot add scopes to them.

Credentials for agents

• Prefer a token passed through the environment: MANAGE_RUNNERS_TOKEN, or --token-env NAME for a variable with another name. Nothing is stored.
• auth status --agent reports where the token comes from in credential.source (environment, keyring or file). It never prints the token.
• Never print a token, pass it as a literal argument, or write it into files or logs.
• Use the file credential store (--credential-store file) only when the human agreed to it.
• Do not change profiles you were not asked to use.

Idempotency and unknown outcomes

runner create and runner duplicate send an idempotency key. The CLI generates a random key for each invocation unless you pass --idempotency-key (16 to 128 letters, digits, ., _ or -). The API deduplicates a request only when the user, organization, route, key and request are all the same. The 24 hours below count from the first attempt with that key, not from when it finished:

• Completed first attempt, retried within 24 hours of the first attempt: the API returns the original result and creates nothing new.
• Completed first attempt, retried later than that: the key is forgotten, and the same request creates another runner.
• First attempt not completed (still running, or interrupted before its result was stored): the API rejects every retry with that key as a conflict (exit code 6), also after 24 hours. Read the state instead of retrying.
• Same key, different request: the API rejects it as a conflict (exit code 6).

So reusing a key only protects a retry made soon after the first attempt, by the same user in the same organization, with the same flags. Never rely on an old key: before retrying a create or duplicate, list the runners and check whether the first attempt already created one.

When a change ends with exit code 10 (UNKNOWN_OUTCOME), the change may have happened. error.details may contain retryGuidance and idempotencyKey. Read the runner list or the runner, decide what actually happened, and only then continue.

Organizations

Without --org or a stored organization, commands use the user’s default organization. Use org list --agent to see memberships and roles, and --org ID_OR_NAME for one invocation. Store an organization with org use only when asked. See Profiles and organizations.

The agent skill

The CLI embeds a skill file that tells agents how to use it safely. Install it for your agent:

manage-runners setup skill install --target claude     # ~/.claude/skills/manage-runners
manage-runners setup skill install --target codex      # ~/.codex/skills/manage-runners
manage-runners setup skill install --target opencode   # opencode skills directory in your user config directory
manage-runners setup skill install --path ./skills/manage-runners

setup skill status reports whether it is installed and unchanged, and setup skill remove removes an unmodified copy. --dry-run shows what would change. An existing file that the CLI did not install, or a modified copy, is only replaced with --force.

This is the skill embedded in manage-runners (skill version 1):

---
name: manage-runners
description: Operate manage-runners safely through the official CLI.
metadata:
  owner: manage-runners
  version: "1"
---

# Manage Runners

Use `manage-runners commands --agent` to discover supported operations and required scopes.

Interactive `auth login` and `setup` request `profile:read`, `runners:read`, `schedules:read`, `products:read`, `providers:ssh-keys:read`, and `subscriptions:read` by default. Add write, delete, or forget scopes only when explicitly authorized. PAT imports keep the scopes granted by the server.

When a keyring is unavailable, a set `MANAGE_RUNNERS_TOKEN` is used automatically as the PAT for read and runner commands; `--token-env ENV_NAME` overrides it for one invocation. `auth status --agent` reports the credential source. Never print either variable's value; `auth login --token-env` instead imports a PAT into the credential store.

To store a credential without a keyring, pass `--credential-store file` or set `MANAGE_RUNNERS_CREDENTIAL_STORE=file`. The CLI keeps only a scoped, expiring PAT in a 0600 file, never the password or 2FA secret; tell the user so, and that it can be revoked in the dashboard or with `auth logout --revoke`. Never select the file store without the user's agreement.

Always use `--agent` for automation. Treat mutation commands as potentially billable and require the caller to supply every confirmation requested by command discovery.

`runner update` with `--product-id`, `--gitlab-host`, `--runner-token-env`, `--concurrency`, `--executor`, `--ssh-key-id` or `--monitoring` deletes and recreates an active runner's VM and needs `--yes`; `--name`, `--label` and `--hetzner-token-env` alone do not.

Use `runner metrics --agent` (optionally `--id`/`--name` and `--range 1h|24h|7d|30d|90d`) to read resource monitoring. `SUBSCRIPTION_REQUIRED` means monitoring needs an active paid subscription; do not retry. Only change monitoring when explicitly asked.

Runners, schedules, metrics and the subscription belong to an organization. Without `--org` and a stored organization, commands use the caller's default organization. Use `org list --agent` to see memberships and roles, `--org ID_OR_NAME` for one invocation, or `org use ID_OR_NAME` (`org use --clear`) to store one in the profile only when asked. `ORGANIZATION_PERMISSION_DENIED` means the member's role does not allow the action; do not retry. `ORGANIZATION_NOT_FOUND` means the organization is not among the caller's memberships.

`version --check --agent` reports whether a newer CLI release exists and exits 14 when one does; it is safe to run. Never run `self-update` without the user's consent, and pass `--yes` only after they agreed to that update.

Never print credentials, pass a token as a literal command argument, or change an unrelated manage-runners profile.

Machine-readable documentation

• Every page of these docs is available as Markdown: add index.md to the page URL, for example this page as Markdown.
• /llms.txt lists all pages with their Markdown URLs.
• /llms-full.txt contains the whole documentation, including the command reference, in one file.