jenkins-cli

Capabilities

Debug your builds, the agent way

Discover jobs, read build status, and find out why a build failed — with output a coding agent can act on.

Discover jobs

job list maps jobs, folders and multibranch branches with their type and status; job get shows parameters, health and last-build pointers.

Why did it fail?

build stages shows which Pipeline stage broke, build tests --failed-only the failing cases, and build changes the commits that went in.

Console logs

build log reads a console snapshot. For monitoring, pin the build number before --follow and set a host deadline and output budget; --timeout bounds each request.

Map before terrain

job list returns a compact, ?tree=-shaped view, so an agent sees the shape before pulling a full job or a large console log.

Trigger & stop

job build kicks off a build (with --param), build stop aborts one — each with --dry-run preview and read-only gating.

Agent-first output

JSON by default, with structured errors — categories, exit codes and recovery next_steps a coding agent can branch on.

No footguns

Human job paths map to Jenkins URLs, the color field becomes a stable status, and timestamps come back as an ISO instant plus a relative phrase.

Multiple servers

kubectl-style named contexts in one config file. Switch the current server, or override per command with --use-context.

Secure credentials

Your API token lives in the OS keychain, with a per-user DPAPI fallback on Windows and a 0600 fallback on macOS/Linux — never in the config file. Env vars for headless use.

Install

Up and running in a minute

Install with npm, then finish setup in two steps — deploy the Skill, then turn on shell completion.

install

# recommended — fetches the prebuilt binary for your platform
npm install -g @angelmsger/jenkins-cli

Other methods — go install, a source build, or a prebuilt binary from the Releases page — are in the README.

Then finish setup:

1 · Companion Skill

A jenkins Skill is embedded in the binary. It detects your coding agents — Claude Code, Codex, Cursor and ten more — and installs for each one found:

$ jenkins-cli skill install
# Re-run after CLI upgrades, then reload the agent context.

2 · Shell completion

Completes subcommands and flag values. Load it once:

$ source <(jenkins-cli completion bash)

Quick start

Configure once, then debug the build

Set up a server, find the job, then drill into why the build is red.

a typical session

# interactive setup, then verify connectivity
$ jenkins-cli config init --pretty
$ jenkins-cli doctor

# discover jobs, then look at one
$ jenkins-cli job list
$ jenkins-cli job get my-team/my-app

# select the failure, then reuse its number (example: 128)
$ jenkins-cli build get my-app lastFailed
$ jenkins-cli build stages my-app 128
$ jenkins-cli build tests my-app 128 --failed-only
$ set -o pipefail
$ jenkins-cli build log my-app 128 | tail -n 80

# preview and perform an authorized trigger
$ jenkins-cli job build my-app --param BRANCH=main --dry-run
$ jenkins-cli job build my-app --param BRANCH=main --allow-writes
# use queue.queue_id, then executable.number (example values)
$ jenkins-cli queue get 77
$ jenkins-cli build get my-app 129