Skip to content
Documentation

Runner Farm commands

champrep runner-farm, or its short alias champrep rf, manages CHAMPREP Runner Farm from your terminal: your farm accounts, the code host connections, the runner pools and their machine classes, the credits and minutes you used, and the jobs the farm ran. It acts as you, with your normal CLI sign-in, so your role in the account and your plan apply exactly as in the Runner Farm web app.

  1. Install the CLI and sign in with champrep auth login.
  2. Your plan must include Runner Farm, and the workspace needs a farm account. Create the account and add connections in the Runner Farm web app at https://runners.champrep.com.

You may act in more than one farm account: your own, and an organization’s or a team’s. List them, then pick one with --workspace:

Terminal window
champrep rf accounts ls
champrep rf pools ls --workspace organization:65f0c0ffee0000000000abcd

--workspace takes the KEY column of accounts ls: personal, organization:<id> or team:<id>. Without it, the farm picks the account the same way the web app does: your organization’s or team’s account when it has one, otherwise your own.

CommandPurpose
champrep rf accounts lsList the workspaces you can act in, your role, and whether each has a farm account.
champrep rf accounts showShow the farm account: state, who it bills, jobs at once, and the monthly credit ceiling.
champrep rf connections lsList the code host connections with their state and running, held and pooled jobs. --include-deleted, --limit (1-100).
champrep rf pools lsList pools with machine class, busy slots, waiting and held jobs. --connection ID, --state active|paused|draining|deleted, --search, --include-deleted, --limit (1-200).
champrep rf pools show POOL_IDShow one pool, its limits, timeout, and figures for the current cycle.
champrep rf pools createAdd a pool to a connection. Requires --connection, --name and --class; also --isolation, --max-concurrent, --min-idle, --timeout.
champrep rf pools update POOL_IDChange --name, --max-concurrent, --min-idle or --timeout, or --pause / --resume the pool.
champrep rf usageCredits for the current billing period (included, bought, used, left) and minutes and credits per machine class for this month or --period YYYY-MM.
champrep rf jobs lsList jobs, newest first, including waiting, held and refused ones. --state running,held, --pool ID, --billed-to-me, --limit (1-200).
OptionValues
--classcpu-2, cpu-4, cpu-8, arm64-2, arm64-4, build-4
--isolationshared_hardened (default) or tenant_dedicated
--max-concurrentJobs at once, 0 to 500
--min-idleWarm runners kept ready, 0 to 50
--timeoutJob timeout from 15m to 6h, for example 90m or 2h

Your plan decides which classes, isolation levels and limits you may use. A pool that went above the plan after a downgrade shows above plan in pools ls.

See where your jobs run and how busy the pools are:

Terminal window
champrep rf connections ls
champrep rf pools ls
champrep rf pools show pol_01HZX9K4

Add a pool for image builds and pause it for maintenance:

Terminal window
champrep rf pools create --connection con_01HZX7 --name Builds \
--class build-4 --max-concurrent 4 --timeout 2h --yes
champrep rf pools update pol_01HZX9K4 --pause --yes
champrep rf pools update pol_01HZX9K4 --resume --max-concurrent 8 --yes

Check what you used this period and last month:

Terminal window
champrep rf usage
champrep rf usage --period 2026-10

Find jobs that are waiting or held:

Terminal window
champrep rf jobs ls --state waiting,held

pools create and pools update ask before they change anything. Answer y on a terminal, or pass --yes (-y) in a script. Without a terminal and without --yes the command refuses and changes nothing. pools create carries an idempotency key, so the CLI’s automatic retry after a network error never adds two pools.

Add --json to print what Runner Farm returned. usage --json prints { "balance": …, "usage": …, "period": "YYYY-MM" }.

Terminal window
champrep rf pools ls --json | jq -r '.pools[] | "\(.id) \(.state) \(.busy)/\(.max_concurrent)"'

Credit figures follow your role: Owners and Billing managers always see them; Admins and Members see them only when the account shows credits to them. Hidden figures show as -.

For safety, the CLI cannot reach anything that issues, replaces or tests a credential. Use the Runner Farm web app to:

  • create a farm account or move one to an organization;
  • add a connection, pair a self-managed CHAMPREP Code, or replace a runner token or connector secret;
  • delete or restore connections and pools, close the account, and change the cost visibility setting.
MessageWhat to do
payment required … (INSUFFICIENT_CREDITS)The balance cannot pay for the machine class. Buy credits or wait for the next period; the CLI suggests CHAMPREP Billing. Exit code 1.
payment required … (PENDING_INVOICE), (WORKSPACE_NOT_BILLED)The account has an unpaid invoice or its plan ended. An Owner or Billing manager settles it in CHAMPREP Billing.
needs your web session … (INTERACTIVE_SESSION_REQUIRED)Only you, signed in to the web app, can take this decision. Do it at https://runners.champrep.com.
not allowed for your role … (ROLE_REQUIRED)Your role in the workspace does not allow the change. Ask an Owner or Admin.
not allowed for your role … (WORKSPACE_NOT_AVAILABLE)--workspace names a workspace you are not in. Check champrep rf accounts ls.
not available to your account …Your plan does not include Runner Farm or this class or limit.
rate limited … (CAPACITY_EXHAUSTED)Every slot is busy. Wait and try again; buying credits does not help.
not found …No such pool or connection in this account, or the workspace has no farm account yet.

These refusals exit with code 1, also with --json. rate limited (CAPACITY_EXHAUSTED) exits 5; see the exit codes.