Manage Runners
Documentation menu

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

CommandSummary
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

CommandSummary
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

CommandSummary
manage-runners setup skill Install or manage the embedded agent skill

auth

CommandSummary
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

CommandSummary
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

CommandSummary
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

CommandSummary
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

CommandSummary
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

CommandSummary
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

CommandSummary
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

CommandSummary
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

CommandSummary
manage-runners profile show Show the current non-sensitive user profile

subscription

CommandSummary
manage-runners subscription show Show the current subscription and schedule entitlement
manage-runners subscription plans List available subscription plans

org

CommandSummary
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