jenkins-cli

Inspect Jenkins from your terminal — built for coding agents.

jenkins-cli lets coding agents (Claude Code and others) — and humans — inspect Jenkins for a developer's debugging workflow: discover jobs, folders and multibranch branches; read build status and history; and find out why a build failed — which pipeline stage broke, the failing test cases, the console log, and the SCM commits that went in. It can also trigger and stop builds. It works with any Jenkins instance, returns agent-friendly JSON with structured errors, and ships a companion Skill that teaches an agent how to use it.

📖 Documentation site: https://angelmsger.github.io/jenkins-cli/

$ jenkins-cli build get my-app lastFailed
{
  "number": 412, "result": "FAILURE", "status": "failure", "building": false,
  "started_at": "2026-06-16T09:14:02Z", "started_ago": "3h ago", "duration": "2m11s",
  "built_on": "linux-agent-2",
  "causes": [ { "description": "Started by GitHub push by alice", "user_id": "alice" } ]
}

Features

• The developer's debugging loop — job list / job get to discover, build list for history, build get for one build's result and timing, and then the why: build stages (which Pipeline stage failed), build tests --failed-only (the failing cases), build log (console output), build changes (the commits).
• Map before terrain — job list returns a compact, ?tree=-shaped view (name, type, status, last-build pointer) so an agent sees the shape before pulling a full job or a large console log.
• The CLI owns the footguns — human job paths (folder/job/PR-12) are converted to Jenkins' /job/.../job/... form; the color field becomes a stable status; epoch-millisecond timestamps come back as both an ISO instant and a relative phrase; build refs accept lastFailed & friends.
• Agent-friendly output — JSON by default, a {items, has_more} list envelope, --format json|table|ndjson, and --fields projection to spend minimal context. build log prints raw, grep-able console text.
• Errors as navigation — every failure is structured (category/code/hint/next_steps) and mapped to a stable exit code, so a script or agent can branch and self-recover.
• Layered write safety — the three writes (job build, build stop, queue cancel) support --dry-run, honour a session read-only posture, and require --allow-writes to override it; CSRF crumbs are handled automatically.
• Flexible configuration — CLI flags, environment variables, a .env file, a YAML config file, or an interactive wizard; multiple named server contexts; secrets stored in the OS keychain.
• Companion Skill — a jenkins Skill, embedded in the binary, that guides coding agents through the CLI.

Scope: a developer's inspection workflow over jobs and builds, plus the two high-frequency writes (trigger / stop a build) and queue cancel. Jenkins' control plane — creating and configuring jobs, credentials, nodes, Configuration-as-Code — is on the roadmap; the read-only wrapper and --dry-run gates are already wired so those write methods drop in cleanly.

Installation

1. Install the CLI — npm (recommended)

npm install -g @angelmsger/jenkins-cli

npm downloads the prebuilt binary for your platform, verifies its SHA-256 checksum, and keeps upgrades one npm update -g @angelmsger/jenkins-cli away.

go install github.com/angelmsger/jenkins-cli/cmd/jenkins-cli@latest   # go 1.24+
make install                                                          # from a source checkout

Or download a prebuilt binary from the Releases page. The full installation guide covers every method, shell completion and the companion Skill.

2. Deploy the companion Skill

The jenkins Skill is embedded in the binary; it teaches your coding agent (Claude Code, Codex, Cursor, Agents (shared), Gemini CLI, GitHub Copilot, OpenCode, Continue, Windsurf, Grok Build, Pi, Kilo Code, and Roo Code) how to drive the CLI. skill install probes for installed agents and installs into each one found:

jenkins-cli skill install            # auto-detect; install for each agent found
jenkins-cli skill install --agent codex
jenkins-cli skill status             # compare loaded, installed, embedded versions
jenkins-cli skill uninstall          # remove it again

After upgrading the CLI, re-run skill install and reload the agent context.

3. Enable shell completion (optional)

source <(jenkins-cli completion bash)                     # bash, current shell
jenkins-cli completion zsh > "${fpath[1]}/_jenkins-cli"   # zsh, persistent

fish and PowerShell are supported too — see jenkins-cli completion --help.

This is the beginning of the README. Read the rest at the original. Read the full README ↗