runnerctl
Command-line client for the runnerd daemon
The other commands are on runnerctl actions.
runnerctl status
Section titled “runnerctl status”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 thishost-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)
runnerctl jobs
Section titled “runnerctl jobs”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]
runnerctl job <ID>
Section titled “runnerctl job <ID>”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>
runnerctl logs <ID>
Section titled “runnerctl logs <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
runnerctl watch
Section titled “runnerctl watch”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.
runnerctl tui
Section titled “runnerctl tui”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
runnerctl insights
Section titled “runnerctl insights”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
runnerctl caches
Section titled “runnerctl caches”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
runnerctl config
Section titled “runnerctl config”Show or check the daemon’s config
runnerctl config show
Section titled “runnerctl config show”Print the config the daemon runs with, and its path
runnerctl config check [FILE]
Section titled “runnerctl config check [FILE]”Check a config file against the daemon’s budget, as runnerd check-config does; without a file, the daemon’s own config
[FILE]
runnerctl doctor
Section titled “runnerctl doctor”Check that the host can run runners. Runs runnerd doctor here when the daemon is not running
runnerctl web
Section titled “runnerctl web”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 ashttps://host.example.ts.net:8443, over[web] open.[web] originsneed 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
Every command
Section titled “Every command”--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 forwatch