Fast Jenkins terminal companion: rich interactive TUI + focused scripting commands with smart log highlighting & multi‑server profiles. Target: Node >= 22, pure ESM.
# Install (global)
npm i -g @kud/jenkins-cli
# Configure once
jenkins config set --url https://ci.example.com --user alice --token $JENKINS_TOKEN
# See latest build status (pretty)
jenkins status my-pipeline --pretty
# Stream latest logs (follow)
jenkins logs my-pipeline -f
# Launch full-screen explorer (jobs | builds | logs)
jenkins --interactive
# Trigger with parameters
jenkins build my-pipeline --param BRANCH=feature-x --param CACHE=falseNeed JSON for scripts? Add --json. No icons / CI-safe? Set JENKINS_CLI_PLAIN=1.
- Features
- Install
- Quick Start
- Usage Cheat Sheet
- Interactive Explorer
- Configuration & Multi-Server
- Log Highlighting Magic
- Artifacts
- Queue & Pipelines
- Environment Variables
- Programmatic API
- Development & Prepublish
- Why Another CLI?
- Roadmap
- License
- Unified experience: quick one-liners + advanced full-screen explorer.
- Rich log intelligence: Docker, Git, JSON, diffs, test summaries, timestamps, levels, artifacts & more.
- Multi-server profiles with salvage of partially corrupted config.
- Incremental job traversal (BFS) with a safety cap (5000) for huge Jenkins instances.
- Smart emoji fallback on restricted terminals / CI.
- Zero heavy deps — just
commander,chalk,neo-blessed,highlight.js. - Modern: Node 22+, native fetch, ESM-first.
npm i -g @kud/jenkins-cli # Global binary
# or project-local
npm i -D @kud/jenkins-cliBinary: jenkins
jenkins config set --url https://ci.example.com --user alice --token $JENKINS_TOKEN
jenkins list my-job --pretty
jenkins logs my-job -f
jenkins trigger my-job
jenkins artifacts my-job 123 -p .jar -o jars/If you see an error like missing required argument 'jobOrUrl', it means the command expects a job name (or a full job/build URL) as the first positional argument.
Common patterns:
# Latest build status (pretty colors)
jenkins status my-service --pretty
# Follow live logs of latest (or specific) build
jenkins logs my-service -f
jenkins logs my-service 128 -f
# Plain console (same as logs without -f)
jenkins console my-service
jenkins console https://ci.example.com/job/my-service/128/
# List recent builds (limit 20)
jenkins list my-service -l 20<jobOrUrl> accepts either:
- A simple job name (folder paths use
/, e.g.team/backend-api) - A full build URL (
.../job/<name>/<build>/) or job URL (.../job/<name>/)
If the build number is omitted, the CLI resolves the latest build where supported.
Interactive exploration (jobs + builds + logs) still uses either:
jenkins --interactive # root flag form
jenkins interactive # explicit subcommand form| Task | Command | Notes |
|---|---|---|
| Latest build status | jenkins status job |
Add --pretty for colored state + icon |
| List builds | jenkins list job -l 15 |
Uses latest N builds |
| Stream logs | jenkins logs job -f |
Progressive API polling |
| Static logs JSON | jenkins logs job --json |
Outputs { text } |
| Trigger build | jenkins trigger job |
Plain trigger (no params) |
| Param build | jenkins build job --param KEY=V --param X=Y |
Repeat flag |
| Stop build | jenkins stop job 456 |
Aborts running build |
| Artifacts list | jenkins artifacts job 456 |
Tab separated list |
| Download artifacts | jenkins artifacts job 456 -o out/ |
All artifacts |
| Filter artifacts | jenkins artifacts job 456 -p .jar |
Simple substring |
| Test summary | jenkins test-report job 456 |
Add --json for details |
| Pipeline stages | jenkins stages job 456 |
Needs workflow-api plugin |
| Queue list | jenkins queue |
Items with flags |
| Cancel queue | jenkins queue-cancel 123 |
Immediate POST |
| Search jobs | jenkins search api -l 200 |
BFS substring matching |
| Single-job TUI | jenkins ui job |
Build list + logs |
| Multi-job TUI | jenkins interactive |
Jobs + builds + logs |
+------------------+------------------+-----------------------------------------+
| Jobs | Builds | Logs |
| (filter live) | (# State Dur Age)| syntax highlight / search / follow |
+------------------+------------------+-----------------------------------------+
| Status / Key Hints & Active Filters / Pane Focus Indicator / Help (?) |
+--------------------------------------------------------------------------------
| Key | Action | Key | Action |
|---|---|---|---|
q |
Quit | f |
Toggle follow |
r |
Refresh | S |
Toggle build sort |
1/2/3 |
Focus pane | t |
Auto-refresh toggle |
←/→ |
Cycle panes | a |
Artifacts popup |
/ |
Contextual search (jobs or logs) | c |
Clear filters |
b |
Build text filter | B |
Build fuzzy search |
m |
Bookmark line | M |
Jump to bookmark |
e/W/i |
Jump ERROR/WARN/INFO | g/G |
Top / Bottom |
l |
Toggle line numbers | ? |
Help overlay |
- Single job mode:
jenkins interactive --jobs my-servicehides the Jobs panel for more log real estate. - Emojis auto-replaced in plain terminals (CI, VS Code) → textual tokens.
Location: ~/.config/jenkins-cli/config.json (respects $XDG_CONFIG_HOME).
# Primary server
jenkins config set --url https://ci.example.com --user alice --token $TOKEN
# Multiple servers
jenkins config add-server prod --url https://ci.example.com --user alice --token $TOKEN_PROD
jenkins config add-server staging --url https://ci.staging.example.com --user alice --token $TOKEN_STG
jenkins config use staging
jenkins config list-serversPrecedence (highest → lowest): CLI flags > Environment variables > Config file.
Salvage logic automatically:
- Truncates trailing garbage past final
}if file partially corrupted. - Normalizes markdown links
[text](url)→url.
Pattern-based enrichment turns plain build text into readable diagnostics.
| Category | Examples Detected | Styling |
|---|---|---|
| Build Result | BUILD SUCCESS, BUILD FAILURE, UNSTABLE |
Colored + icon |
| Test Summary | Tests run: X Failures: Y Errors: Z |
Numeric color emphasis |
| Tools | docker pull, git clone, npm install |
Prefixed icons & color |
| Diffs | @@ ... @@, +added, -removed |
Magenta hunk / green / red |
| Levels | ERROR, WARN, INFO, DEBUG, TRACE, stack traces |
Rich labels / dim frames |
| JSON Lines | Single-line JSON objects / arrays | Pretty-highlighted or manual fallback |
| Paths & URLs | ~/file.ts, C:\path\a.js, https://... |
Cyan / underlined URLs |
| Progress | 31/120 (25%) or just 31/120 |
Recomputed percentage |
Disable icons entirely: JENKINS_CLI_NO_ICONS=1 (or JENKINS_CLI_PLAIN=1).
# List artifacts of latest build (auto-resolves if number omitted)
jenkins artifacts my-job
# List artifacts for specific build
jenkins artifacts my-job 128
# Download all to directory (creates if missing)
jenkins artifacts my-job 128 -o dist/artifacts
# Filter by substring (.jar) BEFORE downloading
jenkins artifacts my-job 128 -p .jar -o jars/jenkins queue # List queued tasks
jenkins queue-cancel 1234 # Cancel item
jenkins stages my-job 456 # Pipeline stages (needs workflow-api plugin)
jenkins test-report my-job 456 --json # Full JUnit JSON structure| Variable | Purpose | Notes |
|---|---|---|
JENKINS_URL |
Base URL override | Same as --url |
JENKINS_USER |
Username override | |
JENKINS_TOKEN |
Token override | |
JENKINS_SERVER |
Server alias | Chosen from config file |
JENKINS_TIMEOUT |
Request timeout (ms) | Default 15000 |
JENKINS_RETRIES |
Retry attempts (0–9) | Default 0 |
JENKINS_CLI_NO_ICONS |
Disable Unicode/emoji | Plain text tokens |
JENKINS_CLI_PLAIN |
Same as above | |
JENKINS_CLI_ASCII_SCROLLBAR |
Force ASCII scrollbar | Usually auto-chosen |
Import the client (ESM):
import { JenkinsClient } from '@kud/jenkins-cli';
const client = new JenkinsClient('https://ci.example.com', 'user', 'token');
const build = await client.getBuild('my-job');
console.log('Result:', build.result);Progressive log stream:
await client.streamConsole('my-job', 123, chunk => {
process.stdout.write(chunk); // apply your own formatting if desired
});Search jobs incrementally:
const jobs = await client.searchJobs('backend', 200); // cap results
for (const j of jobs) console.log(j.fullName || j.name);Download artifact:
const { artifacts } = await client.getArtifacts('my-job', 123);
for (const a of artifacts) {
const buf = await client.downloadArtifact('my-job', 123, a.relativePath);
// write buffer somewhere
}# Build TS → dist/
npm run build
# Watch mode
npm run dev
# Tests (placeholder for now)
npm testPublishing runs the build automatically via prepublishOnly.
- Existing CLIs are bulky or incomplete for log exploration.
- Need fast traversal & multi-server context switching.
- Rich real-time log augmentation without external plugins.
- Modern Node (fetch, ESM) keeps surface minimal.
- In-log match navigation (cursor → exact line for search hits)
- Structured log export (JSON objects: timestamp, level, message)
- Richer pipeline / stage timing visualization
- Inline artifact preview (JSON / text, maybe diff)
- Config encryption for tokens (optional)
Have a feature idea? Open an issue / PR.
MIT
Happy building! 🛠️