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.
Before you start
Section titled “Before you start”- Install the CLI and sign in with
champrep auth login. - 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.
Which farm account
Section titled “Which farm account”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:
champrep rf accounts lschamprep 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.
Commands
Section titled “Commands”| Command | Purpose |
|---|---|
champrep rf accounts ls | List the workspaces you can act in, your role, and whether each has a farm account. |
champrep rf accounts show | Show the farm account: state, who it bills, jobs at once, and the monthly credit ceiling. |
champrep rf connections ls | List the code host connections with their state and running, held and pooled jobs. --include-deleted, --limit (1-100). |
champrep rf pools ls | List 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_ID | Show one pool, its limits, timeout, and figures for the current cycle. |
champrep rf pools create | Add a pool to a connection. Requires --connection, --name and --class; also --isolation, --max-concurrent, --min-idle, --timeout. |
champrep rf pools update POOL_ID | Change --name, --max-concurrent, --min-idle or --timeout, or --pause / --resume the pool. |
champrep rf usage | Credits 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 ls | List jobs, newest first, including waiting, held and refused ones. --state running,held, --pool ID, --billed-to-me, --limit (1-200). |
Machine classes and limits
Section titled “Machine classes and limits”| Option | Values |
|---|---|
--class | cpu-2, cpu-4, cpu-8, arm64-2, arm64-4, build-4 |
--isolation | shared_hardened (default) or tenant_dedicated |
--max-concurrent | Jobs at once, 0 to 500 |
--min-idle | Warm runners kept ready, 0 to 50 |
--timeout | Job 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.
Examples
Section titled “Examples”See where your jobs run and how busy the pools are:
champrep rf connections lschamprep rf pools lschamprep rf pools show pol_01HZX9K4Add a pool for image builds and pause it for maintenance:
champrep rf pools create --connection con_01HZX7 --name Builds \ --class build-4 --max-concurrent 4 --timeout 2h --yeschamprep rf pools update pol_01HZX9K4 --pause --yeschamprep rf pools update pol_01HZX9K4 --resume --max-concurrent 8 --yesCheck what you used this period and last month:
champrep rf usagechamprep rf usage --period 2026-10Find jobs that are waiting or held:
champrep rf jobs ls --state waiting,heldConfirmation and scripting
Section titled “Confirmation and scripting”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" }.
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 -.
What stays in the web app
Section titled “What stays in the web app”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.
Errors you may see
Section titled “Errors you may see”| Message | What 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.