Jenkins CLI

简体中文 | English

基于 Jenkins API Token 的轻量级命令行客户端，支持查询 Job、查看线上版本、列出可发布 tag、触发构建和查看日志。既能在真实终端中进入交互菜单，也能作为脚本化 CLI 调用。

当前针对 Jenkins 2.46x 开发。其他版本可能可用，但 API 字段可能存在差异。API Token 走 Basic Auth，2.96+ 无需 CSRF crumb。

功能

• 白色终端交互菜单，支持上下键选择与输入即搜过滤
• 动态读取当前账号有权访问的 Job 及其构建状态
• 查看某个 Job 最近成功构建的参数与 git 版本（即线上跑的 tag）
• 自动从构建参数解析业务仓库地址，git ls-remote 列出可发布 tag
• 选择 tag 触发构建，支持轮询构建结果与查看控制台日志
• setup 配置向导与 doctor 环境检查
• 非交互子命令输出结构化 JSON，便于脚本消费

要求

• Python 3.11+
• macOS 或 Linux
• 有效的 Jenkins 账号与 API Token
• 可选：git 客户端（tags 命令需要）

Python 部分仅使用标准库，不需要安装第三方包。

快速开始

git clone https://github.com/QiliChen/jenkins-cli.git
cd jenkins-cli
./install.sh

安装程序会检查 Python、安装 jks 命令，并在首次安装时启动配置向导。

jks doctor
jks

如果终端提示找不到 jks，请将下面一行加入 ~/.zshrc 或 ~/.bashrc：

export PATH="$HOME/.local/bin:$PATH"

配置

首次安装会执行 jks setup，需要填写：

JENKINS_BASE_URL=https://jenkins.example.com
JENKINS_USER=your-username
JENKINS_API_TOKEN=your-api-token

JENKINS_BASE_URL 只填写协议和域名。API Token 在 Jenkins 页面「用户 → 设置 → API Token → 添加新 Token」中生成，生成后只显示一次。

个人配置默认保存在：

~/.config/jenkins-cli/.env

文件权限自动设置为 600。重新配置：

jks setup

常用可选变量：

变量	默认值	用途
JENKINS_DEFAULT_JOB	无	不传 --job 时使用的默认 Job
JENKINS_TIMEOUT_SECONDS	20	API 请求超时
JENKINS_TRUST_ENV	false	设为 true 时走系统代理，默认直连
JENKINS_ENV_FILE	XDG 配置目录	自定义 .env 路径

环境变量优先于 .env。

使用

交互菜单

jks

Job 列表支持直接输入文字过滤（Backspace 删除、Esc 清空/返回）。选中 Job 后可查看当前版本、列出 tag、选择 tag 发布、查看日志。

非交互命令

所有查询类命令输出结构化 JSON（{"schema_version","ok","data"}），失败时 ok=false 且信息写入 stderr。

# 认证状态与 Jenkins 版本
jks status --compact

# 列出有权限的 Job（文件夹展开为 a/b 形式）
jks jobs --compact

# 查看 Job 的参数定义（含 Choice 候选值）
jks params --job example-service

# 查看最近成功构建的参数与 git 版本（线上跑的 tag）
jks current --job example-service

# 列出可发布 tag（自动解析业务仓库后 git ls-remote）
jks tags --job example-service --limit 20

文件夹内的 Job 用 / 分隔，例如 --job folder/example-service。

发布

# 触发前会要求输入 yes 确认
jks deploy --job example-service --param GIT_TAG_0=v1.2.3

# 跳过确认并轮询到构建结束
jks deploy --job example-service --param GIT_TAG_0=v1.2.3 --yes --watch

# 查看最近构建日志末尾 50 行
jks log --job example-service --build lastBuild --tail 50

--param 可重复传入，参数名以 jks params 输出为准。

双仓库流水线

部分流水线自身检出的是运维/发布仓库，真正的业务代码仓库和 tag 通过构建参数（如 GIT_URL_0 / GIT_TAG_0）传入。tags 命令会优先从构建参数中解析业务仓库地址，因此无需读取 config.xml（该接口通常需要更高权限）。发布时把目标 tag 传给对应的 GIT_TAG_* 参数即可。

环境检查

jks doctor

检查 Python 版本、配置文件权限、API 认证以及 git 客户端。FAIL 表示必须修复，WARN 表示对应的可选功能不可用。

升级与卸载

升级：

git pull
./install.sh

重复安装不会覆盖个人配置。

卸载并保留配置：

./uninstall.sh

同时删除个人配置：

./uninstall.sh --purge

安全

• 不要提交 .env 或真实 API Token
• 不要在 Issue、日志或截图中公开 Token
• 每位用户应使用自己的 API Token，以保留正确的授权与审计记录
• 建议使用 HTTPS 部署 Jenkins
• 如果 Token 已经泄露，请立即在 Jenkins 中撤销并重新生成

贡献

欢迎提交 Issue 和 Pull Request。提交前请确保不包含内部域名、Job 名称、IP、账号或密钥。

本仓库是与 Jenkins 交互的独立开源客户端，不是 Jenkins 官方项目。

许可证

MIT License