CLI reference

hookci [global flags] <command> [arguments]

hookci is one binary for two jobs: a daemon (agent, connect, doctor, upgrade) that runs on build hosts, and a local toolkit (detect, init, validate, run, status, logs) that works without a hub. Install it with the steps in Install the agent.

An unknown command prints unknown command "x" and exits with code 2.

Global flags

Global flags go before the command. After the command they are an error.

hookci --isolation none -v run

agent

hookci agent [--state-dir DIR | --installation ID]

Runs the daemon: holds the WebSocket to the hub, accepts triggers and runs jobs. Systemd runs it for you as hookci-agent@<installation-id>, see The agent service.

The agent needs an agent.json written by connect. If group or others can read it, it refuses to start and tells you to chmod 600 it. It exits 0 on SIGINT or SIGTERM. A revoked agent exits 3 with agent revoked: run hookci connect with a new pair token, and an agent rejected as too old exits 4. If the hub does not support the agent’s protocol version, the agent retries after one hour.

connect

hookci connect <pair-token> [--hub URL] [--name NAME] [--state-dir DIR] [--force] [--no-service]

Redeems a pair token, saves the agent credential, checks the connection with the hub and starts the service. Pair tokens start with hc_pair_, are single use and expire after 15 minutes. Run it as root, because it writes under /var/lib/hookci.

sudo hookci connect hc_pair_EXAMPLE
sudo hookci connect hc_pair_EXAMPLE --name ci-runner-2
sudo hookci connect hc_pair_EXAMPLE --hub https://ci.example.com

$ sudo hookci connect hc_pair_EXAMPLE --name ci-runner-2
Connected to https://ci.webuno.io as ci-runner-2 (agent ag_01JD3W)
Started hookci-agent@48213907.service

build-host recording
$ sudo hookci connect hc_pair_EXAMPLE --name ci-runner-2
Connected to https://ci.webuno.io as ci-runner-2 (agent ag_01JD3W)
Started hookci-agent@48213907.service

Illustration. Pairing a host. The token and IDs are examples.

Without --force, an existing agent in the state directory is detected before the token is redeemed, so a refused pair does not use up the token. After writing agent.json (mode 0600) it enables and starts hookci-agent@<installation-id>, or restarts it if it was already running. If the unit is missing it tells you to run the installer. With --no-service it prints the systemctl enable --now command to run yourself. Walkthrough: Pair an agent.

detect

hookci detect [dir] [--json]

Prints the config HookCI would use for dir (default: the current directory) as YAML, with detection notes as a comment at the top. It writes no files.

It recognizes Node (npm, pnpm, yarn, bun, plus Turborepo tasks), Go, Rust and Python projects, and adds services for a Docker Compose file. If a .hookci.yml exists it prints a note on stderr that the file takes precedence. Output samples are in Run checks locally.

Exit codes: 0 on success, 2 for a bad directory, 3 when nothing was detected (no checks detected: add .hookci.yml (run hookci init)).

init

hookci init [dir] [--force]

Writes <dir>/.hookci.yml from detection and prints wrote <path>.

Without --force, an existing file exits with code 2. When detection finds nothing, init writes a skeleton with a single test job that fails until you set its command, and prints a warning to edit the jobs.

validate

hookci validate [--self-hosted] [--json] [path]

Checks a config file, by default .hookci.yml, and prints ok: <path> (N jobs) when it is valid. Diagnostics go to stderr.

Exit codes: 0 valid, 2 the config has errors, 4 the file could not be loaded. The rules behind each diagnostic are in the config reference.

run

hookci [global flags] run [job]

Runs the committed HEAD of the git repository around the current directory, using the .hookci.yml at HEAD, or detection when there is none. The run is recorded as a local event with trusted policy. Uncommitted changes are not included.

Progress lines are printed with a timestamp, and a failed job prints the tail of its log and its reason. Annotations are printed as path:line level message, at most 10 per job. Colors are used on a terminal and turned off when NO_COLOR is set. Ctrl-C cancels the run with the reason interrupted by signal.

sudo hookci run
sudo hookci -v run test
hookci --isolation none run lint

With the default isolation, run needs root and systemd-run. Otherwise it stops and suggests --isolation none for local development. One process at a time can use a state directory.

Exit codes: 0 the run succeeded, 1 it failed (hookci: run failed: job test failed on stderr), 2 not a git repository, invalid config or an unknown job (unknown job "x" (jobs: a, b)), 3 no checks found, 4 internal error.

status

hookci [--state-dir DIR] status [run] [--json]

Without arguments, lists the last 20 runs with the columns ID REPO REF SHA STATE AGE DURATION. With a run ID, lists its jobs with NAME STATE EXIT DURATION REASON.

A state directory with no agent.json or database yet simply has no runs. An unknown run ID prints run <id> not found and exits 2. For an agent installed as a service, use --state-dir /var/lib/hookci/<installation-id> and sudo.

logs

hookci [--state-dir DIR] logs <run> [job|setup] [-f]

Prints the setup log and then each job’s log, each under a ==> name <== header. Name a job, or setup, to print just that log.

An unknown job exits with code 2. Logs are files at <state-dir>/runs/<run>/logs/<job>.log.

doctor

hookci doctor [--hub URL] [--state-root DIR] [--json]

Runs checks on the host and its path to the hub, and prints a table of STATUS CHECK DETAIL with a fix: line under each warning or failure. Statuses are pass, warn and fail.

Exit code 1 if any check fails, otherwise 0. Warnings do not fail the run.

upgrade

sudo hookci upgrade [--version vX.Y.Z] [--check] [--allow-downgrade] [--refresh-trust-root]

Verifies the release signature and archive digest, replaces the binary atomically and restarts running agents. Linux only, and root is required except for --check. Details and examples: Upgrade and uninstall.

Exit codes

Exit codes 3 and 4 from agent are in RestartPreventExitStatus in the shipped unit, so systemd does not restart the agent after them.

Environment variables