CLI command reference
Every manage-runners 1.11.0 command with its scopes, safety properties and help text.
This reference is generated from manage-runners itself. Each page lists the command's required token scopes, whether it changes state or creates paid resources, which confirmation it needs, and its full help text. The agent guide
explains how to read these properties.
Commands
general
| Command | Summary |
|---|---|
manage-runners commands | List CLI commands |
manage-runners help | Show command help |
manage-runners version | Show CLI version metadata; --check compares it with the latest release |
manage-runners self-update | Replace this binary with the latest release, or --version, after verifying its SHA-256 |
manage-runners completion | Generate shell completion scripts |
manage-runners setup | Run the human setup wizard |
manage-runners doctor | Run read-only diagnostics |
config
| Command | Summary |
|---|---|
manage-runners config show | Show effective non-secret configuration |
manage-runners config profiles | List configured API profiles |
manage-runners config set-api | Store an API origin after HTTPS validation; the default profile otherwise uses https://api.managerunners.com |
setup
| Command | Summary |
|---|---|
manage-runners setup skill | Install or manage the embedded agent skill |
auth
| Command | Summary |
|---|---|
manage-runners auth login | Store a PAT from stdin or a named environment variable |
manage-runners auth status | Show authentication status without printing the token |
manage-runners auth logout | Remove the local credential; optionally revoke the current PAT |
manage-runners auth profiles | List local profiles without credentials |
manage-runners auth use | Select the default profile |
runner
| Command | Summary |
|---|---|
manage-runners runner list | List owned runners |
manage-runners runner get | Get one runner by exact ID or unique name |
manage-runners runner watch | Poll a runner until a target or terminal state |
manage-runners runner metrics | Show the metrics of one or all runners shown in the dashboard; manage the connections they are sent to with the metrics commands |
manage-runners runner ssh-keys | List SSH keys available through the runner provider credential |
manage-runners runner create | Create one GitLab or GitHub (--platform github) runner; may create paid Hetzner or DigitalOcean (--provider digitalocean) resources; --cache or --send-to by name also needs runners:read |
manage-runners runner update | Update one runner; product, GitLab host, runner token, concurrency, executor, SSH key, cache, --dashboard or --send-to changes, and label changes of GitHub runners, recreate an active runner's VM; --github-token-env rotates a GitHub runner's token and --watchdog and --watchdog-timeout change the watchdog without recreating it |
manage-runners runner pause | Pause a runner and delete its active VM; the runner first finishes its running jobs (at most one hour) unless --force |
manage-runners runner resume | Resume a paused runner; may create paid Hetzner or DigitalOcean resources |
manage-runners runner duplicate | Duplicate a runner; may create paid Hetzner or DigitalOcean resources |
manage-runners runner delete | Delete an active or paused runner |
manage-runners runner forget | Remove only an UNKNOWN dashboard record |
manage-runners runner wait | Wait for a runner target state after a mutation |
manage-runners runner autoscaling get | Show the scaling policy of a runner or external runner: settings, burst runner template without tokens, and status |
manage-runners runner autoscaling set | Create or change a runner's scaling policy, which adds paid Hetzner or DigitalOcean burst runners while the runner is busy; unchanged settings and omitted tokens are kept |
manage-runners runner autoscaling enable | Enable a scaling policy, which may create paid Hetzner or DigitalOcean burst runners; clears earlier failures |
manage-runners runner autoscaling disable | Disable a scaling policy and drain and delete every burst runner; the settings are kept |
manage-runners runner autoscaling delete | Delete a scaling policy and its events, and drain and delete every burst runner |
manage-runners runner autoscaling events | List the newest events of a scaling policy |
schedule
| Command | Summary |
|---|---|
manage-runners schedule get | Read a runner schedule |
manage-runners schedule set | Create or replace a runner schedule |
manage-runners schedule enable | Enable an existing schedule |
manage-runners schedule disable | Disable a schedule without deleting it |
manage-runners schedule delete | Permanently delete a schedule |
cache
| Command | Summary |
|---|---|
manage-runners cache list | List the organization's S3 runner caches and the runners using them |
manage-runners cache get | Get one cache by exact ID or name |
manage-runners cache create | Create an S3-compatible runner cache; the secret key comes from stdin, an environment variable or a prompt |
manage-runners cache update | Update a cache; connection or sharing changes recreate the VMs of active runners that use it |
manage-runners cache delete | Delete a cache that no runner uses; --name also needs runners:read |
manage-runners cache test | Write, read and delete a test object in a saved or unsaved HTTPS cache; --name also needs runners:read |
metrics
| Command | Summary |
|---|---|
manage-runners metrics list | List the organization's Metrics connections, OTLP endpoints that runners send metrics to, and the runners using them; header values are never returned |
manage-runners metrics get | Get one Metrics connection by exact ID or name; header values are never returned |
manage-runners metrics create | Create a named Metrics connection; header values come from environment variables, stdin or a prompt |
manage-runners metrics update | Update a Metrics connection; endpoint or header changes recreate the VMs of active runners that use it |
manage-runners metrics delete | Delete a Metrics connection; its runners send to no connection and the active ones are recreated |
external-runner
| Command | Summary |
|---|---|
manage-runners external-runner list | List external runners: self-hosted runner servers that report metrics through the agent but that Manage Runners does not create or control |
manage-runners external-runner get | Get one external runner by exact ID or name, with its status, reinstall state and specifications |
manage-runners external-runner create | Add an external runner; then install the agent with install-command; --send-to by name also needs runners:read |
manage-runners external-runner update | Update an external runner's name, platform, labels, --dashboard or --send-to; the server gets changed settings only from a new install command |
manage-runners external-runner delete | Delete an external runner and end its agent's credential; the server keeps the agent until its uninstall command runs; --name also needs runners:read |
manage-runners external-runner install-command | Print a single-use, 15-minute install command for the agent; running it installs, updates or reinstalls the agent and replaces its credential; --name also needs runners:read |
product
| Command | Summary |
|---|---|
manage-runners product list | List runner products |
manage-runners product get | Get one product by exact ID |
manage-runners product locations | Show bookable datacenters and prices for a product |
provider
| Command | Summary |
|---|---|
manage-runners provider hetzner ssh-keys | Validate a Hetzner token, or with --hetzner-token use a saved one, and list SSH keys |
manage-runners provider hetzner tokens | List the organization's saved Hetzner tokens, by name and without values, for --hetzner-token |
manage-runners provider digitalocean ssh-keys | Validate a DigitalOcean token, or with --digitalocean-connection use a connected team, and list its SSH keys |
manage-runners provider digitalocean connections | List the organization's DigitalOcean connections, teams connected in the dashboard, for --digitalocean-connection |
profile
| Command | Summary |
|---|---|
manage-runners profile show | Show the current non-sensitive user profile |
subscription
| Command | Summary |
|---|---|
manage-runners subscription show | Show the current subscription and schedule entitlement |
manage-runners subscription plans | List available subscription plans |
org
| Command | Summary |
|---|---|
manage-runners org list | List your organizations with role and default marker |
manage-runners org use | Store the organization for the profile's organization-scoped commands, or clear it |
Global flags
These flags work with every command.
--agent[=true|false] agent mode: JSON and non-interactive
--api-url string API origin; must match the selected profile
--credential-store string credential store: keyring|file, also via $MANAGE_RUNNERS_CREDENTIAL_STORE; file keeps only a scoped, expiring PAT in a 0600 file, never your password or 2FA secret (default "keyring")
--json[=true|false] emit JSON
--no-color[=true|false] disable color output
--non-interactive[=true|false] disable prompts
--org string organization id or name for runner, schedule, cache, metrics, subscription and provider commands; overrides the profile's organization
--output string output format: human|json|jsonl (default "human")
--profile string configured API profile
--request-id string request ID sent to the API
--timeout duration maximum command duration (for example 30s)
--token-env string named PAT environment variable for this invocation; overrides $MANAGE_RUNNERS_TOKEN; nothing is stored