Jenkins CLI (jk)

jk is a GitHub CLI–style interface for Jenkins controllers. It provides modern, scriptable workflows for developers and operators.

Dependency Check

Before executing any jk command, verify the CLI is installed:

bash
1jk --version

If the command fails or jk is not found, install it using one of these methods:

Only proceed with jk commands after confirming installation succeeds.

Authentication

bash
1# Login with credentials
2jk auth login https://jenkins.example.com --username alice --token <API_TOKEN>
3
4# Login with custom context name
5jk auth login https://jenkins.example.com --name prod --username alice --token <TOKEN>
6
7# Login with TLS options
8jk auth login https://jenkins.example.com --username alice --token <TOKEN> --insecure
9jk auth login https://jenkins.example.com --username alice --token <TOKEN> --ca-file /path/to/ca.pem
10
11# Check auth status (active context)
12jk auth status
13
14# Logout from a context
15jk auth logout              # Logout from active context
16jk auth logout prod         # Logout from specific context

Options for auth login:

• --name — Context name (defaults to hostname)
• --username — Jenkins username
• --token — API token
• --insecure — Skip TLS verification
• --proxy — Proxy URL
• --ca-file — Custom CA bundle
• --set-active — Set as active context (default: true)
• --allow-insecure-store — Allow encrypted file fallback

Contexts

Contexts store controller URLs and credentials for easy switching:

bash
1# List contexts (* = active)
2jk context ls
3
4# Switch active context
5jk context use prod-jenkins
6
7# Remove a context
8jk context rm staging

Environment: JK_CONTEXT overrides active context.

Quick Command Reference

Job Discovery

bash
1# Search across folders
2jk search --job-glob '*deploy*' --limit 10
3
4# Search in specific folder
5jk search --folder team/services --job-glob '*api*'
6
7# Filter by run results
8jk search --job-glob '*' --filter result=FAILURE --since 7d
9
10# With parameter filters
11jk search --job-glob '*/deploy-*' --filter param.ENV=production

Job Operations

bash
1# List jobs in root
2jk job ls
3
4# List jobs in folder (positional or flag)
5jk job ls team/app
6jk job ls --folder team/app
7
8# View job details
9jk job view team/app/pipeline

Run Management

Listing Runs

bash
1# List recent runs
2jk run ls team/app/pipeline
3
4# Limit results
5jk run ls team/app/pipeline --limit 50
6
7# Filter runs
8jk run ls team/app/pipeline --filter result=SUCCESS
9jk run ls team/app/pipeline --filter result=FAILURE --since 7d
10
11# Filter by parameters
12jk run ls team/app/pipeline --filter param.ENV=staging
13
14# Include queued builds
15jk run ls team/app/pipeline --include-queued
16
17# Group by parameter
18jk run ls team/app/pipeline --group-by param.ENV --agg last
19
20# With metadata for agents
21jk run ls team/app/pipeline --json --with-meta
22
23# Pagination
24jk run ls team/app/pipeline --cursor <cursor-from-previous>

Starting Runs

bash
1# Start a run
2jk run start team/app/pipeline
3
4# Start with parameters
5jk run start team/app/pipeline -p BRANCH=main -p ENV=staging
6
7# Start and follow logs
8jk run start team/app/pipeline --follow
9
10# Start, wait for completion (no log streaming)
11jk run start team/app/pipeline --wait --timeout 10m
12
13# Get only the result
14jk run start team/app/pipeline --follow --result
15
16# Fuzzy job matching
17jk run start deploy --fuzzy

Viewing Runs

bash
1# View run details
2jk run view team/app/pipeline 128
3
4# Get only result status
5jk run view team/app/pipeline 128 --result
6
7# Exit with build result code
8jk run view team/app/pipeline 128 --exit-status
9
10# Wait for completion
11jk run view team/app/pipeline 128 --wait --timeout 5m
12
13# Show summary
14jk run view team/app/pipeline 128 --summary

Other Run Commands

bash
1# View run parameters
2jk run params team/app/pipeline
3
4# Cancel a run
5jk run cancel team/app/pipeline 128
6jk run cancel team/app/pipeline 128 --mode term
7jk run cancel team/app/pipeline 128 --mode kill
8
9# Rerun a build (with same parameters)
10jk run rerun team/app/pipeline 128
11jk run rerun team/app/pipeline 128 --follow

Logs

bash
1# View console log (snapshot)
2jk log team/app/pipeline 128
3
4# Stream live logs
5jk log team/app/pipeline 128 --follow
6
7# Custom poll interval
8jk log team/app/pipeline 128 --follow --interval 2s
9
10# Plain output (no decorations)
11jk log team/app/pipeline 128 --plain

Artifacts

bash
1# List artifacts
2jk artifact ls team/app/pipeline 128
3
4# Download all artifacts
5jk artifact download team/app/pipeline 128
6
7# Download with pattern filter
8jk artifact download team/app/pipeline 128 --pattern "**/*.jar"
9jk artifact download team/app/pipeline 128 -p "reports/**/*.xml"
10
11# Output directory
12jk artifact download team/app/pipeline 128 -o ./artifacts/
13
14# Allow empty result (no error if no matches)
15jk artifact download team/app/pipeline 128 -p "*.log" --allow-empty

Test Results

bash
1# View test report
2jk test report team/app/pipeline 128
3
4# JSON output
5jk test report team/app/pipeline 128 --json

Credentials

bash
1# List credentials (system scope)
2jk cred ls
3
4# List folder-scoped credentials
5jk cred ls --scope folder --folder team/app
6
7# Create secret text
8jk cred create-secret --id my-secret --secret "value"
9jk cred create-secret --id my-secret --secret "value" --description "API key"
10
11# Create from stdin
12echo "secret-value" | jk cred create-secret --id my-secret --from-stdin
13
14# Folder-scoped credential
15jk cred create-secret --id my-secret --secret "value" --scope folder --folder team/app
16
17# Delete credential (system scope only)
18jk cred rm my-secret

Node Management

bash
1# List nodes
2jk node ls
3
4# Cordon node (mark temporarily offline)
5jk node cordon agent-01
6jk node cordon agent-01 --message "Maintenance"
7
8# Uncordon node (bring back online)
9jk node uncordon agent-01
10
11# Remove node
12jk node rm agent-01

Queue Management

bash
1# List queued items
2jk queue ls
3
4# Cancel queued item
5jk queue cancel <item-id>

Plugin Management

bash
1# List installed plugins
2jk plugin ls
3
4# Install plugin (prompts for confirmation)
5jk plugin install docker-workflow
6
7# Install without confirmation
8jk plugin install docker-workflow --yes
9
10# Install specific version
11jk plugin install docker-workflow@1.26
12
13# Enable/disable plugin
14jk plugin enable docker-workflow
15jk plugin disable docker-workflow

Output Modes

All commands support structured output:

bash
1# JSON output
2jk run ls team/app --json
3
4# YAML output
5jk run ls team/app --yaml
6
7# Filter with jq expression
8jk run ls team/app --json --jq '.items[0].number'
9
10# Go template
11jk run ls team/app --json --template '{{range .items}}{{.number}}{{end}}'
12
13# Quiet mode (minimal output)
14jk run start team/app --quiet

Global Options

• -c, --context <name> — Use specific context
• --json — JSON output
• --yaml — YAML output
• --format json|yaml — Output format
• --jq <expr> — Filter JSON with jq expression
• -t, --template <tmpl> — Format with Go template
• -q, --quiet — Suppress non-essential output

Environment Variables

• JK_CONTEXT — Override active context
• JK_QUIET — Equivalent to --quiet (any value enables)

Exit Codes

With --follow or --wait, build results use additional codes:

References

• Full command reference: See references/commands.md