Butler CI CLI

🤖 A command-line tool to interact with Jenkins Pipelines in a simple and efficient way.

📋 Description

Butler CI CLI is a terminal application that allows you to manage and monitor Jenkins jobs through simple commands. It makes it easy to query information about pipelines, builds, and their status without needing to access the Jenkins web interface.

⚡ Features

• 📋 List all available jobs in Jenkins (including folders and subfolders)
• 🔍 Get detailed information about a specific job (supports folder paths)
• 🔄 Query the last build of a job
• 📊 List builds with filtering (by status, date range), pagination, and sorting
• 💾 Save job list locally for future references
• 🗂️ Navigate through Jenkins folder structure
• 🔍 Search jobs by name across the entire structure
• 📁 Visualize folder structure
• 🎨 Colorful and user-friendly terminal interface
• 📋 Query required parameters for jobs
• 🚀 Execute builds in an assisted manner (interactive or with CLI parameters)
• 📄 View and download build logs
• 🔄 Stream logs in real-time with configurable refresh intervals
• ✏️ Open logs in configurable editors
• ⚙️ Customizable preferences system (editor, log viewer, directory)

🛠️ Installation

Prerequisites

• Node.js (version 16 or higher)
• pnpm (recommended) or npm
• Access to a Jenkins server with API credentials

Installation from source

1. Clone the repository:

git clone https://github.com/usarral/butler-ci-cli.git
cd butler-ci-cli

2. Install dependencies:

# With npm
npm install

# With pnpm  
pnpm install

# With yarn
yarn install

3. Build the project:

npm run build
# or
pnpm build

4. Install globally (optional):

# With npm
npm install -g .

# With pnpm
pnpm install -g .

# With yarn
yarn global add .

Installation from npm

# With npm
npm install -g butler-ci-cli

# With pnpm
pnpm install -g butler-ci-cli

# With yarn
yarn global add butler-ci-cli

⚙️ Configuration

Butler CI CLI uses a file-based configuration system that allows you to manage multiple Jenkins servers easily. Configurations are stored in your home directory (~/.butler-ci-cli/configs/).

Configuration Management

Create a new configuration

butler-ci-cli config create

The command will guide you step by step to create a new configuration:

• Name: Unique identifier for the configuration
• URL: Jenkins server address
• User: Your Jenkins username
• Token: Jenkins API token
• Description: Optional description
• Activate: Whether to set as active configuration

List configurations

butler-ci-cli config list
# or use the alias
butler-ci-cli config ls

Shows all available configurations with the active one marked.

Use a configuration

butler-ci-cli config use <name>

Sets a configuration as active for use in Jenkins commands.

View current configuration

butler-ci-cli config current

Shows the currently active configuration.

Delete a configuration

butler-ci-cli config delete [name]
# or use the alias
butler-ci-cli config rm [name]

If you don't specify the name, it will show you a list to select from.

Get Jenkins Token

1. Go to your Jenkins profile → Configure
2. In the "API Token" section, generate a new token
3. Use this token when creating the configuration

Compatibility with environment variables

For compatibility, Butler CI CLI will still work with environment variables if you don't have configurations:

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

🚀 Usage

Configuration Commands

config create

Creates a new Jenkins configuration interactively.

config list / config ls

Lists all available configurations.

config use <name>

Sets a configuration as active.

config current

Shows the currently active configuration.

config delete [name] / config rm [name]

Deletes a configuration (with confirmation).

config edit [name]

Edits configuration preferences (editor, log viewer, download directory).

Jenkins Commands

fetch-jobs

Downloads and saves the list of all available jobs in Jenkins, including those within folders and subfolders.

butler-ci-cli fetch-jobs

list-jobs

Shows all available jobs in Jenkins with hierarchical folder structure.

butler-ci-cli list-jobs
butler-ci-cli list-jobs --folders           # Include folders in the view
butler-ci-cli list-jobs --max-level 2      # Limit depth

show-folders

Shows only the Jenkins folder structure.

butler-ci-cli show-folders
butler-ci-cli show-folders --max-level 3

search-jobs

Searches for jobs by name across the entire Jenkins structure.

butler-ci-cli search-jobs <searchTerm>

job-info <jobName>

Gets detailed information about a specific job. Supports folder paths.

butler-ci-cli job-info my-pipeline-job
butler-ci-cli job-info frontend/build-app
butler-ci-cli job-info backend/microservices/user-service

last-build <jobName>

Shows information about the last executed build of a job. Supports folder paths.

butler-ci-cli last-build my-pipeline-job
butler-ci-cli last-build frontend/build-app

job-params <jobName>

Shows the parameters a job needs to run, including their default values.

butler-ci-cli job-params my-pipeline-job

build <jobName>

Executes a build of a job in an assisted manner. The command will interactively request values for each required parameter.

butler-ci-cli build my-pipeline-job

# You can also pass parameters directly via CLI
butler-ci-cli build my-job --params "ENVIRONMENT=production,VERSION=1.2.3"

logs <jobName> <buildNumber|latest>

View, download, or open logs from a specific build in an editor.

# View logs in terminal
butler-ci-cli logs my-job 42
butler-ci-cli logs my-job latest

# Stream logs in real-time (refreshes every 5 seconds by default)
butler-ci-cli logs my-job 42 --stream
butler-ci-cli logs my-job latest -s

# Stream with custom refresh interval (in seconds)
butler-ci-cli logs my-job 42 --stream --interval 10
butler-ci-cli logs my-job latest -s -i 3

# Download logs to file
butler-ci-cli logs my-job 42 --download
butler-ci-cli logs my-job latest -d

# Open logs in configured editor
butler-ci-cli logs my-job 42 --editor
butler-ci-cli logs my-job latest -e

# Download to specific location
butler-ci-cli logs my-job 42 --download --output /tmp/build.log

list-builds <jobName>

Lists all builds for a specified job with support for filtering, pagination, and sorting.

# List all builds (default: 50 most recent)
butler-ci-cli list-builds my-pipeline-job

# Filter by status
butler-ci-cli list-builds my-job --status SUCCESS
butler-ci-cli list-builds my-job --status FAILURE
butler-ci-cli list-builds my-job --status RUNNING

# Filter by date range
butler-ci-cli list-builds my-job --since 2024-01-01
butler-ci-cli list-builds my-job --since 2024-01-01 --until 2024-12-31

# Pagination
butler-ci-cli list-builds my-job --limit 10
butler-ci-cli list-builds my-job --offset 20 --limit 10

# Sorting
butler-ci-cli list-builds my-job --sort-by timestamp --order asc
butler-ci-cli list-builds my-job --sort-by number --order desc

# Combined filters
butler-ci-cli list-builds my-job --status SUCCESS --since 2024-01-01 --limit 20

Example Workflow

# Create configuration
butler-ci-cli config create              # Create configuration
butler-ci-cli config list               # View configurations
butler-ci-cli config use production     # Switch to production

# Explore Jenkins structure
butler-ci-cli fetch-jobs                # Get all jobs (includes folders)
butler-ci-cli show-folders              # View folder structure only
butler-ci-cli list-jobs --folders       # View jobs and folders

# Search and get specific information
butler-ci-cli search-jobs user          # Search for jobs containing "user"
butler-ci-cli job-info frontend/build   # Info about job in frontend folder
butler-ci-cli last-build backend/api    # Last build of backend/api job

# View parameters and execute builds
butler-ci-cli job-params my-pipeline    # View job parameters
butler-ci-cli build my-pipeline         # Execute build (interactive mode)
butler-ci-cli build my-pipeline --params "ENV=prod,VERSION=1.0.0"

# List and filter builds
butler-ci-cli list-builds my-job              # List recent builds
butler-ci-cli list-builds my-job --status SUCCESS  # Only successful builds
butler-ci-cli list-builds my-job --since 2024-01-01 --limit 20

# Work with logs
butler-ci-cli logs my-job 42            # View logs in terminal
butler-ci-cli logs my-job latest        # View latest build logs
butler-ci-cli logs my-job latest -s     # Stream logs in real-time
butler-ci-cli logs my-job latest -s -i 3  # Stream with 3 second refresh
butler-ci-cli logs my-job 42 -d         # Download logs
butler-ci-cli logs my-job latest -e     # Open latest build in editor

🗂️ Project Structure

butler-ci-cli/
├── src/
│   ├── commands/           # CLI commands
│   │   ├── config/         # Configuration commands
│   │   ├── fetchJobs.ts    # fetch-jobs command
│   │   ├── jobInfo.ts      # job-info command
│   │   ├── build.ts        # build command
│   │   ├── listBuilds.ts   # list-builds command
│   │   └── logs.ts         # logs command
│   ├── utils/              # Utilities
│   │   ├── config.ts       # Configuration management
│   │   ├── jenkinsClient.ts # HTTP client for Jenkins
│   │   └── storage.ts      # Local storage management
│   └── index.ts            # Main entry point
├── tests/                  # Test files
├── docs/                   # Documentation
├── package.json
├── tsconfig.json
└── README.md

🔧 Development

Available Scripts

pnpm run dev      # Run in development mode
pnpm run build    # Build for production
pnpm run start    # Run built version
pnpm run test     # Run tests
pnpm run test:coverage  # Run tests with coverage

Adding New Commands

1. Create a new file in src/commands/
2. Implement the command function
3. Register the command in src/index.ts

📦 Dependencies

Main

• commander: CLI framework
• axios: HTTP client for API calls
• chalk: Terminal colors
• inquirer: Interactive prompts
• pino: Logging

Development

• typescript: Programming language
• vitest: Testing framework
• ts-node: Direct TypeScript execution

🤝 Contributing

Want to contribute? Great! Check out our Contributing Guide for more details.

1. Fork the project
2. Create your feature branch (git checkout -b feature/new-feature)
3. Commit your changes (git commit -am 'feat: add new feature')
4. Push to the branch (git push origin feature/new-feature)
5. Open a Pull Request

📚 Documentation

• README - This guide
• FAQ - Frequently asked questions
• Examples Guide - Practical examples
• Architecture - Technical documentation
• Jenkins API - API guide
• Contributing - Contribution guide
• Changelog - Change history
• Publishing - Publishing guide
• Automated Releases - Automated release workflow guide

📝 License

This project is licensed under the MIT License. See the LICENSE file for more details.

🐛 Bug Reports

If you find a bug or have suggestions, please:

1. Check if a similar issue exists in GitHub Issues
2. Check the FAQ
3. Create a new issue with:
   • Problem description
   • Steps to reproduce
   • Butler CI CLI version (butler-ci-cli --version)
   • Node.js version (node --version)
   • Operating system
   • Error logs (if applicable)

📧 Contact

Author: usarral
Repository: https://github.com/usarral/butler-ci-cli