Skip to content

runnerctl

Command-line client for the runnerd daemon

The other commands are on runnerctl actions.

Show the memory and CPU budgets, every slot and what runs in it, the repositories, and why each queued job waits.

With –waiting-for, print nothing and answer in the exit code, for scripts: 0 when a queued job waits for it, 1 when none does, 2 when the daemon cannot be asked or the repository is not one it serves.

  • --waiting-for <WAITING_FOR>: Only answer whether a queued job waits for this
    • host-memory: The host’s memory beside its other programs, also behind an older job that waits for it
  • --repo <REPO>: With –waiting-for, only this repository’s jobs (owner/name)

List jobs, newest first

  • --repo <REPO>: Only this repository (owner/name)
  • --failed: Only jobs that concluded failure; same as –conclusion failure
  • --conclusion <CONCLUSION>: Only jobs with this conclusion, such as success, failure or cancelled
  • --state <STATE>: Only jobs in this state: queued, running, completed, lost or elsewhere
  • --since <SINCE>: Only jobs queued in the last 30m, 12h, 7d, 2w, …
  • --before <BEFORE>: Only jobs older than this job ID: the next page
  • --limit <LIMIT>: At most this many jobs [default: 50, at most 500]

Show one job: its timeline and wait, steps with their durations, and its CPU and what held it back, memory, network, disk writes and build cache

  • <ID>

Print a job’s log

  • <ID>
  • -f, --follow: Keep printing lines as they arrive, until the job’s record is final
  • --from <FROM>: Start at this line, 0-based

Live view of slots, running jobs and their steps, queued jobs with why each waits, and finished jobs.

Redraws in place on a terminal; otherwise prints one line per event.

Full-screen dashboard: CI’s health, the budget as lanes with each slot’s job, the queue with why each job waits, and what needs attention on one line; the jobs with search, filters and a timeline, insights, sizing and caches, the doctor’s checks, and each job’s steps, failure and folded log, with cancel and re-run.

Keys: 1-5 the views, tab and j/k to move, enter to open, / to search, ? for all. The mouse clicks and scrolls unless –no-mouse or RUNNERCTL_NO_MOUSE is set.

  • --no-mouse: Leave the mouse to the terminal: no clicks or wheel in the TUI, and the terminal’s own selection works. RUNNERCTL_NO_MOUSE set to anything but empty does the same

Show what the history says: what the job minutes would have cost on GitHub’s runners, jobs that got slower and stayed so, fail and pass on a re-run, run near their memory cap or miss the build cache, downloads slowed for want of memory, what jobs and the drive wrote, why each profile’s jobs queued, and how long each repository’s jobs wait this week against the last. One line per insight

  • --days <DAYS>: Days of history to read [default: 14, at most 90]
  • --digest: Show the last 24 hours instead: jobs finished and failed, new insights and the longest waits

Show the cache volumes, their sizes and limits, the build cache’s hits, and whether it serves GitHub Actions’ cache

  • --clean <VOLUME>: Empty this volume (a slot layer or a shared cache) instead; refused while a runner uses it

Show or check the daemon’s config

Print the config the daemon runs with, and its path

Check a config file against the daemon’s budget, as runnerd check-config does; without a file, the daemon’s own config

  • [FILE]

Check that the host can run runners. Runs runnerd doctor here when the daemon is not running

Open the web dashboard with a one-time login link, and print one for each of [web] origins

  • --no-open: Print the links instead of opening one. Over SSH they are printed anyway: a browser opened there would be the remote machine’s, and spend the link where nobody sits
  • --base <ORIGIN>: The address of a proxy in front of the dashboard to log in through instead, such as https://host.example.ts.net:8443, over [web] open. [web] origins need not be named here
  • --local: Open the dashboard on its loopback address, over [web] open
  • --qr: Print a QR code of a fresh link on each of [web] origins, or on --base, that signs a phone in within 5 minutes
  • --sign-out-all: Sign every browser out of the dashboard, with a new session secret
  • --socket <SOCKET>: The daemon’s API socket [default: $XDG_RUNTIME_DIR/runnerd.sock]
  • --json: Print the API’s JSON instead of text: the response type unchanged, one event per line for watch