1. 项目概述一个为终端而生的Jenkins管理利器如果你和我一样日常工作中需要频繁地与Jenkins服务器打交道那么你一定体会过在浏览器和终端之间反复横跳的繁琐。查看构建状态、触发新的部署、追踪日志……这些重复性操作不仅打断工作流效率也大打折扣。今天要分享的是我在团队中引入并深度使用超过半年的一个工具jenkins-cli-ts。这是一个用TypeScript编写、基于Bun运行时构建的Jenkins命令行客户端它彻底改变了我们与Jenkins的交互方式。简单来说jenkins-cli-ts让你能在终端里完成几乎所有常见的Jenkins操作。从列出项目、触发构建、实时查看日志到管理多个Jenkins服务器的配置比如区分开发、测试、生产环境它都提供了直观且脚本友好的命令。对于追求效率的开发者、运维工程师和DevOps从业者而言这绝对是一个能显著提升幸福感的工具。它尤其适合那些已经习惯在终端里完成一切希望将CI/CD流程更紧密地集成到本地工作流中的团队。2. 核心设计理念与架构解析2.1 为什么选择 CLI 而非 Web UI 或传统插件在深入使用之前我们先聊聊它的设计初衷。传统的Jenkins交互主要依赖Web界面虽然功能全面但在自动化、批处理和与本地开发流程集成方面存在天然短板。市面上也有一些基于Java的Jenkins CLI官方工具但往往配置复杂、输出不够友好对脚本化支持弱。jenkins-cli-ts的核心理念是“终端优先自动化友好”。它并非要取代Web UI的所有功能而是精准覆盖那些在开发、调试、部署过程中最高频、最需要快速响应的操作。它的设计目标很明确极简配置通过配置文件或环境变量管理多个Jenkins实例一键切换。可解析的输出所有成功输出以OK:开头提示信息以HINT:开头便于其他脚本捕获和处理结果。交互与自动化兼顾既提供了丰富的交互式菜单如搜索、选择也支持通过参数进行完全非交互式--non-interactive调用完美融入CI/CD流水线或本地自动化脚本。性能优化对项目列表等静态信息进行本地缓存减少不必要的API调用响应速度极快。2.2 技术栈选型Bun TypeScript 的优势项目选择了Bun作为运行时而非更常见的Node.js这是一个值得玩味的技术决策。Bun是一个新兴的、集运行时、包管理器和打包工具于一身的JavaScript平台其优势在于启动速度和执行效率。对于CLI工具来说启动延迟直接影响用户体验Bun在这方面表现优异。使用TypeScript则保证了代码的健壮性和可维护性。CLI工具需要处理复杂的参数解析、网络请求、状态管理和错误处理强类型系统能在开发阶段就规避大量潜在的错误。从源码结构来看项目采用了清晰的模块化设计将认证、API客户端、缓存、交互式提示等逻辑分离这使得功能扩展和维护变得相对容易。注意虽然项目使用Bun开发但通过编译生成了独立的原生二进制文件。这意味着最终用户安装后不需要在机器上安装Bun或Node.js直接运行即可极大地降低了使用门槛和依赖管理的复杂度。3. 从零开始的完整安装与配置指南3.1 多种安装方式详解与选择官方提供了几种安装方式适用于不同平台和包管理习惯的用户。首选方案一键安装脚本这是最通用、最推荐的方式。脚本会自动检测系统架构下载对应的预编译二进制文件并安装到你的PATH环境变量中。# 使用 curl curl -fsSL https://jatinbansal.com/jenkins-cli/install/ | bash # 或使用 wget wget -qO- https://jatinbansal.com/jenkins-cli/install/ | bash脚本做了什么识别你的操作系统Linux/macOS和架构x86_64, arm64。从GitHub Releases下载最新的、对应的原生二进制文件。默认将其安装到$HOME/.local/bin目录下。如果该目录不在你的PATH中脚本会给出提示。你可以通过环境变量自定义安装目录JENKINS_CLI_INSTALL_DIR/usr/local/bin curl -fsSL https://jatinbansal.com/jenkins-cli/install/ | bashmacOS 用户的 Homebrew 方案如果你习惯使用Homebrew可以通过添加第三方Tap来安装便于后续更新管理。brew tap jatinbansal1998/tap brew install jatinbansal1998/tap/jenkins-cli # 更新命令 brew upgrade jenkins-cli关于安装目录的实操心得我个人的习惯是将其安装到~/.local/bin并确保该路径已在PATH中。对于macOS/usr/local/bin也是常见选择。安装后运行jenkins-cli --version验证是否成功。如果提示“命令未找到”请检查对应目录是否已加入PATH。对于Linux通常需要将export PATH$HOME/.local/bin:$PATH添加到~/.bashrc或~/.zshrc中并执行source命令。3.2 核心配置多环境配置文件的艺术安装完成后最重要的一步是配置。jenkins-cli-ts的强大之处在于其优雅的多配置文件管理。所有配置存储在~/.config/jenkins-cli/jenkins-cli-config.json。初始配置与登录首先你需要添加一个Jenkins服务器的配置这通过login命令完成。你需要准备--url: Jenkins服务器的地址如https://jenkins.my-company.com。--user: 你的Jenkins用户名。--token: 在Jenkins Web界面生成的API Token在用户设置 API Token中创建。# 为工作环境添加一个配置并命名为“work” jenkins-cli login --profile work --url https://jenkins.company.com --user myname --token jk_abc123def456这条命令会验证凭证有效性并将配置安全地保存到上述配置文件中。--profile参数为这个配置集起了一个别名方便后续切换。配置文件深度解析让我们看看生成的配置文件具体包含了什么{ version: 2, defaultProfile: work, profiles: { work: { jenkinsUrl: https://jenkins.company.com, jenkinsUser: myname, jenkinsApiToken: jk_abc123def456, branchParam: BRANCH, useCrumb: false }, staging: { jenkinsUrl: https://staging-jenkins.company.com, jenkinsUser: myname, jenkinsApiToken: jk_xyz789uvw000, branchParam: BRANCH, useCrumb: true } }, debug: false }version: 配置版本用于内部兼容性管理。defaultProfile: 默认使用的配置别名。如果不指定--profile命令将使用它。profiles: 核心部分可以存储多个环境的配置。branchParam: 这是一个非常实用的字段。许多Jenkins流水线使用参数化构建其中用于指定代码分支的参数名称可能不统一可能是BRANCH、branch、git_branch等。在这里预设后后续使用--branch参数时CLI会自动使用正确的参数名调用Jenkins API。useCrumb: 是否启用CSRF保护Crumb。部分开启了安全设置的Jenkins服务器需要此选项。如果触发构建时遇到403错误可以尝试将其设为true。配置管理命令# 列出所有已配置的profile jenkins-cli profile list # 切换默认profile到“staging” jenkins-cli profile use staging # 删除名为“work”的profile谨慎操作 jenkins-cli profile delete work环境变量回退机制为了兼容一些简单的使用场景或容器环境CLI也支持环境变量。当配置文件中没有任何profile时它会查找以下环境变量JENKINS_URLJENKINS_USERJENKINS_API_TOKENJENKINS_USE_CRUMB重要安全提示API Token相当于你的密码务必妥善保管。配置文件存储在本地通常权限是安全的但也要避免泄露。切勿将配置文件提交到版本库。对于团队共享配置建议每个成员独立生成和使用自己的API Token。4. 日常高频操作实战详解4.1 项目管理与交互式探索基础命令jenkins-cli list是你的控制中心。直接运行它会列出默认profile下所有可用的Job项目。缓存机制与刷新首次运行list时CLI会从Jenkins服务器获取全量Job列表并缓存在本地系统缓存目录中macOS:~/Library/Caches/jenkins-cli/, Linux:~/.cache/jenkins-cli/。后续再执行list命令会瞬间显示结果因为读取的是本地缓存。这对于拥有成百上千个Job的Jenkins实例来说体验提升是巨大的。 当你需要获取最新的Job列表时例如新建了一个Job使用--refresh参数jenkins-cli list --refresh强大的自然语言搜索在大型项目中靠眼睛找Job很痛苦。CLI内置了基于自然语言的搜索功能它会对Job名称和描述进行模糊匹配。jenkins-cli list --search “backend api deploy production”这条命令会找出所有名称或描述中包含“backend”、“api”、“deploy”、“production”这些词汇的Job并按相关性排序非常智能。交互式模式终端里的GUI如果不加任何--search或--non-interactive参数直接运行jenkins-cli list会进入交互式模式。这是一个基于文本的终端UI你可以通过上下箭头键浏览Job列表。输入文字进行实时过滤搜索。选中一个Job后按回车会弹出操作菜单Build: 触发构建接下来会进入构建参数子菜单。Status: 查看该Job最新构建的状态。Build history: 查看构建历史记录。Watch: 实时监控最新构建的状态直到完成。Logs: 查看最新构建的日志。Cancel: 取消正在队列中或运行中的构建。Rerun: 重新运行上一次构建。这个设计将高频操作流线化你完全不需要记住复杂的命令和参数通过方向键和回车就能完成大部分工作体验非常流畅。4.2 构建触发参数化构建的优雅处理触发构建是核心功能jenkins-cli-ts对此的支持非常细致。基本构建触发jenkins-cli build --job “frontend-website”如果该Job不需要参数这条命令会立即触发一次构建。处理分支参数对于需要传递分支参数的Job最常见场景可以使用--branch参数。CLI会智能地使用你在profile中配置的branchParam默认为BRANCH来调用Jenkins的buildWithParametersAPI。jenkins-cli build --job “api-service” --branch feat/new-authentication自定义参数传递如果你的构建需要其他自定义参数可以使用--param参数支持多个。jenkins-cli build --job “deploy-pipeline” --param ENVIRONMENTstaging --param VERSION2.1.0 --param ROLLBACKfalse你甚至可以混合使用分支参数和自定义参数jenkins-cli build --job “deploy-pipeline” --branch main --param ENVIRONMENTprod“仅使用默认参数”模式有些参数化构建配置了默认值你希望直接使用这些默认值而不进行任何交互。这时可以使用--without-params参数。jenkins-cli build --job “nightly-test” --without-params在非交互式脚本中结合--non-interactive使用可以确保命令不会因等待输入而挂起jenkins-cli build --job-url “https://jenkins/job/nightly-test/” --non-interactive --without-params交互式构建流程在交互式模式下选择Build后你会进入一个构建模式子菜单Select a branch: 从Git仓库的分支列表中选取一个需要Jenkins Job配置支持。Enter custom parameters: 手动输入参数键值对。Run with default parameters: 直接使用默认参数触发。实时监控构建状态触发构建后你可能想等待它完成。使用--watch参数CLI会持续轮询构建状态直到成功、失败或中止并在完成后在macOS上发送一个系统通知Linux/Windows下会在终端有显著提示。jenkins-cli build --job “api-service” --branch main --watch在监控过程中按Esc键可以随时退出监控返回命令行。4.3 构建状态、历史与日志深度管理状态查询与监控status命令用于快速查看一个Job的最新构建状态。jenkins-cli status --job “data-processor”输出会显示构建编号、状态SUCCESS, FAILURE, UNSTABLE, ABORTED等、持续时间以及构建URL。 同样可以结合--watch来实时监控一个已存在的构建jenkins-cli status --job “data-processor” --watch构建历史洞察history或builds命令会以清晰的表格形式展示最近的构建历史模仿了Jenkins Web UI的样式但在终端里看起来更紧凑。jenkins-cli history --job “mobile-app-build”表格包含构建号、状态、时间戳、持续时间和提交者如果Jenkins提供了的话。在交互式模式下你可以按空格键翻页查看更多历史记录。选中一个历史构建后可以Rebuild: 使用与该次构建完全相同的参数重新触发一次构建。这是回滚或重现某次构建的绝佳方式无需手动回忆参数。Open URL: 在默认浏览器中打开该构建的Jenkins页面。Logs: 直接跳转到查看该次构建的日志。如果构建失败还会显示失败的步骤和原因摘要取决于Jenkins的配置。日志流式输出查看日志是排查问题的关键。logs命令默认显示最新一次构建的日志。# 查看最新构建的日志一次性输出 jenkins-cli logs --job “frontend-website” # 实时跟踪日志输出类似 tail -f jenkins-cli logs --job “frontend-website” --follow # 指定轮询间隔默认为2秒可以调整为更频繁 jenkins-cli logs --job “frontend-website” --follow --poll 1s # 查看指定构建URL的日志不跟踪 jenkins-cli logs --build-url “https://jenkins/job/frontend-website/45/” --no-follow--follow模式在调试长时间运行的构建时非常有用你可以实时看到控制台输出就像在本地运行命令一样。4.4 高级工作流控制等待、取消与重试等待构建完成在自动化脚本中你常常需要触发一个构建并等待它完成后再进行下一步操作。wait命令就是为此而生。# 等待名为“deploy-prod”的Job的最新构建完成超时设为30分钟每5秒检查一次 jenkins-cli wait --job “deploy-prod” --timeout 30m --interval 5s # 更精确地等待一个特定的构建完成 jenkins-cli wait --build-url “https://jenkins/job/deploy-prod/123/” # 等待一个队列中的任务开始构建先出队再等待构建完成 jenkins-cli wait --queue-url “https://jenkins/queue/item/456/”这个命令的退出码很有用0表示构建成功1表示构建失败或不稳定124表示等待超时130表示被用户中断如CtrlC。这为脚本化判断提供了直接依据。取消构建或队列任务当发现触发了错误的构建或者某个构建卡住时需要取消它。# 取消“slow-job”当前正在运行或队列中的构建 jenkins-cli cancel --job “slow-job” # 通过具体的构建URL取消 jenkins-cli cancel --build-url “https://jenkins/job/slow-job/55/” # 通过队列URL取消任务还在排队未开始构建 jenkins-cli cancel --queue-url “https://jenkins/queue/item/789/”重试失败构建rerun命令是一个快捷操作它会找到指定Job最近一次失败的构建并使用完全相同的参数重新触发一次。这在快速重试因网络等临时问题失败的构建时非常方便。jenkins-cli rerun --job “flaky-integration-test”5. 集成、自动化与隐私考量5.1 在脚本与自动化流程中的应用jenkins-cli-ts的设计从一开始就考虑了自动化。它的输出格式和退出码是脚本友好的。可解析的输出格式所有成功执行的命令其核心输出行都以OK:前缀开头。例如成功触发构建后你会看到OK: Build triggered: https://jenkins/job/my-job/123/在Bash/Python等脚本中你可以很容易地用grep或正则表达式提取出这个URL。类似的提示信息以HINT:开头警告或错误信息则有其他明确标识。这种一致性让结果捕获变得简单可靠。非交互式模式在CI/CD流水线、cron任务或任何无人值守的脚本中必须使用--non-interactive标志。这确保了CLI不会等待任何用户输入例如选择分支或参数如果遇到需要输入的情况会直接报错退出。这是自动化场景下的必备参数。#!/bin/bash # 一个简单的部署脚本示例 set -e JOB_NAME“deploy-to-staging” BRANCH${CI_COMMIT_BRANCH:-“main”} echo “Triggering deployment for $BRANCH...” BUILD_URL$(jenkins-cli build --job “$JOB_NAME” --branch “$BRANCH” --non-interactive | grep -o ‘OK: Build triggered: .*’ | cut -d‘ ’ -f4) if [ -n “$BUILD_URL” ]; then echo “Waiting for build: $BUILD_URL” jenkins-cli wait --build-url “$BUILD_URL” --timeout 20m --non-interactive echo “Deployment finished.” else echo “Failed to trigger build.” exit 1 fi灵活的凭证指定方式自动化脚本中你可能不想依赖全局配置文件。CLI支持在命令行中直接指定一次性凭证优先级最高。jenkins-cli list --url https://jenkins.other-env.com --user robot --token jk_xxx --non-interactive这让你可以在不修改任何配置文件的情况下临时操作另一个Jenkins实例。5.2 隐私与数据分析配置解析工具集成了可选的匿名数据分析功能基于PostHog用于帮助开发者了解命令使用情况以改进产品。这一点非常透明也值得称赞。默认行为与隐私保护数据分析功能默认是关闭的。即使启用其数据收集也有严格的保护措施绝不会发送任何敏感信息包括Jenkins用户名、API Token、URL任务名称、构建URL、队列URL分支名称、搜索关键词构建参数名和值日志输出内容发送的数据仅限于匿名的安装ID、CLI版本、执行的命令名称、命令是否在交互式终端中运行、命令执行结果成功/失败的高层标识、命令执行的精确耗时毫秒以及粗略的Jenkins API健康状态计数。这些数据无法关联到具体的用户或公司。如何配置与控制启用分析使用作者提供的默认项目在配置文件~/.config/jenkins-cli/jenkins-cli-config.json中设置analyticsDisabled: false。完全禁用分析在配置文件中设置analyticsDisabled: true或设置环境变量JENKINS_ANALYTICS_DISABLEDtrue。这是最彻底的方式。使用自定义PostHog实例通过环境变量JENKINS_POSTHOG_API_KEY和JENKINS_POSTHOG_HOST可以将数据发送到你自己的PostHog项目实现完全的数据控制。个人建议对于企业内部使用特别是涉及生产环境时我建议在配置文件中显式设置analyticsDisabled: true以完全禁用。对于个人或开源项目使用可以根据对开发者的信任程度自行决定。工具在此处的设计给了用户充分的选择权和知情权是很好的实践。6. 进阶技巧、问题排查与维护6.1 实用技巧与高效工作流别名Alias提升效率在~/.bashrc或~/.zshrc中为常用命令设置别名可以极大提升效率。alias jcl“jenkins-cli” alias jlist“jenkins-cli list --search” alias jbuild“jenkins-cli build --watch” # 我习惯触发后立刻观看这样jlist “prod deploy”就能快速搜索jbuild --job xxxx触发后自动进入监控。结合 fzf 进行模糊选择对于高级终端用户可以将jenkins-cli list的输出与模糊查找器fzf结合实现更强大的Job选择。# 选择一个Job并触发构建需要jq和fzf selected_job$(jenkins-cli list --format json | jq -r ‘.[].name’ | fzf) if [ -n “$selected_job” ]; then jenkins-cli build --job “$selected_job” --watch fi利用缓存机制理解缓存位置~/Library/Caches/jenkins-cli/或~/.cache/jenkins-cli/有时很有用。例如在Jenkins Job发生大规模变动后你可以手动删除缓存文件来强制刷新而不是等待缓存过期或每次都加--refresh。“deploy” 别名deploy是build命令的一个别名语义上更适合部署场景两者功能完全一致。jenkins-cli deploy --job “rollout-service” --branch canary6.2 常见问题与排查指南在实际使用中你可能会遇到以下一些问题问题1执行命令时报错 “Invalid credentials” 或 “403 Forbidden”检查凭证首先确认jenkins-cli profile list显示的profile信息是否正确特别是API Token是否过期Jenkins的API Token可以随时重新生成。检查URL确保Jenkins URL正确且末尾没有多余的斜杠/。启用CSRF Crumb如果Jenkins服务器开启了“防止跨站点请求伪造”CSRF Protection需要在profile配置或环境变量中设置“useCrumb”: true或JENKINS_USE_CRUMBtrue。尝试一次性凭证使用--url --user --token参数直接测试以排除配置文件错误。问题2触发参数化构建时参数未正确传递确认参数名Jenkins Job中定义的参数名是大小写敏感的。使用jenkins-cli build --job JOB_NAME --without-params先触发一次然后在Jenkins Web界面查看那次构建的“参数”部分确认实际的参数名称。更新profile配置如果分支参数名不是默认的BRANCH在profile配置中修改branchParam字段为你Job中实际的参数名。问题3在自动化脚本中命令挂起不退出确保使用了--non-interactive在脚本中任何jenkins-cli命令都应加上此参数防止等待用户输入。检查命令是否进入交互模式例如list命令不加参数会进入交互式菜单。在脚本中应该使用--search指定内容或明确使用--non-interactive。问题4网络问题或Jenkins服务器不稳定超时控制对于wait、logs --follow等可能长时间运行的命令合理设置--timeout参数避免脚本无限期等待。重试逻辑在关键的业务脚本中考虑对jenkins-cli命令添加重试机制以应对临时的网络抖动或Jenkins API短暂不可用。问题5如何升级CLI工具Homebrew安装运行brew upgrade jenkins-cli。脚本安装运行jenkins-cli update或jenkins-cli upgrade。你可以通过jenkins-cli update --check先检查新版本。自动更新可以启用通知jenkins-cli update --enable-auto或自动安装jenkins-cli update --enable-auto-install。我个人的习惯是启用通知手动控制升级时机。6.3 维护与更新策略该工具开发活跃定期会有新功能和修复。关注其GitHub仓库的Release页面是了解新特性的好方法。对于生产环境建议在升级前先在测试环境中验证新版本CLI与你的Jenkins实例和自动化脚本的兼容性。如果遇到bug或有新功能需求项目的GitHub仓库是提交问题的好地方。由于其代码结构清晰如果你有TypeScript和Bun的开发经验甚至可以考虑为其贡献代码。开发环境搭建非常方便项目提供了Dev Container配置用VS Code等编辑器打开即可获得一个包含所有依赖的完整开发环境。