Headless Jenkins core — client, config, and types (data · actions · auth).

Features • Quick Start • API Reference • Development

🌟 Features

• 🧩 Single client, full surface — JenkinsClient covers job/build metadata, console logs (with live streaming), artifacts, the build queue, and triggers
• ⚙️ Layered config resolution — named server → environment variables → per-call overrides, so callers never hardcode credentials
• 🗂 Multi-server profiles — add, switch, and remove named Jenkins servers without touching env vars
• 🔁 Resilient HTTP layer — timeout and bounded retry with backoff on network errors and 5xx responses, automatic CSRF crumb handling on every mutating call
• 🌲 Recursive job search — BFS traversal across nested folders, plus an incremental/concurrent variant with progress callbacks for large instances
• 🧼 Log sanitisation — strips ANSI escape codes and control characters from console output for clean rendering
• 📐 Fully typed — exported TypeScript types for jobs, builds, artifacts, parameters, and changesets

Surface-agnostic by design: this package holds no CLI, no prompts, no rendering — just data, actions, and auth. @kud/jenkins-cli is the command surface and interactive TUI built on top of it.

🚀 Quick Start

npm install @kud/jenkins

import { JenkinsClient, resolveConfig } from "@kud/jenkins"

const cfg = resolveConfig()
const client = new JenkinsClient(cfg.url, cfg.user, cfg.token)

const jobs = await client.searchJobs("my-service")
const build = await client.getBuild("my-service")

console.log(build.result, build.building)

Configuration resolves in layers — named server profile → environment variables → explicit overrides:

export JENKINS_URL=https://ci.example.com
export JENKINS_USER=erwann
export JENKINS_API_TOKEN=xxxxxxxxxxxx

Several instances can be declared at once, comma or pipe separated and matched positionally. JENKINS_INSTANCES names them; without it, each name is derived from its URL's first hostname label. The first instance is the default, and JENKINS_SERVER (or a server override) selects another:

export JENKINS_INSTANCES=pipeline,scheduler
export JENKINS_URL=https://pipeline.example.com,https://scheduler.example.com
export JENKINS_USER=erwann          # a single value applies to every instance
export JENKINS_API_TOKEN=tok1,tok2

A name/URL count mismatch is an error rather than a best-effort pairing: a short list would silently authenticate one instance with another's credentials.

Or manage named servers on disk (~/.config/jenkins-cli/config.json, override the base with XDG_CONFIG_HOME):

import { addServer, useServer, listServers } from "@kud/jenkins"

addServer("prod", {
  url: "https://ci.example.com",
  user: "erwann",
  token: "xxxx",
})
useServer("prod")
listServers() // [{ name: "prod", url: "...", current: true }]

📖 API Reference

Jobs & Builds

Method	Description
getJob(job)	Fetch a job's metadata (depth 1)
getBuild(job, buildNumber?)	Fetch a build; defaults to the last build
listBuilds(job, limit?)	Fetch recent builds concurrently
getBuildChanges(job, buildNumber?)	Trigger cause, culprits, and SCM commits for a build
getJobParameters(job)	Parameter definitions for a parameterised job
searchJobs(query, limit?)	Recursive BFS search across folders
searchJobsIncremental(query, opts?)	Same search, with a progress callback and bounded concurrency
getSpecificJobs(jobNames)	Batch-fetch jobs by name, tolerant of per-job errors
getPipelineStages(job, buildNumber)	Pipeline stage breakdown (Workflow API)
getTestReport(job, buildNumber)	Test report for a build

Logs

Method	Description
getConsoleText(job, buildNumber?)	Full console output as text
streamConsole(job, buildNumber, onChunk, intervalMs?, opts?)	Poll and stream console output as it's produced

Artifacts

Method	Description
getArtifacts(job, buildNumber?)	Build plus its artifact list
downloadArtifact(job, buildNumber, relativePath)	Download an artifact as a Buffer

Actions

Method	Description
triggerBuild(job)	Trigger a build
triggerBuildWithParameters(job, params)	Trigger a parameterised build
stopBuild(job, buildNumber)	Stop a running build
getQueue()	Fetch the build queue
cancelQueueItem(id)	Cancel a queued item

Config

Export	Description
resolveConfig(overrides?)	Layered resolution: named server → env vars → overrides
addServer(name, { url, user, token })	Add or update a named server profile
useServer(name)	Switch the active named server
removeServer(name)	Remove a named server profile
listServers()	List all named servers, with the active one flagged

Utilities

Export	Description
sanitizeLogChunk(chunk, opts?)	Strip ANSI codes and control characters from console output
normalizeUrl(url)	Fix malformed schemes such as http:/host → http://host
ensureScheme(url)	Prefix https:// onto a bare host if no scheme is present
parseBuildSpecifier(input)	Parse a job name, job URL, or build URL into a structured descriptor

Types

JenkinsJob, JenkinsBuild, JenkinsBuildRef, JenkinsArtifact, JenkinsCrumb, JenkinsParameterDefinition, JenkinsCommit, JenkinsBuildChanges — exported from src/types.ts and used across every method above.

Auth is HTTP Basic (username + API token) — no OAuth, no sessions. Every mutating call (triggerBuild, stopBuild, cancelQueueItem, …) fetches a CSRF crumb first and attaches it automatically, so callers never manage crumbs themselves.

🔧 Development

src/
├── index.ts             # public exports
├── jenkins-client.ts    # JenkinsClient — data + actions
├── config.ts            # resolveConfig, named-server helpers
├── types.ts             # shared Jenkins types
├── url-utils.ts         # URL parsing/normalisation helpers
└── log-sanitizer.ts     # sanitizeLogChunk

Script	Description
build	Compile src/ to dist/ via tsc
typecheck	Type-check without emitting output

git clone https://github.com/kud/jenkins.git
cd jenkins
npm install
npm run build

🏗 Tech Stack

Layer	Choice
Language	TypeScript 5.9
Runtime	Node.js ≥ 22, native fetch
Module	ESM (type: module)
Dependencies	None at runtime — @types/node and typescript are dev-only

---

MIT © kud — Made with ❤️