GitHub - addozhang/jk: Pipeline-native Jenkins CLI

A Pipeline-native CLI for Jenkins.

jk is for the day-to-day pipeline operator: inspect a job, trigger a build, watch it, tail its log, answer an input step — all from the terminal, all driven by the Jenkins URL you'd paste into a browser.

What jk is

• URL-as-identity: every command takes a Jenkins URL; the host (and optional context path) picks the stored credentials.
• Stable, self-owned schema: yaml (default), json, or raw. Output begins with schemaVersion: "1"; breaking changes bump the version.
• Pipeline-aware: understands wfapi (stage tree, parallel branches, pending input).
• Scripting-friendly: --watch returns the build result via exit code; -o json pipes cleanly into jq.
• Agent-ready: ships an optional skill that teaches AI coding agents how to use jk safely from the terminal.

What jk is not

• Not a general Jenkins administration tool — no plugin/agent/credentials-store management.
• Not a Freestyle CLI — Pipeline (declarative or scripted) is the supported job type.
• Not a Jenkinsfile linter or editor.

Disclaimer

Install

Homebrew (macOS / Linux)

brew install addozhang/tap/jk

Requires the tap repo addozhang/homebrew-tap to be accessible.

go install

go install github.com/addozhang/jk/cmd/jk@latest

Requires Go 1.22+. The Go toolchain fetches the module directly from GitHub; no proxy is needed for a public repo. If you forked into a private repo, set GOPRIVATE=github.com/addozhang/* first.

Download a pre-built binary

Download jk_<version>_<os>_<arch>.tar.gz (Windows builds ship as .zip) from the Releases page, extract, and move jk onto your PATH.

Quick start

# 1. Add credentials for your Jenkins host
jk auth add https://jenkins.example.com

# Verify the authenticated Jenkins identity
jk auth whoami https://jenkins.example.com

# 2. Inspect a pipeline
jk pipeline info https://jenkins.example.com/job/my-folder/job/my-pipeline

# 3. Trigger a build and watch it finish
jk build trigger https://jenkins.example.com/job/my-folder/job/my-pipeline \
    -p ENV=staging --watch

# 4. Tail the console log of the latest build
jk build logs https://jenkins.example.com/job/my-folder/job/my-pipeline/lastBuild -f

# 5. Respond to a paused input step with parameter values
jk build input https://jenkins.example.com/job/deploy/42 proceed \
    -p ENV=prod -p DRY_RUN=false

# 6. Cancel a running build
jk build cancel https://jenkins.example.com/job/deploy/42 --wait

# 7. Inspect the parameter values a build was triggered with
jk build params https://jenkins.example.com/job/my-pipeline/lastSuccessfulBuild

# 8. Re-trigger a specific build with its recorded parameters
jk build rebuild https://jenkins.example.com/job/my-pipeline/42

AI agent skill

jk includes a companion skill for AI coding agents at skills/jk-jenkins-cli/. The skill is a concise operating guide for agents that need to inspect Jenkins failures, trigger and watch builds, read stage-scoped logs, or handle pending Pipeline input steps with the right safety checks.

Use it when an agent has terminal access and needs to work with Jenkins through jk. The skill emphasizes:

• using Jenkins URLs as the unit of identity;
• preferring -o json for machine-readable inspection;
• inspecting status and stages before reading logs;
• using --stage for focused log reads;
• checking pendingInput and --input-id before acting on input steps;
• avoiding unsupported Jenkins administration tasks.

First-time setup

1. Add a host credential

jk auth add https://jenkins.example.com
# Token: (paste your Jenkins API token — input is hidden)

Credentials are stored in ~/.config/jk/credentials (mode 0600, TOML format). Tokens are never printed by any jk command.

To keep the API token out of the credentials file entirely, store it in the OS keyring with --secure-storage (or set JK_SECURE_STORAGE=1):

jk auth add --secure-storage https://jenkins.example.com

The file then records only the username plus a secure marker for the host; the token is fetched from the keyring on every request and is removed again by jk auth remove. Re-running jk auth add for the same host without the flag migrates the credential back to file storage. jk auth list reports which hosts are keyring-backed via the secure field (see docs/schema.md §3.1).

Verify which Jenkins identity those credentials select without printing the token:

jk auth whoami https://jenkins.example.com

The command also accepts job URLs and preserves Jenkins context paths.

Rebuild a specific run

jk build rebuild <build-url> reads the recorded parameters from the selected numeric or permalink build and triggers the same pipeline again:

jk build rebuild https://jenkins.example.com/job/deploy/42

Before triggering, jk verifies that every recorded parameter is still defined by the pipeline. Jenkins-redacted password or credential values cannot be recovered; use jk build trigger -p KEY=VALUE when explicit replacement values are required. Rebuild does not reproduce workspaces, environment variables, SCM revisions, or plugin-specific state.

Context-path-scoped credentials

jk auth add accepts an optional context path, so several Jenkins instances reachable on the same host — distinguished only by a reverse-proxy prefix — can each hold their own credential:

jk auth add https://ci.example.com/team-a   # instance under /team-a
jk auth add https://ci.example.com/team-b   # instance under /team-b
jk auth add https://ci.example.com          # host-only fallback (optional)

The stored key is scheme://host[:port] plus the normalised context path — the segments before the first /job/; a bare host or a pure /job/... URL stores no path. When a command runs, jk selects the most specific entry whose key is a path-prefix of the request URL, falling back to the host-only entry when no context path matches. Matching honours segment boundaries, so a /team-a entry never captures a request to /team-amber.

2. Custom CA / self-signed certificates

If your Jenkins is behind a TLS proxy with a self-signed certificate, point SSL_CERT_FILE at the PEM bundle:

export SSL_CERT_FILE=/etc/ssl/my-ca-bundle.pem
jk pipeline info https://jenkins.example.com/job/...

Pass --insecure only as a last resort; it disables all certificate verification and prints a warning.

URL conventions

jk treats the Jenkins URL as the primary identifier. Every URL shape that Jenkins produces is accepted:

Any of the seven Jenkins build permalinks may appear in the build-position slot in place of a numeric build number: lastBuild, lastCompletedBuild, lastSuccessfulBuild, lastUnsuccessfulBuild, lastFailedBuild, lastStableBuild, lastUnstableBuild. Jenkins resolves them server-side; jk output always records the resolved numeric buildNumber.

Jenkins instances deployed under a URL context path (a reverse-proxy mount such as /jenkins, or a multi-tenant prefix like /domain) are supported: any path segments before the first /job/ are preserved and replayed against the server. A context path can also scope stored credentials, so multiple instances on one host can each hold their own token — see Context-path-scoped credentials under First-time setup.

Normalisation rules:

• Trailing slashes are stripped.
• Default ports (:80 for http, :443 for https) are dropped when looking up credentials, so https://jenkins.example.com and https://jenkins.example.com:443 resolve to the same credential entry.
• The credential lookup key is scheme://host[:non-default-port] plus an optional context path. A request resolves to the most specific stored key that is a segment-boundary path-prefix of the URL, falling back to a host-only entry — so a single host can serve several credentialed instances while a plain host entry still covers every path beneath it.

Scripting with jk

JSON output

# Get just the build result
jk build status https://host/job/pipeline/42 -o json | jq -r '.result'

# Find any pending input
jk build status https://host/job/pipeline/lastBuild -o json | jq '.pendingInput'

Exit codes

When --watch is not used, jk exits 0 on success or 10 on any jk-level error (bad URL, auth failure, network problem, TLS verification failure, CSRF crumb failure, malformed Jenkins response). The stderr message identifies which.

When --watch is used with jk build trigger, or --wait is used with jk build cancel, the exit code reflects the build's terminal state:

jk build trigger https://host/job/pipeline --watch
echo $?   # 0..4 = build result; 10 = jk-level failure

Schema pinning

All structured output begins with schemaVersion: "1". Scripts should assert on this value:

schema=$(jk pipeline info https://host/job/foo -o json | jq -r '.schemaVersion')
[ "$schema" = "1" ] || { echo "unexpected schema $schema"; exit 1; }

Breaking changes will increment the version; additive changes (new fields, new enum values tagged experimental) will not. See docs/schema.md for the full field reference and versioning policy.

Release notes

v0.8.0 — archived artifact downloads

New features

• jk build artifacts <build-url> lists files archived by a Jenkins build in stable YAML or JSON output.
• jk build artifact <build-url> <relative-path> --destination <file> downloads one artifact with exact metadata membership validation.
• jk build artifacts fetch <build-url> --directory <dir> downloads all artifacts sequentially while preserving their archived paths.

Safety and tooling improvements

• Artifact content streams to disk through same-directory temporary files and is installed only after a complete download.
• Bulk downloads reject traversal, absolute paths, and symlinked parent paths; existing files require explicit --force.
• Artifact downloads follow external Artifact Manager redirects without forwarding Jenkins credentials to unrelated hosts.

v0.7.0 — auth identity and build rebuild

New features

• jk auth whoami <url> verifies the Jenkins identity selected by stored credentials without exposing the API token. Root URLs, job URLs, and context-path-mounted instances are supported.
• jk build rebuild <build-url> re-triggers a specified numeric or permalink build with its recorded parameters, without requiring the Jenkins Rebuild plugin.

Safety and tooling improvements

• Rebuild validates recorded parameters against the pipeline's current definitions and refuses redacted, removed, or unsupported values before triggering.
• Empty integration-test directories are skipped correctly, and the complete test, vet, and lint gates pass.

v0.6.0 — build cancel

New features

• jk build cancel <build-url> stops a running build via the Jenkins /stop endpoint — the same action as the UI Stop button. The build is marked ABORTED after any post { always {} } cleanup blocks run.
• --wait flag polls the build until it reaches a terminal state and exits with the build-result exit code (3 for ABORTED). The poll correctly passes through the brief PENDING_INPUT window that occurs while Jenkins is processing the stop request, rather than treating it as a terminal state.
• Accepts build permalinks (lastBuild, etc.) in the build-position slot, consistent with all other build commands.

v0.5.1 — error message fix

Bug fixes

• Build commands now report Build not found: <url> (with a suggestion to check the build number) instead of the misleading Pipeline not found message when Jenkins returns HTTP 404 for a build URL.

v0.2.0 — input-step parameters and status correctness

New features

• jk build input <url> proceed now accepts repeatable -p KEY=VALUE flags to submit parameter values to a paused input step. @PATH loads the value from a file. Values are validated client-side against the pending input's declared shape (CHOICE / BOOLEAN / STRING / TEXT / PASSWORD) before any HTTP call; invalid values exit 10 with a message that names the offending parameter and lists the valid choices.
• pendingInput.parameters in jk build status output is promoted from experimental to stable. Scripts can rely on the field name and Parameter shape.

Behavior changes (bug fixes)

• Finished builds no longer report state: PENDING_INPUT. A non-building build is always DONE, regardless of whether a stale pendingInput action marker is still attached to Jenkins's core /api/json response.
• Live paused builds now populate pendingInput.id, pendingInput.message, and pendingInput.parameters correctly. The data is sourced from /wfapi/pendingInputActions rather than the core actions[] array, which only carries an _class marker.

See docs/schema.md §3.7 and §3.9 for the full field reference and endpoint wire-format details.

Develop

make build             # build ./bin/jk
make test              # unit + integration with -race
make test-e2e          # end-to-end (requires `make e2e-up` first)
make lint              # golangci-lint v2, zero warnings required
make release-snapshot  # local cross-platform snapshot via GoReleaser
make help              # full target list

Requires Go 1.22+ and golangci-lint v2.

Docs

• SPEC.md — engineering practice, tech stack, boundaries.
• openspec/ — change management; behavior changes go through OpenSpec.
• docs/schema.md — output schema contract (field reference, enum catalog, versioning policy).