### Install Plugins

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/references/commands.md

Install one or more plugins, with options to skip confirmation or specify versions.

```bash
jk plugin install docker-workflow        # Install (prompts for confirm)
jk plugin install docker-workflow --yes  # Skip confirmation
jk plugin install docker-workflow@1.26   # Specific version
jk plugin install plugin1 plugin2        # Multiple plugins
```

--------------------------------

### Install jk via Scoop

Source: https://github.com/avivsinai/jenkins-cli/blob/main/README.md

Use the Scoop package manager to install the binary on Windows.

```powershell
scoop bucket add avivsinai https://github.com/avivsinai/scoop-bucket
scoop install jk
```

--------------------------------

### Jenkins CLI Development Setup

Source: https://github.com/avivsinai/jenkins-cli/blob/main/README.md

Install git hooks for pre-commit checks, build the binary, run unit tests, linters, and security checks as part of the development workflow.

```bash
# First-time setup
make pre-commit-install  # Install git hooks (gitleaks, formatting, etc.)

# Standard workflow
make build      # Build the binary
make test       # Run unit tests
make lint       # Run linters
make security   # Run security checks (gitleaks + pre-commit)
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/avivsinai/jenkins-cli/blob/main/CONTRIBUTING.md

Commands to verify Go version and install necessary development tools on macOS.

```bash
# Go 1.25+
go version  # should report go1.25.x

# Dev tools (macOS)
brew install golangci-lint gitleaks pre-commit
```

--------------------------------

### Install jk via Homebrew

Source: https://github.com/avivsinai/jenkins-cli/blob/main/README.md

Use Homebrew to install the binary on macOS or Linux.

```bash
brew install avivsinai/tap/jk
```

--------------------------------

### Install Jenkins CLI

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/SKILL.md

Installation commands for various platforms.

```bash
brew install avivsinai/tap/jk
```

```bash
scoop bucket add avivsinai https://github.com/avivsinai/scoop-bucket && scoop install jk
```

```bash
go install github.com/avivsinai/jenkins-cli/cmd/jk@latest
```

--------------------------------

### Install jk via Go

Source: https://github.com/avivsinai/jenkins-cli/blob/main/README.md

Install the latest or a specific version of the tool directly using the Go toolchain.

```bash
# Install latest version
go install github.com/avivsinai/jenkins-cli/cmd/jk@latest

# Or install specific version
go install github.com/avivsinai/jenkins-cli/cmd/jk@v0.0.29
```

--------------------------------

### Install jk AI Skill via Marketplace

Source: https://github.com/avivsinai/jenkins-cli/blob/main/README.md

Install the jk skill through the marketplace plugin system.

```bash
/plugin marketplace add avivsinai/skills-marketplace
/plugin install jk@avivsinai-marketplace
```

--------------------------------

### Install jk AI Skill via skild registry

Source: https://github.com/avivsinai/jenkins-cli/blob/main/README.md

Install the jk skill using the skild registry.

```bash
npx skild install @avivsinai/jk -t claude -y
```

--------------------------------

### POST /run/start

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/SKILL.md

Starts a new run for a specified pipeline.

```APIDOC
## POST /run/start

### Description
Initiates a new build for the pipeline, optionally with parameters and follow-up options.

### Method
POST

### Endpoint
jk run start <pipeline-path>

### Parameters
#### Request Body
- **-p** (string) - Optional - Key-value pairs for build parameters (e.g., BRANCH=main).
- **--follow** (boolean) - Optional - Stream logs after starting.
- **--wait** (boolean) - Optional - Wait for completion.
- **--timeout** (string) - Optional - Timeout duration for wait.
```

--------------------------------

### Configure Pre-commit Hooks

Source: https://github.com/avivsinai/jenkins-cli/blob/main/CONTRIBUTING.md

Install the pre-commit hooks for the repository.

```bash
make pre-commit-install
```

--------------------------------

### Install jk AI Skill via Vercel Skills CLI

Source: https://github.com/avivsinai/jenkins-cli/blob/main/README.md

Install the jk skill for AI coding assistants using the skills CLI.

```bash
npx skills add avivsinai/jenkins-cli -g -y
```

--------------------------------

### Trigger and Monitor Builds

Source: https://context7.com/avivsinai/jenkins-cli/llms.txt

Start builds with parameters, follow logs, or wait for completion.

```bash
# Trigger a simple build
jk run start team/app/pipeline

# Trigger with parameters
jk run start team/app/deploy \
  -p VERSION=1.2.3 \
  -p ENVIRONMENT=staging \
  -p DEPLOY=true

# Trigger and follow logs until completion
jk run start team/app/pipeline --follow

# Trigger and wait for completion (no log streaming)
jk run start team/app/pipeline --wait --timeout 30m

# Get only the final result
jk run start team/app/pipeline --follow --result
# Output: SUCCESS

# Quiet mode - outputs only the build number (useful for scripts)
jk run start team/app/pipeline -q
# Output: 128

# JSON output after completion
jk run start team/app/deploy \
  -p VERSION=1.2.3 \
  --follow --json
```

--------------------------------

### Install Plugin XML Payload

Source: https://github.com/avivsinai/jenkins-cli/blob/main/docs/spec.md

The `jk plugin install` command posts this XML payload to `/pluginManager/installNecessaryPlugins`. The `shortName` and `version` should be specified.

```xml
<install plugin="shortName@version"/>
```

--------------------------------

### Manage Jenkins Plugins

Source: https://github.com/avivsinai/jenkins-cli/blob/main/docs/spec.md

List installed plugins, their versions, and available updates. Install, enable, or disable plugins with confirmation gates.

```bash
jk plugin ls
```

```bash
jk plugin install <plugin-name>
```

```bash
jk plugin enable <plugin-name>
```

```bash
jk plugin disable <plugin-name>
```

--------------------------------

### Manage plugins

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/SKILL.md

List, install, enable, and disable Jenkins plugins.

```bash
# List installed plugins
jk plugin ls

# Install plugin (prompts for confirmation)
jk plugin install docker-workflow

# Install without confirmation
jk plugin install docker-workflow --yes

# Install specific version
jk plugin install docker-workflow@1.26

# Enable/disable plugin
jk plugin enable docker-workflow
jk plugin disable docker-workflow
```

--------------------------------

### Verify Jenkins CLI Installation

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/SKILL.md

Check the installed version of the CLI to ensure compatibility with specific commands.

```bash
jk --version
```

--------------------------------

### List Plugins

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/references/commands.md

Display all currently installed Jenkins plugins.

```bash
jk plugin ls                             # List installed plugins
```

--------------------------------

### Manually Install jk AI Skill

Source: https://github.com/avivsinai/jenkins-cli/blob/main/README.md

Manually copy the skill files into the local configuration directory.

```bash
git clone https://github.com/avivsinai/jenkins-cli.git
cp -r jenkins-cli/.claude/skills/jk ~/.claude/skills/
```

--------------------------------

### Agent Discovery Patterns

Source: https://github.com/avivsinai/jenkins-cli/blob/main/CLAUDE.md

Examples of using the Jenkins CLI for discovering and querying Jenkins jobs and runs.

```bash
jk search --job-glob '*pattern*' --json for cross-folder job discovery
```

```bash
jk run ls <job> --filter result=SUCCESS --since 7d --json for filtered run queries
```

```bash
jk run params <job> to inspect parameter metadata before triggering builds
```

```bash
jk help --json for programmatic command enumeration
```

--------------------------------

### Manage Jenkins runs

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/SKILL.md

Commands for listing, starting, viewing, and managing build runs.

```bash
# List recent runs
jk run ls team/app/pipeline

# Limit results
jk run ls team/app/pipeline --limit 50

# Filter runs
jk run ls team/app/pipeline --filter result=SUCCESS
jk run ls team/app/pipeline --filter result=FAILURE --since 7d

# Filter by parameters
jk run ls team/app/pipeline --filter param.ENV=staging

# Include queued builds
jk run ls team/app/pipeline --include-queued

# Group by parameter
jk run ls team/app/pipeline --group-by param.ENV --agg last

# With metadata for agents
jk run ls team/app/pipeline --json --with-meta

# Pagination
jk run ls team/app/pipeline --cursor <cursor-from-previous>
```

```bash
# Start a run
jk run start team/app/pipeline

# Start with parameters
jk run start team/app/pipeline -p BRANCH=main -p ENV=staging

# Start and follow logs
jk run start team/app/pipeline --follow

# Start, wait for completion (no log streaming)
jk run start team/app/pipeline --wait --timeout 10m

# Get only the result
jk run start team/app/pipeline --follow --result

# Fuzzy job matching
jk run start deploy --fuzzy
```

```bash
# View run details
jk run view team/app/pipeline 128

# Get only result status
jk run view team/app/pipeline 128 --result

# Exit with build result code
jk run view team/app/pipeline 128 --exit-status

# Wait for completion
jk run view team/app/pipeline 128 --wait --timeout 5m

# Show summary
jk run view team/app/pipeline 128 --summary
```

```bash
# View run parameters
jk run params team/app/pipeline

# Cancel a run
jk run cancel team/app/pipeline 128
jk run cancel team/app/pipeline 128 --mode term
jk run cancel team/app/pipeline 128 --mode kill

# Rerun a build (with same parameters)
jk run rerun team/app/pipeline 128
jk run rerun team/app/pipeline 128 --follow
```

--------------------------------

### Enable or Disable Plugins

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/references/commands.md

Toggle the active status of an installed plugin.

```bash
jk plugin enable docker-workflow
jk plugin disable docker-workflow
```

--------------------------------

### Start Pipeline Runs

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/references/commands.md

Triggers a new pipeline run with support for parameters, log following, waiting, and fuzzy matching.

```bash
jk run start team/app/pipeline           # Trigger a run
jk run start team/app/pipeline -p BRANCH=main -p ENV=staging

# Follow logs until completion
jk run start team/app/pipeline --follow
jk run start team/app/pipeline --follow --follow-interval 500ms

# Wait for completion (no log streaming)
jk run start team/app/pipeline --wait
jk run start team/app/pipeline --wait --interval 2s --timeout 10m

# Get only the result
jk run start team/app/pipeline --follow --result

# Fuzzy job matching
jk run start deploy --fuzzy
jk run start deploy --fuzzy --non-interactive

# Quiet mode (outputs only build number)
jk run start team/app/pipeline --quiet
```

--------------------------------

### Manage Jenkins CLI Extensions

Source: https://github.com/avivsinai/jenkins-cli/blob/main/docs/spec.md

Install and manage exec-based extensions for the Jenkins CLI. Extensions can be installed from a repository or listed and removed.

```bash
jk extension install <repo>
```

```bash
jk extension ls
```

```bash
jk extension rm <extension-name>
```

--------------------------------

### GET /log

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/SKILL.md

Retrieves console logs for a specific run.

```APIDOC
## GET /log

### Description
Fetches the console log for a specific run, with options to stream live logs.

### Method
GET

### Endpoint
jk log <pipeline-path> <run-id>

### Parameters
#### Query Parameters
- **--follow** (boolean) - Optional - Stream live logs.
- **--interval** (string) - Optional - Poll interval for streaming.
- **--plain** (boolean) - Optional - Output without decorations.
```

--------------------------------

### Plugin Commands

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/references/commands.md

Commands for managing Jenkins plugins, including listing, installing, enabling, and disabling them.

```APIDOC
## jk plugin ls

### Description
List all installed Jenkins plugins.

### Method
GET (conceptual)

### Endpoint
Not applicable (CLI command)

## jk plugin install

### Description
Install one or more Jenkins plugins.

### Method
POST (conceptual)

### Endpoint
Not applicable (CLI command)

### Parameters
#### Path Parameters
- **docker-workflow** (string) - Required - The name of the plugin to install. Can specify multiple plugin names.
- **docker-workflow@1.26** (string) - Optional - Specify a particular version of the plugin.

#### Query Parameters
- **-y, --yes** (boolean) - Optional - Skip the confirmation prompt before installation.

## jk plugin enable

### Description
Enable a Jenkins plugin.

### Method
PUT (conceptual)

### Endpoint
Not applicable (CLI command)

### Parameters
#### Path Parameters
- **docker-workflow** (string) - Required - The name of the plugin to enable.

## jk plugin disable

### Description
Disable a Jenkins plugin.

### Method
PUT (conceptual)

### Endpoint
Not applicable (CLI command)

### Parameters
#### Path Parameters
- **docker-workflow** (string) - Required - The name of the plugin to disable.
```

--------------------------------

### Trigger Jenkins Build with Parameters

Source: https://github.com/avivsinai/jenkins-cli/blob/main/docs/spec.md

Trigger Jenkins builds with parameters and optionally follow the build progress. Use this to start builds programmatically or with specific configurations.

```bash
jk run <job-path> --param <key>=<value> --follow
```

--------------------------------

### Build jk from Source

Source: https://github.com/avivsinai/jenkins-cli/blob/main/README.md

Clone the repository and build the binary locally using make.

```bash
git clone https://github.com/avivsinai/jenkins-cli.git
cd jenkins-cli
make build   # produces ./bin/jk
```

--------------------------------

### View Run Details

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/references/commands.md

Retrieves details for a specific build, including options to wait for completion or output summaries.

```bash
jk run view team/app/pipeline 128        # View run details

# Get only result
jk run view team/app/pipeline 128 --result

# Exit with build result code
jk run view team/app/pipeline 128 --exit-status

# Wait for completion
jk run view team/app/pipeline 128 --wait
jk run view team/app/pipeline 128 --wait --interval 2s --timeout 5m

# Show human-readable summary
jk run view team/app/pipeline 128 --summary
```

--------------------------------

### Manage credentials

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/SKILL.md

Create, list, and delete system or folder-scoped credentials.

```bash
# List credentials (system scope)
jk cred ls

# List folder-scoped credentials
jk cred ls --scope folder --folder team/app

# Create secret text
jk cred create-secret --id my-secret --secret "value"
jk cred create-secret --id my-secret --secret "value" --description "API key"

# Create from stdin
echo "secret-value" | jk cred create-secret --id my-secret --from-stdin

# Folder-scoped credential
jk cred create-secret --id my-secret --secret "value" --scope folder --folder team/app

# Delete credential (system scope only)
jk cred rm my-secret
```

--------------------------------

### GET /jk/api/credentials

Source: https://github.com/avivsinai/jenkins-cli/blob/main/docs/api.md

Lists available Jenkins credentials.

```APIDOC
## GET /jk/api/credentials

### Description
Lists credentials stored in Jenkins.

### Response
#### Success Response (200)
- **items** (array) - List of credential objects
- **nextCursor** (string|null) - Pagination cursor

#### Response Example
{
  "items": [
    {
      "id": "slack-token",
      "type": "secretText",
      "scope": "folder"
    }
  ],
  "nextCursor": null
}
```

--------------------------------

### Verify Development Environment

Source: https://github.com/avivsinai/jenkins-cli/blob/main/CONTRIBUTING.md

Run security checks, linting, and tests to ensure the environment is correctly configured.

```bash
make security  # runs: gitleaks, pre-commit
make lint
make test
```

--------------------------------

### List and Filter Runs

Source: https://context7.com/avivsinai/jenkins-cli/llms.txt

Query build history using filters, grouping, and metadata selection.

```bash
# List recent runs for a job
jk run ls team/app/pipeline --limit 10

# Filter by result and time
jk run ls team/app/pipeline \
  --filter result=SUCCESS \
  --since 7d \
  --limit 5

# Filter by parameter values
jk run ls Helm.Chart.Deploy \
  --filter param.CHART_NAME~nova \
  --filter result=SUCCESS \
  --since 7d

# Group by parameter and get last run per group
jk run ls team/app/deploy \
  --group-by param.CHART_NAME \
  --agg last \
  --json

# Include queued builds in output
jk run ls team/app/pipeline --include-queued

# Get metadata for agent consumption
jk run ls team/app/deploy \
  --with-meta \
  --select parameters \
  --limit 5 \
  --json
```

--------------------------------

### GET /jk/run/params

Source: https://github.com/avivsinai/jenkins-cli/blob/main/docs/api.md

Discovers parameters for a specific Jenkins job.

```APIDOC
## GET /jk/run/params

### Description
Retrieves parameter definitions for a job, including type and metadata.

### Response
#### Success Response (200)
- **jobPath** (string) - The path of the job
- **source** (string) - Discovery path (config, runs, or auto)
- **parameters** (array) - List of parameter objects

#### Response Example
{
  "jobPath": "team/app/main",
  "source": "runs",
  "parameters": [
    {
      "name": "CHART_NAME",
      "type": "string",
      "isSecret": false,
      "sampleValues": ["nova"],
      "frequency": 1
    }
  ]
}
```

--------------------------------

### Build and Test Commands

Source: https://github.com/avivsinai/jenkins-cli/blob/main/CLAUDE.md

Standard make commands for building, testing, linting, and formatting the project. Use `JK_E2E_DISABLE=1 make test` to skip end-to-end tests during unit testing.

```bash
make build          # Build binary to ./bin/jk (injects version via ldflags)
make test           # Run unit tests (228+ tests)
make lint           # Run golangci-lint
make e2e            # Run end-to-end tests (requires Docker)
make fmt            # Format code with gofmt
```

```bash
# Run a single test
go test -run TestFunctionName ./path/to/package
```

```bash
# Skip e2e tests during unit testing
JK_E2E_DISABLE=1 make test
```

```bash
# E2E with Colima on macOS (if Docker is unreachable)
colima start --network-address
export DOCKER_HOST="unix://$HOME/.colima/default/docker.sock"
make e2e
```

--------------------------------

### View and Stream Build Logs

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/references/commands.md

Commands for retrieving build console logs, including options for live streaming and plain text output.

```bash
jk log team/app/pipeline 128             # View console log (snapshot)
jk log team/app/pipeline 128 --follow    # Stream live logs
jk log team/app/pipeline 128 --follow --interval 2s
jk log team/app/pipeline 128 --plain     # No decorations
```

--------------------------------

### GET /jk/log

Source: https://github.com/avivsinai/jenkins-cli/blob/main/docs/api.md

Retrieves a snapshot of the logs for a specific job run.

```APIDOC
## GET /jk/log

### Description
Returns a log snapshot. If the run is still executing, the log may be truncated.

### Response
#### Success Response (200)
- **jobPath** (string) - The path of the job
- **build** (integer) - Build number
- **status** (string) - Run status
- **result** (string) - Build result
- **log** (string) - Log content
- **truncated** (boolean) - Whether the log is incomplete

#### Response Example
{
  "jobPath": "team/app/main",
  "build": 128,
  "status": "completed",
  "result": "SUCCESS",
  "log": "Started by user Jane Doe...",
  "truncated": false
}
```

--------------------------------

### GET /jk/api/status

Source: https://github.com/avivsinai/jenkins-cli/blob/main/docs/api.md

Performs a plugin status handshake to verify compatibility between the client and server.

```APIDOC
## GET /jk/api/status

### Description
Performs a plugin status handshake to verify compatibility between the client and server. Clients must provide specific headers for version and feature negotiation.

### Method
GET

### Endpoint
/jk/api/status

### Parameters
#### Request Headers
- **X-JK-Client** (string) - Required - The semantic version of the client
- **X-JK-Features** (string) - Required - CSV list of supported features

### Response
#### Success Response (200)
- **version** (string) - API version
- **features** (array) - List of supported features
- **minClient** (string) - Minimum required client version
- **recommendedClient** (string) - Recommended client version

#### Response Example
{
  "version": "1.0.0",
  "features": ["runs", "credentials", "events"],
  "minClient": "0.3.0",
  "recommendedClient": "1.0.0"
}
```

--------------------------------

### GET /jk/api/runs

Source: https://github.com/avivsinai/jenkins-cli/blob/main/docs/api.md

Lists Jenkins build runs with support for filtering, grouping, and pagination.

```APIDOC
## GET /jk/api/runs

### Description
Returns a paginated list of build runs. Supports aggregation and metadata when requested.

### Method
GET

### Endpoint
/jk/api/runs

### Response
#### Success Response (200)
- **items** (array) - List of build run objects.
- **nextCursor** (string) - Opaque cursor for pagination.
- **groups** (array) - Aggregated data groups (optional).
- **metadata** (object) - Metadata regarding filters and parameters (optional).

#### Response Example
{
  "items": [
    {
      "id": "team/app/main/128",
      "number": 128,
      "status": "completed"
    }
  ],
  "nextCursor": "g2wAAAABbQAAAGp..."
}
```

--------------------------------

### Check Local Build Version

Source: https://github.com/avivsinai/jenkins-cli/blob/main/CONTRIBUTING.md

Verify the version of the locally built binary.

```bash
./bin/jk version
```

--------------------------------

### List Credentials

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/references/commands.md

Display system or folder-scoped credentials.

```bash
jk cred ls                               # List system credentials
jk cred ls --scope system                # Explicit system scope
jk cred ls --scope folder --folder team/app
```

--------------------------------

### List and Download Build Artifacts

Source: https://context7.com/avivsinai/jenkins-cli/llms.txt

Use 'jk artifact ls' to list artifacts and 'jk artifact download' to retrieve them. Supports filtering with glob patterns and downloading to a specified output directory.

```bash
# List all artifacts for a build
jk artifact ls team/app/pipeline 128
```

```bash
# Get artifact list as JSON
jk artifact ls team/app/pipeline 128 --json
```

```bash
# Download all artifacts
jk artifact download team/app/pipeline 128 -o ./artifacts
```

```bash
# Download with glob pattern filter
jk artifact download team/app/pipeline 128 \
  -p "**/*.xml" \
  -o ./test-reports
```

```bash
# Download specific artifact types
jk artifact download team/app/pipeline 128 \
  -p "coverage/*.html" \
  -o ./coverage-reports
```

```bash
# Allow empty results (no error if no matches)
jk artifact download team/app/pipeline 128 \
  -p "**/*.log" \
  -o ./logs \
  --allow-empty
```

--------------------------------

### GET /jk run params

Source: https://github.com/avivsinai/jenkins-cli/blob/main/docs/spec.md

Discovers parameter metadata for a specific Jenkins job path.

```APIDOC
## GET jk run params

### Description
Surfaces parameter metadata for scripts and agents by parsing configuration or inferring from recent runs.

### Method
GET

### Endpoint
jk run params <jobPath>

### Parameters
#### Path Parameters
- **jobPath** (string) - Required - The path to the Jenkins job.

#### Query Parameters
- **--source** (string) - Optional - Source for parameter discovery: config, runs, or auto (default).

### Response
#### Success Response (200)
- **jobPath** (string) - The job path.
- **source** (string) - The source used for discovery.
- **parameters** (array) - List of parameter definitions including name, type, default, isSecret, sampleValues, and frequency.

### Response Example
{
  "jobPath": "team/app",
  "source": "auto",
  "parameters": [
    {
      "name": "CHART_NAME",
      "type": "string",
      "sampleValues": ["nova", "gamma"],
      "frequency": 1
    }
  ]
}
```

--------------------------------

### Retrieve metadata hints

Source: https://github.com/avivsinai/jenkins-cli/blob/main/docs/agent-cookbook.md

Fetch available filters and parameters for a job to assist with adaptive prompts.

```bash
jk run ls team/api/deploy --with-meta --json --limit 0
```

```python
import json
import subprocess

meta = json.loads(subprocess.run([
    "jk", "run", "ls", "team/api/deploy",
    "--with-meta", "--json", "--limit", "0"
], check=True, capture_output=True, text=True).stdout)["metadata"]
```

--------------------------------

### GET /jk/events/stream

Source: https://github.com/avivsinai/jenkins-cli/blob/main/docs/api.md

Establishes a Server-Sent Events (SSE) stream to receive real-time updates from Jenkins.

```APIDOC
## GET /jk/events/stream

### Description
Establishes a Server-Sent Events (SSE) stream to receive real-time updates from Jenkins. Frames are JSON objects encoded as UTF-8 text events.

### Method
GET

### Endpoint
/jk/events/stream

### Parameters
#### Query Parameters
- **topics** (string) - Required - Comma-separated list of topics to subscribe to (e.g., run,queue,node)

### Response
#### Success Response (200)
- **topic** (string) - The event topic (e.g., run.completed)
- **jobPath** (string) - The path of the job
- **number** (integer) - The build number
- **status** (string) - The status of the event
- **result** (string) - The result of the event
- **timestamp** (string) - ISO 8601 timestamp

#### Response Example
{
  "topic": "run.completed",
  "jobPath": "team/app/main",
  "number": 128,
  "status": "completed",
  "result": "SUCCESS",
  "timestamp": "2025-08-12T18:25:35Z"
}
```

--------------------------------

### GET /jk/api/runs/<jobPath>/<build>

Source: https://github.com/avivsinai/jenkins-cli/blob/main/docs/api.md

Retrieves detailed information about a specific Jenkins build run.

```APIDOC
## GET /jk/api/runs/<jobPath>/<build>

### Description
Retrieves the full details of a specific Jenkins build run, including status, parameters, SCM info, stages, and artifacts.

### Method
GET

### Endpoint
/jk/api/runs/<jobPath>/<build>

### Parameters
#### Path Parameters
- **jobPath** (string) - Required - The path to the Jenkins job.
- **build** (integer) - Required - The build number.

### Response
#### Success Response (200)
- **id** (string) - Unique identifier of the run.
- **status** (string) - Current status (queued, running, completed).
- **result** (string) - Build result (SUCCESS, UNSTABLE, FAILURE, ABORTED, NOT_BUILT).
- **startTime** (string) - RFC3339 timestamp.
- **durationMs** (integer) - Duration in milliseconds.

#### Response Example
{
  "id": "team/app/main/128",
  "number": 128,
  "status": "completed",
  "result": "SUCCESS",
  "startTime": "2025-08-12T18:24:03Z"
}
```

--------------------------------

### Create Secrets

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/references/commands.md

Create new credentials, supporting direct input, stdin, and folder-scoped storage.

```bash
jk cred create-secret --id my-secret --secret "value"
jk cred create-secret --id my-secret --secret "value" --description "API key"

# From stdin
echo "secret" | jk cred create-secret --id my-secret --from-stdin

# Folder-scoped
jk cred create-secret --id my-secret --secret "value" --scope folder --folder team/app
```

--------------------------------

### GET /run/ls

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/SKILL.md

Lists recent runs for a specific pipeline with various filtering and grouping options.

```APIDOC
## GET /run/ls

### Description
Lists recent runs for a pipeline, supporting limits, result filtering, parameter filtering, and pagination.

### Method
GET

### Endpoint
jk run ls <pipeline-path>

### Parameters
#### Query Parameters
- **--limit** (integer) - Optional - Limit the number of results.
- **--filter** (string) - Optional - Filter by result (SUCCESS/FAILURE) or parameters (param.KEY=value).
- **--since** (string) - Optional - Filter by time duration (e.g., 7d).
- **--include-queued** (boolean) - Optional - Include queued builds in the list.
- **--group-by** (string) - Optional - Group results by a specific parameter.
- **--cursor** (string) - Optional - Pagination cursor.
```

--------------------------------

### Manage build artifacts

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/SKILL.md

List and download artifacts associated with build runs.

```bash
# List artifacts
jk artifact ls team/app/pipeline 128

# Download all artifacts
jk artifact download team/app/pipeline 128

# Download with pattern filter
jk artifact download team/app/pipeline 128 --pattern "**/*.jar"
jk artifact download team/app/pipeline 128 -p "reports/**/*.xml"

# Output directory
jk artifact download team/app/pipeline 128 -o ./artifacts/

# Allow empty result (no error if no matches)
jk artifact download team/app/pipeline 128 -p "*.log" --allow-empty
```

--------------------------------

### Manage build queue

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/SKILL.md

List queued items and cancel pending builds.

```bash
# List queued items
jk queue ls

# Cancel queued item
jk queue cancel <item-id>
```

--------------------------------

### GET /jk/api/runs

Source: https://github.com/avivsinai/jenkins-cli/blob/main/docs/spec.md

Retrieves a normalized list of Jenkins runs based on job path and optional filters.

```APIDOC
## GET /jk/api/runs

### Description
Returns a normalized list of runs for a specific job.

### Method
GET

### Endpoint
/jk/api/runs

### Parameters
#### Query Parameters
- **jobPath** (string) - Required - The path to the Jenkins job
- **limit** (integer) - Optional - Maximum number of runs to return
- **after** (string) - Optional - Build number to start after

### Response
#### Success Response (200)
- **runs** (array) - List of run objects containing id, number, status, result, startTime, duration, branch, commit, stages, artifacts, and testSummary.
```

--------------------------------

### GET /jk run ls

Source: https://github.com/avivsinai/jenkins-cli/blob/main/docs/spec.md

Lists Jenkins runs with support for filtering, grouping, and metadata retrieval.

```APIDOC
## GET jk run ls

### Description
Lists Jenkins runs with support for composable discovery flags, filtering, and metadata.

### Method
GET

### Endpoint
jk run ls

### Parameters
#### Query Parameters
- **--filter** (string) - Optional - Filter by key[op]value (result, status, branch, param.*, artifact.*, cause).
- **--since** (string) - Optional - RFC3339 timestamp or human duration (e.g., 72h).
- **--select** (string) - Optional - Comma-separated fields to project into fields{}.
- **--group-by** (string) - Optional - Field to group results by.
- **--agg** (string) - Optional - Aggregation type (count, first, last).
- **--with-meta** (boolean) - Optional - Include machine-readable metadata.
- **--include-queued** (boolean) - Optional - Include queued builds in output.
- **--limit** (integer) - Optional - Limit the number of results.

### Response
#### Success Response (200)
- **schemaVersion** (string) - Version of the response schema.
- **items** (array) - List of run objects.
- **groups** (array) - Grouped aggregates if requested.
- **nextCursor** (string) - Cursor for pagination.
- **metadata** (object) - Metadata block containing filters, parameters, and selection context.

### Response Example
{
  "schemaVersion": "1.0",
  "items": [],
  "groups": [],
  "nextCursor": "g2wAAA...",
  "metadata": {
    "fields": ["number", "result", "parameters"],
    "groupBy": "param.CHART_NAME"
  }
}
```

--------------------------------

### List Queued Items

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/references/commands.md

Display items currently waiting in the build queue.

```bash
jk queue ls                              # List queued items
```

--------------------------------

### GET /jk/api/runs/<jobPath>/<build>/logs

Source: https://github.com/avivsinai/jenkins-cli/blob/main/docs/api.md

Retrieves progressive log output for a specific build run.

```APIDOC
## GET /jk/api/runs/<jobPath>/<build>/logs

### Description
Fetches log text for a build run, supporting progressive loading via offsets.

### Method
GET

### Endpoint
/jk/api/runs/<jobPath>/<build>/logs

### Response
#### Success Response (200)
- **text** (string) - The log content.
- **nextOffset** (integer) - The offset for the next log request.
- **hasMore** (boolean) - Indicates if more log data is available.

#### Response Example
{
  "text": "Running on linux-agent-1...\n",
  "nextOffset": 1472,
  "hasMore": true
}
```

--------------------------------

### Configure output modes

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/SKILL.md

Format command output using JSON, YAML, Go templates, or quiet mode.

```bash
# JSON output
jk run ls team/app --json

# YAML output
jk run ls team/app --yaml

# Filter with jq expression
jk run ls team/app --json --jq '.items[0].number'

# Go template
jk run ls team/app --json --template '{{range .items}}{{.number}}{{end}}'

# Quiet mode (minimal output)
jk run start team/app --quiet
```

--------------------------------

### POST /jk/run/start

Source: https://github.com/avivsinai/jenkins-cli/blob/main/docs/api.md

Triggers a new Jenkins job run and returns an acknowledgement.

```APIDOC
## POST /jk/run/start

### Description
Triggers a job run and returns an acknowledgement payload.

### Response
#### Success Response (200)
- **jobPath** (string) - The path of the job
- **message** (string) - Status message
- **queueLocation** (string) - URL of the queued item

#### Response Example
{
  "jobPath": "team/app/main",
  "message": "run requested",
  "queueLocation": "https://jenkins.example/queue/item/1357/"
}
```

--------------------------------

### Discover Build Parameters

Source: https://context7.com/avivsinai/jenkins-cli/llms.txt

Inspect parameter definitions for a job from configuration or historical runs.

```bash
# Get parameters from job config
jk run params team/app/deploy --source config

# Infer parameters from recent runs
jk run params team/app/deploy --source runs

# Auto-detect best source
jk run params team/app/deploy --json
```

--------------------------------

### Jenkins Event Stream Format

Source: https://github.com/avivsinai/jenkins-cli/blob/main/docs/spec.md

This is an example of a stable JSON event emitted by the Jenkins Events Router. It includes topic, job, build number, timestamp, and causes.

```json
{ "topic": "run.started", "job": "team/app/main", "build": 128, "timestamp": "...", "causes": [...] }
```

--------------------------------

### Fetch Job Configuration

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/references/commands.md

Retrieve the raw config.xml for a job, useful for review or local editing.

```bash
# Fetch raw config.xml to stdout
jk job config platform/services/auth-relay

# Save config.xml for review or editing
jk job config platform/services/auth-relay > auth-relay.config.xml
```

--------------------------------

### View Job Parameters

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/references/commands.md

Displays the parameter definitions configured for a specific job.

```bash
jk run params team/app/pipeline          # Show job's parameter definitions
```

--------------------------------

### Test Snapshot Releases

Source: https://github.com/avivsinai/jenkins-cli/blob/main/CONTRIBUTING.md

Generate snapshot binaries using GoReleaser for testing purposes.

```bash
goreleaser release --snapshot --clean
ls -la dist/
```

--------------------------------

### Run Log Snapshot JSON

Source: https://github.com/avivsinai/jenkins-cli/blob/main/docs/api.md

Provides a snapshot of the build log. If the run is still executing, the 'truncated' flag will be true, and callers should retry with --follow.

```json
{
  "jobPath": "team/app/main",
  "build": 128,
  "status": "completed",
  "result": "SUCCESS",
  "startTime": "2025-08-12T18:24:03Z",
  "duration": "1m32s",
  "log": "Started by user Jane Doe\nRunning on linux-agent-1...\n...",
  "truncated": false
}
```

--------------------------------

### Create Jenkins Jobs

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/references/commands.md

Create new jobs using repository configurations or discovery strategies.

```bash
jk job create auth-relay \
  --folder platform/services \
  --repo-owner playg \
  --repository taboola-sales-skills \
  --script-path services/auth-relay/Jenkinsfile \
  --credentials bitbucket-ro

# Optional discovery behavior
jk job create auth-relay \
  --repo-owner playg \
  --repository taboola-sales-skills \
  --branch-strategy only-prs \
  --discover-origin-prs \
  --discover-fork-prs
```

--------------------------------

### Manage CLI Contexts

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/references/commands.md

List, switch, or remove Jenkins connection contexts.

```bash
# List contexts (* = active)
jk context ls

# Switch active context
jk context use prod-jenkins

# Delete context
jk context rm staging
```

--------------------------------

### List Build Artifacts

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/references/commands.md

Retrieve a list of artifacts associated with a specific build.

```bash
jk artifact ls team/app/pipeline 128     # List artifacts
```

--------------------------------

### Download Build Artifacts

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/references/commands.md

Download artifacts from a build, supporting glob patterns, custom output directories, and empty result handling.

```bash
jk artifact download team/app/pipeline 128
jk artifact download team/app/pipeline 128 --pattern "**/*.jar"
jk artifact download team/app/pipeline 128 -p "reports/**/*.xml"
jk artifact download team/app/pipeline 128 -o ./artifacts/
jk artifact download team/app/pipeline 128 -p "*.log" --allow-empty
```

--------------------------------

### Jenkins CLI Job Creation with Branch Strategy

Source: https://github.com/avivsinai/jenkins-cli/blob/main/README.md

Create a Bitbucket-backed Multibranch Pipeline job, specifying the repository owner, name, script path, credentials, and branch strategy.

```bash
# Create a Bitbucket-backed Multibranch Pipeline job
jk job create auth-relay \
  --folder platform/services \
  --repo-owner playg \
  --repository taboola-sales-skills \
  --script-path services/auth-relay/Jenkinsfile \
  --credentials bitbucket-ro \
  --branch-strategy all
```

--------------------------------

### Context Management Commands

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/references/commands.md

Commands for managing CLI contexts, including listing, switching, and removing them.

```APIDOC
## Context Management Commands

### List Contexts

```bash
jk context ls
```

**Description**: Lists all configured contexts, with the active context marked by an asterisk (*).

### Switch Context

```bash
jk context use <context_name>
```

**Description**: Switches the active context to the specified context name.

### Remove Context

```bash
jk context rm <context_name>
```

**Description**: Deletes the specified context.

**Environment Variable**: `JK_CONTEXT` can override the active context.
```

--------------------------------

### View build logs

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/SKILL.md

Retrieve console logs for specific build runs.

```bash
# View console log (snapshot)
jk log team/app/pipeline 128

# Stream live logs
jk log team/app/pipeline 128 --follow

# Custom poll interval
jk log team/app/pipeline 128 --follow --interval 2s

# Plain output (no decorations)
jk log team/app/pipeline 128 --plain
```

--------------------------------

### Command Catalog JSON

Source: https://github.com/avivsinai/jenkins-cli/blob/main/docs/api.md

Provides a comprehensive catalog of available CLI commands, their descriptions, flags, and subcommands. Includes exit codes.

```json
{
  "schemaVersion": "1.0",
  "commands": [
    {
      "name": "jk",
      "use": "jk",
      "description": "jk is the Jenkins CLI for developers",
      "flags": [
        {"name": "context", "shorthand": "c", "type": "string", "description": "Active Jenkins context name", "default": "", "persistent": true},
        {"name": "json", "type": "bool", "description": "Output in JSON format when supported", "default": "false", "persistent": true},
        {"name": "yaml", "type": "bool", "description": "Output in YAML format when supported", "default": "false", "persistent": true},
        {"name": "jq", "type": "string", "description": "Filter JSON output using jq expression (requires --json or --format=json)", "default": "", "persistent": true},
        {"name": "quiet", "shorthand": "q", "type": "bool", "description": "Suppress non-essential output", "default": "false", "persistent": true},
        {"name": "format", "type": "string", "description": "Output format: json, yaml", "default": "", "persistent": true},
        {"name": "template", "shorthand": "t", "type": "string", "description": "Format output using Go template (requires --json or --format=json)", "default": "", "persistent": true}
      ],
      "subcommands": [
        {
          "name": "run",
          "use": "run",
          "description": "Interact with job runs",
          "subcommands": [
            {"name": "ls", "use": "run ls <jobPath>", "description": "List recent runs"},
            {"name": "search", "use": "run search", "description": "Search runs across jobs"}
          ]
        }
      ]
    }
  ],
  "exitCodes": {
    "0": "Success",
    "1": "General error",
    "2": "Validation error",
    "3": "Not found",
    "4": "Authentication failure",
    "5": "Permission denied",
    "6": "Connectivity/DNS/TLS failure",
    "7": "Timeout",
    "8": "Feature unsupported",
    "10": "Build result: UNSTABLE",
    "11": "Build result: FAILURE",
    "12": "Build result: ABORTED",
    "13": "Build result: NOT_BUILT",
    "14": "Build result: RUNNING (in-progress)"
  }
}
```

--------------------------------

### Configure Docker Environment for E2E Tests

Source: https://github.com/avivsinai/jenkins-cli/blob/main/CONTRIBUTING.md

Export environment variables to point the test harness to the Colima Docker socket.

```sh
export DOCKER_HOST="unix://$HOME/.colima/default/docker.sock"
export TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE="/var/run/docker.sock"
# Requires jq (install via 'brew install jq' on macOS).
export TESTCONTAINERS_HOST_OVERRIDE="$(colima status --json | jq -r '.ip_address')"
```

--------------------------------

### View Test Reports

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/references/commands.md

Retrieve test reports for a build, with optional JSON output formatting.

```bash
jk test report team/app/pipeline 128     # View test report
jk test report team/app/pipeline 128 --json
```

--------------------------------

### Artifact Management

Source: https://context7.com/avivsinai/jenkins-cli/llms.txt

Commands for listing and downloading build artifacts from Jenkins pipelines.

```APIDOC
## List and Download Build Artifacts

### Description
Browse and retrieve artifacts from Jenkins builds.

### Method
CLI Command

### Endpoint
jk artifact [ls|download] [pipeline] [build_number]

### Parameters
#### Path Parameters
- **pipeline** (string) - Required - The path to the pipeline.
- **build_number** (integer) - Required - The specific build number.

#### Query Parameters
- **--json** (flag) - Optional - Output results as JSON.
- **-o** (string) - Optional - Output directory for downloads.
- **-p** (string) - Optional - Glob pattern filter for downloads.
- **--allow-empty** (flag) - Optional - Do not error if no matches are found.
```

--------------------------------

### Build a run summary dashboard

Source: https://github.com/avivsinai/jenkins-cli/blob/main/docs/agent-cookbook.md

Aggregate success and failure counts for jobs over the last week.

```bash
jk run ls team/api/deploy --since 7d --group-by result --agg count --json
```

```python
import json
import subprocess

summary = json.loads(subprocess.run([
    "jk", "run", "ls", "team/api/deploy",
    "--since", "7d",
    "--group-by", "result",
    "--agg", "count",
    "--json",
], check=True, capture_output=True, text=True).stdout)
counts = {g["value"]: g["count"] for g in summary.get("groups", [])}
```

--------------------------------

### Jenkins CLI Job Creation and Configuration

Source: https://github.com/avivsinai/jenkins-cli/blob/main/README.md

Create a new Multibranch Pipeline job from a Bitbucket repository, fetch its configuration, and update its script path. Supports configuration via stdin.

```bash
jk job create auth-relay --folder platform/services --repo-owner playg --repository taboola-sales-skills --script-path services/auth-relay/Jenkinsfile --credentials bitbucket-ro
jk job config platform/services/auth-relay | rg scriptPath
jk job configure platform/services/auth-relay --script-path services/auth-relay/Jenkinsfile
jk job config platform/services/auth-relay | jk job configure platform/services/auth-relay --stdin
```

--------------------------------

### Authenticate with Jenkins CLI

Source: https://github.com/avivsinai/jenkins-cli/blob/main/skills/jk/references/commands.md

Use these commands to log in to a Jenkins instance with various security and proxy configurations.

```bash
# Login with credentials
jk auth login https://jenkins.example.com --username alice --token <API_TOKEN>

# With context name
jk auth login https://jenkins.example.com --name prod --username alice --token <TOKEN>

# TLS options
jk auth login https://jenkins.example.com --username alice --token <TOKEN> --insecure
jk auth login https://jenkins.example.com --username alice --token <TOKEN> --ca-file /path/to/ca.pem

# With proxy
jk auth login https://jenkins.example.com --username alice --token <TOKEN> --proxy http://proxy:8080

# Allow insecure storage (when keychain unavailable)
jk auth login https://jenkins.example.com --username alice --token <TOKEN> --allow-insecure-store
```

--------------------------------

### Queue Management

Source: https://context7.com/avivsinai/jenkins-cli/llms.txt

Commands for monitoring and managing the Jenkins build queue.

```APIDOC
## Monitor and Manage the Build Queue

### Description
Inspect queued builds and cancel pending items.

### Method
CLI Command

### Endpoint
jk queue [ls|cancel] [item_id]

### Parameters
#### Path Parameters
- **item_id** (integer) - Optional - The ID of the queued item to cancel.
```

--------------------------------

### Manage Jenkins CLI Contexts

Source: https://github.com/avivsinai/jenkins-cli/blob/main/docs/spec.md

List, use, or remove Jenkins CLI contexts. Use `jk whoami` to display the current context.

```bash
jk context ls|use|rm
```

```bash
jk whoami
```

--------------------------------

### View and Stream Build Logs

Source: https://context7.com/avivsinai/jenkins-cli/llms.txt

Access console output for Jenkins builds with options for streaming and formatting.

```bash
# View log snapshot for a completed build
jk log team/app/pipeline 128

# Stream live logs until build completes
jk log team/app/pipeline 128 --follow

# Stream with custom polling interval
jk log team/app/pipeline 128 --follow --interval 500ms

# Plain output (no headers, suitable for piping)
jk log team/app/pipeline 128 --plain

# Get log as JSON
jk log team/app/pipeline 128 --json
```

--------------------------------

### Snapshot job parameters

Source: https://github.com/avivsinai/jenkins-cli/blob/main/docs/agent-cookbook.md

Retrieve job parameters to populate UI defaults for manual triggers.

```bash
jk run params Helm.Chart.Deploy --source auto --json
```

```typescript
const proc = new Deno.Command("jk", {
  args: ["run", "params", "Helm.Chart.Deploy", "--json"],
}).outputSync();
const payload = JSON.parse(new TextDecoder().decode(proc.stdout));
const required = payload.parameters.filter((p: any) => p.frequency >= 0.99);
```