Reference

CLI reference

jenkins-cli inspects Jenkins for a developer's debugging workflow: discover jobs and branches, read build status, logs, test failures and pipeline stages, and trigger or stop builds. It emits agent-friendly JSON with structured errors, and works with any Jenkins instance. AGENT NOTE: a companion Skill ("jenkins") carries the canonical usage, safety modes, and env setup and is the source of truth for driving this CLI. If you are an agent, load that Skill before composing commands. Check status with `jenkins-cli skill status`; install it with `jenkins-cli skill install`.

Generated from the command tree, so it always matches --help.

Global flags

Persistent flags accepted by every command.

Flag	Default	Description
`--allow-writes`	`false`	override read-only mode (defaults.read_only / JENKINS_CLI_READ_ONLY) for this invocation
`--base-url`		Jenkins server URL (overrides config), e.g. http://localhost:8080
`--config`		config directory (default ~/.angelmsger/jenkins)
`--fields`		comma-separated dot-path fields to keep
`--format, -f`		output format: json, table or ndjson
`--pretty`	`false`	human-friendly mode for interactive terminal use only (agents/scripts should omit): TUI in `config init`, colorized JSON elsewhere; errors without a TTY
`--timeout`		request timeout, e.g. 30s
`--use-context`		use a named context for this invocation
`--verbose, -v`	`false`	log request lines on stderr

jenkins-cli auth

jenkins-cli auth

jenkins-cli auth login

Store credentials for the active context (interactive)

jenkins-cli auth login

Prompts for your Jenkins username and API token (or password), verifies them against the server, and stores the secret in the OS keychain. Requires an interactive terminal; in CI / agent sandboxes set JENKINS_USER + JENKINS_TOKEN (or JENKINS_PASSWORD) instead.

jenkins-cli auth logout

Remove the stored credential for the active context

jenkins-cli auth logout

jenkins-cli auth status

Show the active identity and verify connectivity

jenkins-cli auth status

jenkins-cli build

Inspect builds: status, logs, stages, tests, changes

jenkins-cli build

A build is one run of a job. List a job's history, then drill into a build's result, console log, pipeline stages, test failures or SCM changes. A build reference is a number or a permalink keyword: last, lastSuccessful, lastFailed, lastCompleted, lastStable (default: last).

jenkins-cli build artifacts

List a build's archived artifacts

jenkins-cli build artifacts <path> [ref]

Returns the build's archived artifacts with a direct download URL for each.

jenkins-cli build changes

Show the SCM commits in a build

jenkins-cli build changes <path> [ref]

Returns the source-control changes a build picked up: commit id, author, message and affected paths. Works for both freestyle and pipeline jobs.

jenkins-cli build get

Get one build: result, timing, trigger cause

jenkins-cli build get <path> [ref]

Returns a build's result and status, when it started (absolute and relative) and how long it ran, which node it ran on, what triggered it, and any build parameters. ref defaults to the latest build.

jenkins-cli build list

List a job's recent builds (newest first)

jenkins-cli build list <path> [flags]

Returns a job's build history: number, status, start time (and how long ago), duration and what triggered each build. Use --limit to control how many builds come back.

Options

Flag	Default	Description
`--limit`	`20`	number of builds to return

jenkins-cli build log

Print a build's console output

jenkins-cli build log <path> [ref] [flags]

Prints the build's console log as plain text to stdout. Use --start to resume from a byte offset, or --follow to stream new output until the build finishes (Ctrl-C to stop). ref defaults to the latest build.

Options

Flag	Default	Description
`--follow`	`false`	stream new output until the build finishes (Ctrl-C to stop)
`--start`	`0`	start byte offset into the console log

Examples

  jenkins-cli build log my-app lastFailed
  jenkins-cli build log my-app --follow

jenkins-cli build stages

Show a Pipeline build's stage-by-stage status

jenkins-cli build stages <path> [ref]

Returns each Pipeline stage with its status and duration, so you can see exactly which stage failed. Applies to Pipeline / multibranch jobs only.

jenkins-cli build stop

Abort a running build (write)

jenkins-cli build stop <path> <ref> [flags]

Aborts the build at <path> #<ref>. With --dry-run, print the request that would be sent and exit. This is a write: it is blocked in read-only mode unless --allow-writes is given.

Options

Flag	Default	Description
`--dry-run`	`false`	print the request without stopping the build

jenkins-cli build tests

Show a build's test results

jenkins-cli build tests <path> [ref] [flags]

Returns the build's test totals plus the individual cases. Use --failed-only to keep just the failing cases (with their error details) — the high-signal view when triaging a red build.

Options

Flag	Default	Description
`--failed-only`	`false`	keep only failing test cases

jenkins-cli config

Set up and inspect configuration and contexts

jenkins-cli config

jenkins-cli config contexts

List configured contexts and which one is current

jenkins-cli config contexts

jenkins-cli config init

Interactively configure a context and store credentials

jenkins-cli config init [flags]

Collects a server URL, username and API token (or password), verifies them, then writes a named context plus the secret. With --pretty it runs an interactive TUI (requires a terminal); without it, a plain line-by-line wizard that also works over a pipe. When a configuration already exists, it first asks whether to edit a context, add a new one, or replace it all (skip the question with --context <name>). For fully headless setup, set JENKINS_URL / JENKINS_USER / JENKINS_TOKEN (or JENKINS_PASSWORD) instead.

Options

Flag	Default	Description
`--context`	`default`	name for the context to create or update (skips the edit/add/replace prompt)

Examples

  jenkins-cli config init --pretty   # interactive TUI (recommended)
  jenkins-cli config init             # plain line-by-line wizard (scripts, non-TTY)
  jenkins-cli config init --context prod   # add/update a named context directly

jenkins-cli config show

Show the resolved configuration with field provenance

jenkins-cli config show

jenkins-cli config use-context

Set the current context

jenkins-cli config use-context <name>

jenkins-cli doctor

Check configuration, credentials and connectivity

jenkins-cli doctor [flags]

Runs a quick health check: is a server configured, are credentials present, and can the server be reached and authenticated. Each check reports ok/failed so an agent can self-diagnose environment problems. It also reports whether a newer jenkins-cli release is available.

Options

Flag	Default	Description
`--no-update-check`	`false`	skip the check for a newer jenkins-cli release

Examples

  jenkins-cli doctor
  jenkins-cli doctor --no-update-check

jenkins-cli job

Discover jobs and trigger builds

jenkins-cli job

Jobs are the projects, folders and multibranch pipelines on the instance. `job list` is the discovery map; `job get` shows one job's detail (parameters, health, branch jobs, last-build pointers); `job build` triggers a build. Job paths are folder/job[/branch] — list to find the exact name before querying.

jenkins-cli job build

Trigger a build of a job (write)

jenkins-cli job build <path> [flags]

Starts a build of the job at <path>. Pass --param KEY=VALUE (repeatable) for a parameterized job. With --dry-run, print the request that would be sent and exit without triggering. This is a write: it is blocked in read-only mode unless --allow-writes is given.

Options

Flag	Default	Description
`--dry-run`	`false`	print the request without triggering the build
`--param`	`[]`	build parameter KEY=VALUE (repeatable)

Examples

  jenkins-cli job build my-folder/my-app
  jenkins-cli job build my-app --param BRANCH=main --param CLEAN=true
  jenkins-cli job build my-app --param BRANCH=main --dry-run

jenkins-cli job get

Get one job, including parameters and last-build pointers

jenkins-cli job get <path>

Returns a single job by path (folder/job[/branch]): its description, build parameters, health, last / lastSuccessful / lastFailed build pointers, and — for folders and multibranch projects — the child jobs (branches and PRs).

jenkins-cli job list

List jobs (the discovery map)

jenkins-cli job list [flags]

Lists jobs with their type, status and last-build snapshot. Pass --folder to list inside a folder — or a multibranch project, which lists its branch / PR jobs — and --depth to recurse nested containers. Each job's last_build carries its result, start time and duration, so one call shows every branch's build situation. Status is derived from Jenkins' color field (success / failure / unstable / building / disabled / not_built).

Options

Flag	Default	Description
`--depth`	`0`	recurse nested folders this many levels (0 = immediate children)
`--folder`		list jobs inside this folder, or branches of this multibranch project

jenkins-cli queue

Inspect and manage the build queue

jenkins-cli queue

The queue holds builds waiting to start. List it to see what is pending or blocked and why, inspect one item, or cancel a queued build before it runs.

jenkins-cli queue cancel

Cancel a queued build before it starts (write)

jenkins-cli queue cancel <id> [flags]

Removes a still-queued build by its queue id. With --dry-run, print the request that would be sent and exit. This is a write: it is blocked in read-only mode unless --allow-writes is given.

Options

Flag	Default	Description
`--dry-run`	`false`	print the request without cancelling

jenkins-cli queue get

Get one queue item

jenkins-cli queue get <id>

jenkins-cli queue list

List builds waiting in the queue

jenkins-cli queue list

jenkins-cli skill

Install the companion Skill for coding agents (Claude Code, Codex)

jenkins-cli skill

jenkins-cli skill install

Deploy the embedded Skill into a coding agent's skills directory

jenkins-cli skill install [flags]

Write the companion `jenkins` Skill — bundled inside this binary — into a coding agent's skills directory. With no flags it probes for installed agents (Claude Code, Codex) and installs into each one found. Re-run it after upgrading the CLI to refresh the Skill to the matching version.

Options

Flag	Default	Description
`--agent`	`[]`	target agents instead of auto-detecting (claude-code, codex)
`--dir`		explicit skills base directory; installs into <dir>/jenkins
`--project`	`false`	install into the project (./.claude/skills, ./.agents/skills) instead of $HOME

jenkins-cli skill path

Print where the Skill would be installed, and whether it is

jenkins-cli skill path [flags]

Options

Flag	Default	Description
`--agent`	`[]`	limit to specific agents (claude-code, codex)
`--dir`		explicit skills base directory
`--project`	`false`	use the project skills directories instead of $HOME

jenkins-cli skill show

Print the embedded SKILL.md to stdout

jenkins-cli skill show

jenkins-cli skill status

Report whether the companion Skill is loaded and installed

jenkins-cli skill status [flags]

Options

Flag	Default	Description
`--project`	`false`	check the project skills dirs (./.claude/skills, ./.agents/skills) instead of $HOME

jenkins-cli skill uninstall

Remove the companion Skill from a coding agent's skills directory

jenkins-cli skill uninstall [flags]

Delete a previously installed `jenkins` Skill. With no flags it probes for installed agents (Claude Code, Codex) and removes the Skill from each one found.

Options

Flag	Default	Description
`--agent`	`[]`	target agents instead of auto-detecting (claude-code, codex)
`--dir`		explicit skills base directory; removes <dir>/jenkins
`--project`	`false`	remove from the project (./.claude/skills, ./.agents/skills) instead of $HOME

jenkins-cli version

Print version information

jenkins-cli version