sanjiu-jenkins-cli 0.1.0

A simple Jenkins CI/CD CLI tool for triggering builds, monitoring status, and streaming logs

sj-cicd — Jenkins 构建部署命令行工具

简洁的 Jenkins 命令行工具，一条命令管理构建部署。

• 支持任意 Jenkins 实例，Jenkins URL 完全可配置
• 内置 Claude Code / Codex Skill，安装后可直接对话式操作 Jenkins
• 结构化 JSON 输出，对 AI 和脚本都友好

安装

方式一：pip 安装（推荐）

pip install sanjiu-jenkins-cli

方式二：源码安装（一键脚本，自动引导配置 + 注册 AI Skill）

git clone https://github.com/slicenferqin/sanjiu-jenkins-cli.git
cd sanjiu-jenkins-cli
bash setup.sh

安装脚本会自动完成：

1. 检查 Python 版本（需要 3.11+）
2. 安装 CLI 工具
3. 交互式引导配置 Jenkins 认证
4. 检测 Claude Code / Codex，自动注册 Skill

配置

首次使用需要两个东西：Jenkins URL 和 API Token。

获取 API Token

1. 打开你的 Jenkins → 右上角用户名 → Configure（或直接访问 <你的Jenkins>/me/configure）
2. 找到 API Token 部分
3. 点击 Add new Token → 取个名字 → 复制生成的 token

写入配置（二选一）

方式一：配置文件（推荐）

cat > ~/.jenkins-cli << 'EOF'
JENKINS_URL=https://your-jenkins.example.com
JENKINS_USER=your-username
JENKINS_TOKEN=your-api-token
EOF
chmod 600 ~/.jenkins-cli

方式二：环境变量

export JENKINS_URL="https://your-jenkins.example.com"
export JENKINS_USER="your-username"
export JENKINS_TOKEN="your-api-token"

验证配置

sj-cicd auth
# ✓ Authentication successful
# {"user": "sanjiu", "fullName": "三酒", ...}

使用教程

命令一览

sj-cicd list [FILTER]           列出任务（支持正则过滤）
sj-cicd info <任务名>            查看任务详情和构建参数
sj-cicd build <任务名> K=V ...   触发构建
sj-cicd status <任务名> [构建号]  查看构建状态（默认最近一次）
sj-cicd history <任务名> [-n N]  查看构建历史（默认最近 10 次）
sj-cicd log <任务名> <构建号>     查看构建日志
sj-cicd stop <任务名> <构建号>    停止运行中的构建
sj-cicd auth                    验证认证配置

场景 1：搜索任务

# 列出所有任务
sj-cicd list

# 按关键词搜索（支持正则）
sj-cicd list order-center
sj-cicd list "web|frontend"

# 输出示例：
# [
#   {"name": "Dev_InternalControl-order-center", "type": "pipeline", "buildable": true, "status": "blue"},
#   {"name": "Test_InternalControl-order-center", "type": "pipeline", "buildable": true, "status": "blue"},
#   ...
# ]

场景 2：查看任务参数

sj-cicd info DEV-WEB-xiaoy-zhibo-wx

# 输出示例：
# {
#   "name": "DEV-WEB-xiaoy-zhibo-wx",
#   "buildable": true,
#   "lastBuild": 10,
#   "parameters": [
#     {"name": "ENV", "type": "ChoiceParameter", "choices": ["test", "dev"], "defaultValue": "test"},
#     {"name": "BranchName", "type": "GitParameter", "choices": ["master", "release", ...], "defaultValue": "master"},
#     {"name": "NpmRegistry", "type": "ChoiceParameter", "choices": ["私有源", "官方源"], "defaultValue": "私有源"}
#   ]
# }

场景 3：触发构建

# 带参数触发，等待完成
sj-cicd build DEV-WEB-xiaoy-zhibo-wx ENV=test BranchName=master

# 带参数触发，实时流式日志
sj-cicd build DEV-WEB-xiaoy-zhibo-wx ENV=test BranchName=master --follow-log

# 只触发，不等待
sj-cicd build DEV-WEB-xiaoy-zhibo-wx ENV=dev --no-wait

build 命令的完整流程：

1. 触发构建 → 获取队列 ID
2. 等待构建开始（轮询队列，最长 120 秒）
3. 监控构建状态 / 流式输出日志
4. 报告最终结果（SUCCESS / FAILURE + 耗时）

场景 4：查看构建状态

# 最近一次构建
sj-cicd status DEV-WEB-xiaoy-zhibo-wx

# 指定构建号
sj-cicd status DEV-WEB-xiaoy-zhibo-wx 42

# 输出示例：
# {
#   "job": "DEV-WEB-xiaoy-zhibo-wx",
#   "number": 10,
#   "result": "SUCCESS",
#   "building": false,
#   "duration": "3m21s",
#   "timestamp": "2021-04-14 19:04:04"
# }

场景 5：构建历史

# 最近 10 次
sj-cicd history DEV-WEB-xiaoy-zhibo-wx

# 最近 5 次
sj-cicd history DEV-WEB-xiaoy-zhibo-wx -n 5

场景 6：查看 / 排查日志

# 查看完整日志
sj-cicd log DEV-WEB-xiaoy-zhibo-wx 10

# 实时流式日志（构建进行中时使用）
sj-cicd log DEV-WEB-xiaoy-zhibo-wx 10 --follow

场景 7：停止构建

sj-cicd stop DEV-WEB-xiaoy-zhibo-wx 42
# ✓ Stop request sent for DEV-WEB-xiaoy-zhibo-wx #42

中文任务名

完全支持中文任务名，自动 URL 编码：

sj-cicd info "cdn刷新"
sj-cicd build "cdn刷新" Type=File UriList="https://example.com/path"

AI 对话集成（Claude Code / Codex）

安装脚本会自动检测 Claude Code 和 Codex CLI，将 Skill 注册到对应位置。注册后无需记命令，直接用自然语言操作：

你说的话	AI 执行的操作
"部署 DEV-WEB-xiaoy-zhibo-wx 到 test 环境"	info → 展示参数 → 确认 → build --follow-log
"查看 order-center 最近的构建"	list order-center → status
"构建失败了，帮我看下日志"	history → 找到失败构建 → log → 分析错误
"Jenkins 上有哪些 WEB 项目"	list WEB
"停止 xxx 的构建"	status → 确认运行中 → stop

手动安装 Skill

如果通过 pip 安装而非 setup.sh，需要手动复制 Skill：

# Claude Code
mkdir -p ~/.claude/skills/sj-cicd
curl -o ~/.claude/skills/sj-cicd/SKILL.md \
  https://raw.githubusercontent.com/slicenferqin/sanjiu-jenkins-cli/main/skill/SKILL.md

# Codex CLI
mkdir -p ~/.codex/skills/sj-cicd
curl -o ~/.codex/skills/sj-cicd/SKILL.md \
  https://raw.githubusercontent.com/slicenferqin/sanjiu-jenkins-cli/main/skill/SKILL.md

项目结构

sanjiu-jenkins-cli/
├── setup.sh                    # 一键安装（引导配置 + 自动注册 Skill）
├── pyproject.toml              # 包配置
├── src/jenkins_cli/
│   ├── cli.py                  # CLI 入口（Click）
│   ├── client.py               # Jenkins API 客户端（httpx）
│   └── config.py               # 认证配置管理
├── skill/
│   └── SKILL.md                # AI Skill（Claude Code / Codex）
└── tests/

License

MIT