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 prints raw, grep-able console output; --follow streams a running build to completion via Jenkins' progressive log.

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

An jenkins Skill is embedded in the binary. It detects your coding agent — Claude Code, Codex — and installs for each:

$ jenkins-cli skill install

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

# why is the latest build red?
$ jenkins-cli build get my-app lastFailed
$ jenkins-cli build stages my-app lastFailed
$ jenkins-cli build tests my-app lastFailed --failed-only
$ jenkins-cli build log my-app lastFailed | tail -n 80

# trigger a build and watch it (writes; preview first)
$ jenkins-cli job build my-app --param BRANCH=main --dry-run
$ jenkins-cli build log my-app --follow