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.
Agents running in Claude, Claude Code or another MCP client with Streamable HTTP and MCP authorization can use the remote MCP server at https://api.managerunners.com/mcp instead of the CLI: the human connects it with an OAuth sign-in, and no CLI or token is needed. See Connect to Claude and other AI assistants.
Roles: the human sets up, the agent operates
A human installs the CLI, logs in and decides what the agent may do:
- Install the CLI.
- Give the agent a token, either:
- interactive login with
manage-runners setuporauth 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.
- interactive login with
- 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:
| Field | Meaning |
|---|---|
name |
Dotted name, for example runner.delete |
path |
The words to type after manage-runners, for example ["runner", "delete"] |
summary |
One-line description |
mutation |
true if the command changes local configuration or remote state |
destructive |
true if it deletes or stops something |
paid_resource_effect |
create, recreate, delete or null: what it does to paid Hetzner or DigitalOcean resources |
required_scopes |
Token scopes the command needs |
required_flags |
Flags that must be given |
confirmation |
paid_resource, runner_id or null, see Confirmations |
supports_json |
Whether JSON output is supported |
supports_non_interactive |
false for commands that need a human at a terminal, such as setup |
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 IDsends a request ID (1 to 128 safe characters) to the API and echoes it inmeta.request_id, which helps to correlate logs.--output jsonlwrites 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
| Code | Meaning | What to do |
|---|---|---|
| 0 | Success | |
| 2 | Invalid command, flag or value, or a missing confirmation | Fix the command. Nothing was sent. |
| 3 | Token missing, invalid or expired | Ask the human to log in again. |
| 4 | Missing scope, role or plan | Do not retry. See the error code. |
| 5 | Runner, schedule or organization not found, or not monitored | Check the ID and organization. |
| 6 | The runner’s state does not allow the action, or a name is ambiguous | Read the runner’s state first. |
| 7 | The API rejected the input, or waiting for a runner timed out (with --wait, after the change was accepted) |
Fix the input, or check the runner’s state. |
| 8 | Rate limited or temporarily unavailable | Retry later with backoff. |
| 9 | The API could not be reached, or --timeout expired before the request completed |
Check connectivity, or give the command a longer --timeout. Before repeating a change, check whether it happened. |
| 10 | A change may or may not have happened | Do not retry. Read the state and reconcile first. |
| 11 | auth logout --revoke could not confirm revocation or local removal |
Check the token in the dashboard. |
| 12 | Configuration or credential store problem | Run manage-runners doctor. |
| 13 | Unexpected API response, too large a response, or an unsupported version; for self-update, a release or download that failed its checks |
Update the CLI; for metrics, use a shorter range. Do not retry a rejected download. |
| 14 | version --check: an update is available (ok is true) |
Tell the human; update only with their consent. |
| 70 | Internal error | Report it. |
Error codes
The most important values of error.code:
| Code | Exit | Meaning |
|---|---|---|
USAGE |
2 | Invalid input or missing confirmation |
ORGANIZATION_AMBIGUOUS |
2 | --org matches several organizations by name |
UNAUTHENTICATED |
3 | No valid token |
MFA_CODE_REJECTED |
3 | auth login or setup: the authenticator code was wrong or already used. Ask the human for the next code; never retry with the same one |
FORBIDDEN |
4 | The token lacks a scope, or the plan does not include the feature |
SUBSCRIPTION_REQUIRED |
4 | Showing metrics in the dashboard and sending them to a connection need an active plan. The same HTTP 403 is used for a missing scope, so this is the likely, not certain, cause. |
ORGANIZATION_PERMISSION_DENIED |
4 | Your role in the organization does not allow the action |
NOT_RELEASE_BUILD |
2 | A development or modified build cannot run self-update; error.details.hint names the install script (Linux, macOS) or the manual download steps (Windows) |
NOT_FOUND |
5 | The runner or schedule does not exist in the selected organization |
ORGANIZATION_NOT_FOUND |
5 | The organization is not among your memberships |
NOT_MONITORED |
5 | The runner exists but is not active or does not show metrics in the dashboard |
RELEASE_NOT_FOUND |
5 | The release given to self-update --version does not exist |
CONFLICT |
6 | The runner’s state does not allow the action |
AMBIGUOUS |
6 | Several runners have that name; use --id |
VALIDATION |
7 | The API rejected the input |
TIMEOUT |
7 | runner wait, runner watch or --wait timed out; with --wait, the change itself was accepted |
RETRYABLE |
8 | Try again later |
TOO_MANY_TOTP_FAILURES |
8 | auth login or setup: too many wrong authenticator codes for the account. Do not retry before the time in the message |
TIMEOUT |
9 | --timeout expired before a request to the Manage Runners API was sent, or before a read got its response; the timed-out request changed nothing. self-update and version --check report NETWORK instead |
NETWORK |
9 | Network error |
UNKNOWN_OUTCOME |
10 | The change may have happened; reconcile before retrying |
REVOCATION_UNCONFIRMED |
11 | Token revocation could not be confirmed |
CONFIG, CREDENTIAL_STORE |
12 | Local configuration or credential store problem |
INSTALL_DIR_NOT_WRITABLE, UPDATE_FAILED |
12 | self-update cannot write or replace the binary, or the binary changed while it ran; when the directory is not writable, error.details.hint names the install script (Linux, macOS) or the manual download steps (Windows) |
INCOMPATIBLE_RESPONSE, RESPONSE_TOO_LARGE |
13 | The API response or release manifest could not be used |
PLATFORM_NOT_RELEASED |
13 | The release has no build for this operating system and CPU |
DOWNLOAD_REJECTED |
13 | The download failed its size, SHA-256 or archive checks, or was redirected to another host; nothing was changed |
INVALID_PROVIDER, INVALID_LOCATION, INVALID_PRODUCT, PROVIDER_TOKEN_REQUIRED |
7 | The provider is unknown or not offered, or the location, product or token does not fit it |
INVALID_PROVIDER_TOKEN |
7 | DigitalOcean refused the token |
DIGITALOCEAN_CONNECTION_NOT_FOUND |
5 | No DigitalOcean connection with this ID in the organization |
DIGITALOCEAN_CONNECTION_NEEDS_RECONNECT |
6 | DigitalOcean no longer accepts the connection; connect the team again in the dashboard |
DIGITALOCEAN_TEAM_MISMATCH |
7 | The connection or token is for another DigitalOcean team than the runner’s droplet |
PROVIDER_CREDENTIAL_CONFLICT |
7 | Both a token and a DigitalOcean connection were given |
PROVIDER_VM_CREATION_ERROR, PROVIDER_PRECONDITION_FAILED |
7 | DigitalOcean refused the droplet or the request, for example at the droplet or reserved IP limit, for a size the account’s limits do not allow, or for a locked account |
PROVIDER_API_ERROR |
7, 8 or 10 | The DigitalOcean API refused the request, most likely for a missing token scope (7), or failed (8; 10 for runner changes, whose outcome is then unknown) |
PROVIDER_CATALOG_UNAVAILABLE |
8 or 10 | DigitalOcean’s products cannot be read right now; after runner update (10), inspect the runner before retrying |
PROVIDER_IP_DELETION_PENDING |
8 | runner delete of a paused DigitalOcean runner: DigitalOcean has not released its IP yet, so the runner was kept; run the delete again in a few minutes |
Provider errors name the provider in details.provider and carry its message in details.detail.
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.
Catalog confirmation |
Commands | Non-interactive confirmation |
|---|---|---|
paid_resource |
runner create, runner resume, runner duplicate, runner pause, runner update when it recreates the server, and runner autoscaling set, enable and disable |
--yes |
runner_id |
runner delete, runner forget |
--yes and --confirm <runner-id>, exactly equal to --id |
runner_id |
schedule delete |
--yes and --confirm <runner-id>, exactly equal to --runner-id |
runner_id |
runner autoscaling delete |
--yes and --confirm <runner-id>, exactly equal to the anchor’s id: --id, or the id that --name resolves to |
self_update |
self-update |
--yes |
null |
every other command | none |
runner update needs --yes only with --product-id, --gitlab-host, --runner-token-env, --concurrency, --executor, --ssh-key-id, --cache, --no-cache, --dashboard, --send-to or --no-send-to, because those recreate an active runner’s server. On a GitHub runner, --label needs it too, because GitHub registers the labels. --name, --hetzner-token-env, --provider-token-env and, on a GitLab runner, --label 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 resumeandrunner duplicatecreate Hetzner servers or DigitalOcean droplets, which the provider bills to the user.runner autoscaling setandenablelet a scaling policy create burst runners, which are servers too.recreate:runner updatemay delete and recreate an active runner’s server, interrupting its jobs.delete:runner pauseandrunner deletedelete servers.runner deletealso deletes the IP addresses and the schedule.runner autoscaling disableanddeletedrain and delete every burst runner of the policy.
runner forget only removes an UNKNOWN runner’s record and leaves the server untouched. It is never a substitute for runner delete.
Scopes
| Scope | Commands |
|---|---|
profile:read |
auth status, profile show, org list, org use, resolving --org |
runners:read |
runner list, get, watch, wait, metrics, ssh-keys, update, every runner autoscaling command, and --wait on any runner change |
runners:write |
runner create, update, pause, resume, duplicate, runner autoscaling set, enable, disable, delete |
runners:delete |
runner delete |
runners:forget |
runner forget |
schedules:read |
schedule get |
schedules:write |
schedule set, enable, disable, delete |
products:read |
product list, get, locations |
providers:ssh-keys:read |
provider hetzner ssh-keys, provider digitalocean ssh-keys |
subscriptions:read |
subscription show, subscription plans |
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 NAMEfor a variable with another name. Nothing is stored. auth status --agentreports where the token comes from incredential.source(environment,keyringorfile). 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. `EMAIL_NOT_VERIFIED` means the account's email address is not verified yet: ask the user to enter the emailed code in the dashboard, then log in again; do not retry before that. `MFA_CODE_REJECTED` means the authenticator code was wrong or already used: ask the user for the next code from their authenticator app; never retry with the same code. `TOO_MANY_TOTP_FAILURES` (exit 8) means too many wrong codes: tell the user, do not retry before the time in the message, and suggest a password reset if they did not make those attempts.
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 create`, `runner update`, `runner resume` and `runner duplicate` fail with `SUBSCRIPTION_REQUIRED` when the organization has no active plan; do not retry. Running runners keep running, and `runner pause` and `runner delete` still work.
`runner pause` lets the runner finish its running jobs first and reports `PAUSING`; it takes no new jobs and becomes `PAUSED` once they have finished, after at most one hour. A busy GitHub runner can still get jobs that ask only for GitHub's default labels until its job ends. Only use `--force` (immediate, cancels running jobs) when the user asks for it.
`runner create` without `--name` gets a generated name such as `swift-falcon`; the result's `name` shows it.
`runner update` with `--product-id`, `--gitlab-host`, `--runner-token-env`, `--concurrency`, `--executor`, `--ssh-key-id`, `--cache`, `--no-cache`, `--dashboard`, `--send-to` or `--no-send-to` deletes and recreates an active runner's VM and needs `--yes`; `--name`, `--label`, `--hetzner-token-env`, `--provider-token-env`, `--watchdog` and `--watchdog-timeout` alone do not, except that `--label` recreates GitHub runners.
Runners are GitLab runners unless created with `runner create --platform github`, which takes `--github-owner`, `--github-repository` (omit it for an organization runner), `--github-runner-group` (organization runners only) and `--github-token-env NAME` instead of `--gitlab-host`, `--executor` and `--runner-token-env`; GitHub runners need `--concurrency` 1 to 32 and cannot use caches. The token is a fine-grained GitHub token with Administration read and write (repository) or Self-hosted runners read and write (organization); ask the user to provide it in an environment variable, never as an argument. `runner get` and `runner list` show `platform` and, for GitHub runners, `github` with `owner`, `repository` and `runnerGroup`. `runner update --github-token-env NAME` rotates a GitHub runner's token without recreating it. `GITHUB_TOKEN_INVALID`, `GITHUB_PERMISSION_DENIED` (the details name the missing permission) and `GITHUB_NOT_FOUND` need a corrected token or scope from the user; do not retry unchanged. State `REGISTRATION_FAILED` ends waiting: the runner could not register; report it and suggest checking the token. `RUNNER_STATE_CONFLICT` means nothing changed; read the runner again before retrying. `RUNNER_PAUSED_TOKEN_REFUSED` (exit 11) means an update saved the new settings but left the runner paused because GitHub refused its token; do not repeat the update: ask the user for a valid token, rotate it, then resume the runner.
Hetzner tokens are saved per organization: `provider hetzner tokens` lists them by id and name with the runners and policies that use them, never their values, and `--hetzner-token ID` replaces `--hetzner-token-env` in `runner create`, `runner update`, `runner autoscaling set` and `provider hetzner ssh-keys`, so prefer a saved token over asking the user for a token. A token passed with `--hetzner-token-env` is saved to the organization, or matched with a saved one. Saving, replacing and deleting saved tokens needs the dashboard (Organization settings); replacing one there brings back runners that became UNKNOWN because Hetzner refused it, so suggest that instead of a new token per runner. `runner update` switches a runner to another token only within its Hetzner project (`HETZNER_PROJECT_MISMATCH`, exit 7, otherwise); `HETZNER_TOKEN_NOT_FOUND` (exit 5) means the id is not a saved token of the organization. `HETZNER_TOKEN_REPLACED` (exit 6) means someone replaced the saved token while the request used it: a create created nothing; after an update, read the runner with `runner get`, then retry.
Runners run on Hetzner unless created with `runner create --provider digitalocean`, which takes `--provider-token-env NAME` instead of `--hetzner-token-env`, a DigitalOcean product (`product list` shows `provider` `DigitalOcean`, prices in USD) and its region as `--location`, for example `fra1`. The token is a DigitalOcean personal access token with the custom scopes `account:read`, `droplet:create`, `droplet:read`, `droplet:update`, `droplet:delete`, `image:read`, `reserved_ip:create`, `reserved_ip:read`, `reserved_ip:update`, `reserved_ip:delete`, `ssh_key:read` and `tag:create`; ask the user to provide it in an environment variable. `provider digitalocean ssh-keys --token-env NAME` checks it and lists the account's SSH keys. Instead of a token, a DigitalOcean team the user connected in the dashboard can be used: `provider digitalocean connections` lists the connections (id, team, status), and `--digitalocean-connection ID` replaces `--provider-token-env` in `runner create --provider digitalocean`, `runner update` (only to another connection or token of the same team; `DIGITALOCEAN_TEAM_MISMATCH` otherwise), `runner autoscaling set` and `provider digitalocean ssh-keys`. Connecting a team needs the browser; `DIGITALOCEAN_CONNECTION_NEEDS_RECONNECT` (exit 6) means the user has to connect it again in the dashboard's Organization settings. `runner get` and `runner list` show `provider` only for runners not on Hetzner; the provider and location of a runner cannot change, and `runner update --provider-token-env NAME` replaces its token. Each DigitalOcean runner keeps a reserved IPv4 and IPv6, also while paused (the IPv4 then costs USD 5 a month). `PROVIDER_VM_CREATION_ERROR` usually means the account's droplet or reserved IP limit: ask the user to have DigitalOcean raise it; `INVALID_PROVIDER_TOKEN` and `PROVIDER_API_ERROR` with exit 7 need a valid token with all scopes; do not retry unchanged. `PROVIDER_CATALOG_UNAVAILABLE` with exit 8 was refused before anything changed: retry later; with exit 10 (`runner update`) the update may have paused the runner and saved its settings: inspect it with `runner get` before retrying. `PROVIDER_IP_DELETION_PENDING` (exit 8) from `runner delete` means DigitalOcean has not released the runner's IP yet and the runner was kept: run the same delete again in a few minutes. `PROVIDER_API_ERROR` with exit 10 may have left a change half done: show the user DigitalOcean's message from `details.detail` and inspect the runner with `runner get` before retrying.
S3-compatible runner caches belong to the organization: `cache list --agent` shows each cache and the runners using it. `runner create` or `runner update` take `--cache ID_OR_NAME` (a name needs `runners:read`); `runner update --no-cache` removes it. Pass the cache secret key only with `--secret-key-stdin` or `--secret-key-env NAME`; it is never returned. `cache update` that changes the connection or sharing recreates the VMs of active runners using the cache: it fails with `CACHE_RECREATE_REQUIRED` and the runners until repeated with `--yes`, which needs explicit approval; runners with `recreate: false` are unknown and keep the old settings until edited or recreated. `RUNNER_LOCKED` lists runners that are busy; retry later. `cache delete` of a cache in use fails with `CACHE_IN_USE`. `cache test` writes, reads and deletes a small object and only works for HTTPS endpoints.
Metrics are a runner VM's CPU, RAM, swap and disk usage and its running CI jobs (on GitHub runners from collector 1.2.0 on). Each runner has two independent destinations: `--dashboard on|off` shows them in the dashboard, where `runner metrics` reads them, and `--send-to ID_OR_NAME` (a name needs `runners:read`) or `--no-send-to` on `runner create` or `runner update` sends them to one of the organization's Metrics connections (OTLP endpoints). Both need an active paid subscription to switch on; an unknown connection fails with `INVALID_METRICS_CONNECTION`. `metrics list --agent` shows each connection: endpoint, header names and the runners using it. `metrics create --name NAME --endpoint URL` and `metrics update --id ID|--name NAME` take header values only from `--header-env NAME=VAR` or `--header-stdin NAME`; `--header NAME` keeps a stored value. An endpoint or header change, and `metrics delete`, after which the connection's runners send to no connection, recreates the VMs of the active ones: it fails with `METRICS_CONNECTION_RECREATE_REQUIRED` and the runners until repeated with `--yes`, which needs explicit approval. `runner get` and `runner list` show `monitoringEnabled` (shown in the dashboard), `metricsConnectionId`, `metricsConnectionName` and the last reported `metricsStatus`.
Use `runner metrics --agent` (optionally `--id`/`--name` and `--range 1h|24h|7d|30d|90d`) to read the metrics shown in the dashboard. `SUBSCRIPTION_REQUIRED` means metrics need an active paid subscription; do not retry. Only change `--dashboard` or `--send-to` when explicitly asked.
A runner with `--dashboard on` or a `--send-to` connection can have a watchdog: `--watchdog on|off` and `--watchdog-timeout MINUTES` (5 to 60, default 10) on `runner create` or `runner update`. When the collector reports nothing for the timeout, the platform restarts the runner by a forced pause and resume, which cancels its running jobs; at most three times in 24 hours, then the watchdog switches itself off with `disabledReason` `RESTART_LIMIT`. Enable it only when asked. `INVALID_WATCHDOG` names the refused setting in `details.field`; `watchdogEnabled` means the runner needs the dashboard or a connection first. `runner get` shows `watchdog` with `restarts`, `lastRestartAt` and `lastRestartResult`; `RESUME_FAILED` means the runner could not be resumed (it is paused, or `UNKNOWN` after a refused Hetzner token): report it rather than resuming it unasked.
External runners are self-hosted GitLab or GitHub runner servers that report metrics through the Manage Runners agent but that Manage Runners does not create, pause or change. `external-runner list --agent` and `external-runner get --id ID|--name NAME` show their `status` (`WAITING_FOR_INSTALL`, `ONLINE`, `OFFLINE` or `REVOKED`), `reinstallNeeded` with `reinstallReasons`, and `specs` from the agent's samples; `runner list` shows them as `externalRunners`, and `runner metrics` reads their metrics. `external-runner create --name NAME --platform gitlab|github` and `external-runner update` take `--label`, `--dashboard` and `--send-to`; changed settings reach the server only through a new install command. `external-runner install-command` prints a single-use command, valid for 15 minutes, that the user runs on the server as root; it carries the server's credential, so print it only when the user asks and never store it. `external-runner delete` needs `--yes --confirm ID` and returns the server's uninstall command.
Autoscaling adds paid Hetzner or DigitalOcean burst runners to a GitLab or GitHub runner or external runner, the anchor, while few of its group's job slots are free; it adds none while every runner reports that no job runs, though CPU or memory rules can still add one when job counts are unknown. `runner autoscaling get --id ID|--name NAME --agent` shows the policy, its burst runner template without tokens (external anchors) and `status` (burst runners, `capacity` with the group's busy and free job slots or null, last decision and reason, failures, `disabledReason`, `cleanupBlocked`); `runner autoscaling events` lists its newest events. `runner autoscaling set` changes only the given settings: `--preset eager|balanced|conservative` or up to three `--rule`, one per metric: `free:K:MINUTES` (add when at most K job slots are free for MINUTES, for example `free:0:3`) or `cpu|memory:OUT:MINUTES:IN` (for example `cpu:80:5:30`), `--max` (required for a new policy), `--step`, `--scale-in-window`, `--stabilization`, `--enabled`; for an external anchor also the burst runner settings of its platform (GitLab: `--gitlab-host`, `--executor`, `--cache`; GitHub: `--github-owner`, `--github-repository` or `--github-runner-group`, and the anchor's labels), with the tokens only from `--hetzner-token-env` (or `--provider-token-env` or `--digitalocean-connection ID`, one of which `--provider digitalocean` needs) and `--runner-token-env` or `--github-token-env` (omitted, the stored ones are kept). A managed anchor's burst runners copy it on its provider; `--provider` with another provider creates them there with `--product-id`, `--location`, that provider's token and optional `--ssh-key` (shown as `burst` by `get`), and `--provider` with the anchor's own provider switches back; `SCALING_POLICY_CHANGED` (exit 6) means another change replaced the stored burst provider or token meanwhile and nothing was saved, so run `runner autoscaling get` and retry. `set` and `enable` can create paid servers, and `disable` and `delete` drain and delete every burst runner: run them only when asked, with the `--yes` (and for `delete` `--confirm ID`) the user agreed to. Policies need a Pro or Enterprise plan (`SUBSCRIPTION_REQUIRED`). `runner list` and `runner get` mark burst runners with `burst` and their anchor; `BURST_RUNNER_READ_ONLY` means a burst runner can only be deleted, so change its anchor's policy instead.
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.mdto 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.