Jenkins

Jenkins Skill

Use this skill to operate Jenkins controllers through the packaged launcher and local CLI runtime.

Runtime and execution

Always run the packaged launcher through ${JENKINS_SKILL_DIR} so it works from the user's current working directory:

• macOS/Linux: ${JENKINS_SKILL_DIR}/bin/jenkins
• Windows: ${JENKINS_SKILL_DIR}\bin\jenkins.cmd

${JENKINS_SKILL_DIR} is a documentation placeholder, not a guaranteed shell environment variable. Do not execute ${JENKINS_SKILL_DIR}/bin/jenkins or ${JENKINS_SKILL_DIR}\bin\jenkins.cmd literally when the host has not resolved that placeholder. Resolve BIN to a real launcher path once before the first CLI call. When the host leaves the placeholder unresolved, first use the active installed skill directory for this pack or any host-provided installed skill directory when available. Only fall back to standalone workspace installs such as .claude/skills/jenkins/bin/jenkins or .Codex/skills/jenkins/bin/jenkins when the plugin-installed path is not available. Do not call node dist/cli.js directly. Do not start with version, doctor, or --help when the user already asked for a concrete Jenkins read or write task, unless the launcher itself is failing. When exact command syntax is unclear, use the packaged launcher with <group> --help or <group> <action> --help before guessing flags. The launcher first reuses a compatible system Node runtime when available (currently Node >= 20), and only downloads the required runtime into the local cache when the machine does not already have one.

Provider-specific caveats

You MUST run BIN config get before any job, build, queue, or system command. Do NOT offer the user a choice to skip the config step. If that call returns ok: false, CONFIG_ERROR, or stored config was not found, stop the workflow and guide the user through config set before attempting any Jenkins business command. Use BIN config set --base-url <URL> --user <USER> --token <API_TOKEN> for first-time setup. Persisted config lives at ~/.config/jenkins-cli/config.json, following the same pattern as Bitbucket's ~/.config/bitbucket-cli/config.json. After config set, rerun BIN config get, confirm it succeeds, and only then rerun the original Jenkins read or write command. When config state is unknown, do not run config get in parallel with job, build, queue, or system commands.

Scope and boundaries

• Jenkins controller API only.
• CLI-mediated operations only.
• Do not call Jenkins REST endpoints directly from the skill layer.
• v1 authentication is username plus API token stored through config set.
• Treat --job and --folder as slash-separated Jenkins paths such as folder-a/service-build.

Deployment-related capabilities

The CLI supports these deployment-adjacent workflows out of the box:

Workflow	How
Verify build result	build get returns result (SUCCESS/FAILURE/UNSTABLE/ABORTED), duration, timestamp
Check build artifacts	build get returns artifacts array (may be empty for pipeline jobs)
Follow a deploy build	job build-with-params → queue get → build get + build console
Read deploy console	build console --job <path> --number <N> --tail 50 for recent output
Check last successful deploy	build get --job <path> --number lastSuccessfulBuild
Multi-branch pipeline builds	Use --job folder/repo/branch path format (e.g. SampleOrg/sample-service/master)
Job health	job get returns healthReport array with score and description

Known limitations for deployment workflows

• No Pipeline stage tracking: build get does not return per-stage status. Use build console with --tail to infer stage progress from log output.
• No artifact download: build get lists artifact file names but the CLI does not provide a download command.
• No environment variable or parameter readback: job get returns summary info only; build parameters are not exposed in the current API.
• No deployment environment mapping: Jenkins does not natively expose which environment a build deploys to; this must be inferred from job naming conventions or build parameters.
• No rollback command: Rollback must be implemented as a new build with previous version parameters.

Output and error handling expectations

• Prefer stable, structured CLI output that downstream agents can parse reliably.
• Distinguish read actions and write actions explicitly.
• For write failures, return explicit and actionable failure details; do not swallow errors.
• Never print or repeat the stored API token.

Error remediation table

When a CLI error matches a row below, you MUST apply the one-step recovery action exactly as stated. Do NOT substitute a generic multi-step explanation when the table provides a concise recovery. If the error persists after recovery, stop and report it to the user.

Error	Typical cause	Recovery action
401 Unauthorized	Stored API token is invalid or expired	Run BIN config set --base-url <URL> --user <USER> --token <NEW_TOKEN>, then BIN config get to confirm, then retry
403 Forbidden	User lacks permission on the target job/folder	Verify the job path with BIN job list or BIN job list --folder <parent>; switch to an authorized user via config set if needed
404 Not Found	Job path is wrong or the job does not exist on that controller	List available jobs with BIN job list or BIN job list --folder <parent> to find the correct path; correct the --job value and retry
Connection refused	Controller URL is wrong or Jenkins is down	Run BIN config get to check base-url; correct it with config set or confirm Jenkins is reachable at that URL
Timeout	Network latency or unresponsive controller	Retry once; if it fails again, ask the user to verify network connectivity to the controller URL

For config-level errors (CONFIG_ERROR, stored config was not found), see the Configuration flow in references/usage.md.

Quick reference — common operations

Use these directly without reading supporting files. BIN = the resolved launcher path for this session, not the literal ${JENKINS_SKILL_DIR} placeholder token.

Task	Command
Read config status	BIN config get
Store config	BIN config set --base-url <URL> --user <USER> --token <TOKEN>
List root jobs	BIN job list
List jobs in a folder	BIN job list --folder <path>
Read one job	BIN job get --job <path>
Trigger a job	BIN job build --job <path>
Trigger a parameterized job	BIN job build-with-params --job <path> --params-json '<JSON>'
Create a freestyle job	BIN job create --job <path> [--config-xml-file <path>]
Create a folder	BIN job create-folder --folder <path> [--config-xml-file <path>]
Create a multi-branch pipeline	BIN job create-multi-branch --job <path> --repo-url <url> [--credentials-id <id>]
Copy an existing job	BIN job copy --from <path> --to <path>
Read job config.xml	BIN job get-config --job <path>
Update job config.xml	BIN job reconfig --job <path> --config-xml-file <path>
Delete a job	BIN job delete --job <path>
Read one build	BIN build get --job <path> --number <N>
Read build console	BIN build console --job <path> --number <N> [--tail <lines>]
List queue items	BIN queue list
Read one queue item	BIN queue get --id <ID>
Cancel one queue item	BIN queue cancel --id <ID>
Read controller summary	BIN system info

Notes on build triggering:

• job build is for non-parameterized jobs.
• job build-with-params accepts exactly one of --params-json or --params-file.
• Trigger responses return the Jenkins queue location when Jenkins exposes it. Use queue get to follow the item until an executable number appears.
• After a queue item gets an executable build number, switch to build get or build console.

Notes on job creation:

• job create, job create-folder, and job create-multi-branch are write operations. Confirm the target path with the user before running them.
• When --config-xml-file is omitted, create and create-folder ship a minimal default config.xml; create-multi-branch instead requires --repo-url (with optional --credentials-id).
• job copy requires --from and --to to share the same parent folder; only the leaf segment may differ.
• All four creation actions hit Jenkins createItem with the user's API token; no separate CSRF crumb is required.

Notes on job lifecycle:

• job get-config returns the raw config.xml of a job. Use this to inspect or template a job's configuration before copying or reconfiguring.
• job reconfig replaces the entire config.xml of an existing job. It is a write operation — confirm the target with the user before running it. A common workflow is get-config → edit locally → reconfig.
• job delete permanently removes a job. It is a write operation — confirm the target with the user before running it.

Common command mistakes — There is no job_info or build start command. Use job get --job <path> to inspect a job and job build --job <path> to trigger a build. There is no job edit command; use job reconfig --job <path> --config-xml-file <path> to update a job's config.xml. Never invent or guess command names; if unsure, run <group> --help first.

Deployment-oriented quick reference

Task	Command
Check last completed build result	BIN build get --job <path> --number lastCompletedBuild
Check last successful build	BIN build get --job <path> --number lastSuccessfulBuild
Check last stable build	BIN build get --job <path> --number lastStableBuild
Read deploy log tail	BIN build console --job <path> --number <N> --tail 100
Trigger rollback build	BIN job build-with-params --job <path> --params-json '{"BRANCH":"<prev-branch>","VERSION":"<prev-version>"}'
Check if a build is still running	BIN build get --job <path> --number <N> → check building field
Read multi-branch pipeline build	BIN build get --job <folder>/<repo>/<branch> --number <N>
Check job health report	BIN job get --job <path> → read healthReport array

Capability Domain

Domain:

• ci

Provides:

• ci.config.get
• ci.config.set
• ci.job.get
• ci.job.trigger
• ci.build.get
• ci.build.console
• ci.queue.get
• provider-specific workflow helpers

Config check:

• jenkins config get

Supporting files

Read supporting files only when the condition matches — the quick reference tables above cover most invocations.

File	Read when
references/commands.md	User asks about an unfamiliar command, flag, or group not shown in the quick reference tables above
references/usage.md	Performing a write operation (build trigger, config set, queue cancel), or first-time setup / troubleshooting
examples/common-workflows.md	Executing a multi-step deployment sequence (e.g. trigger → queue poll → build check → console read), or when the user asks for an end-to-end walkthrough