bktide

Command-line interface for Buildkite CI/CD workflows with rich shell completions (Fish, Bash, Zsh) and Alfred workflow integration for macOS power users.

Features

• 🚀 Workflow Management: View and manage builds, pipelines, organizations, and annotations
• 🔧 Smart Shell Completions: Context-aware completions for Fish, Bash, and Zsh
• 🎯 Alfred Integration: macOS Alfred workflow for quick access to Buildkite data
• 📊 Multiple Output Formats: Plain text, JSON, or Alfred-compatible output
• 🔐 Secure Token Storage: System keychain integration for API credentials
• ⚡ Performance: Built-in caching for faster repeated operations

Installation

npm install -g bktide

Once installed, use the bktide binary directly from your shell.

Shell Completions

bktide supports auto-completion for Fish, Bash, and Zsh shells.

Quick Setup

# Fish
bktide completions fish > ~/.config/fish/completions/bktide.fish

# Bash
echo 'source <(bktide completions bash)' >> ~/.bashrc

# Zsh  
echo 'source <(bktide completions zsh)' >> ~/.zshrc

Completions provide:

• Command suggestions (ie bktide <Tab>)
• Option completions (ie bktide builds --<Tab>)
• Value completions (ie bktide --format <Tab>)
• Dynamic completions for organizations and pipelines (Fish with jq installed)

See Shell Completions Guide for detailed installation and troubleshooting.

Documentation

Our documentation is organized by audience to help you find what you need:

📖 User Documentation - For end users

• Getting Started - Quick start guide for new users
• Authentication - How to authenticate with Buildkite
• Shell Completions - Setting up auto-completion
• Troubleshooting - Common issues and solutions
• Alfred Integration - macOS Alfred workflow (installation, troubleshooting)

👨‍💻 Developer Documentation - For contributors

• Contributing Guide - How to contribute to the project
• Development Guide - Setup and coding guidelines
• Alfred Workflow Development - Building and packaging
• Testing Strategy - Testing approach and procedures

📚 Reference Documentation - For everyone

• Changelogs - What changed and when
• Release Process - How releases work

See Documentation Overview for the complete structure and classification guide.

Testing

Run the test suite with:

npm test                       # Run all tests
npm run test:watch            # Watch mode for development  
npm run test:coverage         # Generate coverage report
npm run test:extract-patterns # Extract patterns from real data (requires token)

See Testing Strategy for details on the hybrid testing approach.

Usage

Show Your Login Information

bktide viewer

List Your Organizations

bktide orgs

List Pipelines in an Organization

bktide pipelines

Additional options:

# Filter by organization
bktide pipelines --org your-org-slug

# Limit the number of results
bktide pipelines --count 20

# Filter pipelines by name
bktide pipelines --filter payments

List Your Builds

bktide builds

Additional options:

# Filter by organization
bktide builds --org your-org-slug

# Filter by pipeline
bktide builds --pipeline pipeline-slug

# Filter by branch
bktide builds --branch main

# Filter by state
bktide builds --state passed

# Pagination
bktide builds --count 20 --page 2

# Output in JSON format
bktide builds --format json

# Output in Alfred-compatible JSON format
bktide builds --format alfred

Show Build Annotations

bktide annotations <build>

The build reference can be specified in two formats:

• Slug format: org/pipeline/number (e.g., gusto/zenpayroll/1287418)
• URL format: https://buildkite.com/org/pipeline/builds/number

Additional options:

# Filter by context
bktide annotations gusto/zenpayroll/1287418 --context rspec

# Output in JSON format
bktide annotations gusto/zenpayroll/1287418 --format json

# Output in plain text format (default)
bktide annotations https://buildkite.com/gusto/zenpayroll/builds/1287418 --format plain

# Combine filtering and formatting
bktide annotations gusto/zenpayroll/1287418 --context build-resources --format json

Show Build Details

View detailed information about a specific build including jobs and annotations.

# View build by slug format
bktide build org/pipeline/123

# View build by URL format
bktide build https://buildkite.com/org/pipeline/builds/123

Additional options:

# Fetch all jobs (handles pagination for large builds)
bktide build org/pipeline/123 --jobs

# Show failure details and error summaries
bktide build org/pipeline/123 --failed

# Include full annotation content
bktide build org/pipeline/123 --annotations

# Combine options for comprehensive view
bktide build org/pipeline/123 --jobs --failed --annotations

Generate Shell Completions

# Generate completions for your shell
bktide completions fish
bktide completions bash
bktide completions zsh

# Auto-detect your shell and generate completions
bktide completions

API Token

You'll need a Buildkite API token with GraphQL scopes. Create one at: https://buildkite.com/user/api-access-tokens

Providing your token

You can provide your token in one of these ways:

• -t, --token <token>: e.g. bktide orgs --token abc123
• BK_TOKEN environment variable: e.g. BK_TOKEN=abc123 bktide orgs
• Store once and reuse: bktide token --store

Manage stored token:

bktide token --check   # See if a token is stored
bktide token --reset   # Remove stored token

Visual Features

The CLI provides a modern visual experience with color-coded information and clear hierarchy:

Color-Coded Build Status

Build statuses are displayed with intuitive colors for quick scanning:

• Blue (✓) - Passed builds
• Orange (✖) - Failed builds
• Cyan (↻) - Running builds
• Yellow (⚠) - Blocked/warning states
• Gray (−) - Skipped/inactive states

Visual Hierarchy

• Bold + underlined headers for table columns
• Cyan highlighting for identifiers (#1234, IDs)
• Magenta for numeric counts
• Dimmed text for auxiliary information and tips
• Arrow indicators (→) for actionable tips

Accessibility

• Colorblind-safe palette - Uses blue/orange instead of green/red
• NO_COLOR support - Set NO_COLOR=1 for no colors
• ASCII mode - Use BKTIDE_ASCII=1 for screen reader compatibility
• Symbols with text fallbacks - Information never relies solely on color

Smart Empty States

When no results are found, helpful suggestions guide you:

No builds found

Try specifying an organization with --org <name>
Use --count to increase the number of results

Enhanced Error Messages

Errors provide clear context and actionable solutions:

✖ Error: Authentication Failed

The provided token is invalid or expired.

To fix this:
  1. Get a new token from Buildkite
  2. Run: bktide token --store
  3. Try your command again

Global Options

These flags work with all commands:

• --log-level <level>: trace|debug|info|warn|error|fatal (default: info)
• -d, --debug: verbose debug output and detailed errors
• --no-cache: disable API response caching
• --cache-ttl <ms>: set cache TTL in milliseconds
• --clear-cache: clear cached data before running
• -t, --token <token>: provide Buildkite API token (or use BK_TOKEN)
• --save-token: save token to system keychain
• -f, --format <format>: plain|json|alfred (affects output and errors)
• --color <mode>: auto|always|never (controls color in plain format)
• -q, --quiet: suppress non-error output (success messages, tips)
• --tips: show helpful tips after operations (default: true)
• --no-tips: hide helpful tips

Output Behavior

• Plain format (default): human-friendly output with color-coded statuses, bold headers, and visual hierarchy. Progress indicators (spinners for indeterminate operations, progress bars for operations with known totals) show during long operations only in interactive TTYs and are cleared on completion (no residual lines). Tips appear dimmed with arrow indicators (→) at the end of output.
• JSON/Alfred formats: strictly machine-readable; no extra lines, no colors, no spinners or confirmations.
• Streams: results go to stdout; errors go through the error formatter. When using --format json|alfred, only the formatted payload is printed.
• Colors: by default --color auto enables color in TTYs with semantic coloring (blue for success, orange for errors, etc.). Use --color never or NO_COLOR=1 to disable. Use --color always to force color in plain output.
• Accessibility: Full functionality without colors - symbols provide visual cues (✓, ✖, ⚠, →) with ASCII fallbacks when BKTIDE_ASCII=1 is set.

Logging System

The CLI uses a structured logging system based on Pino. This provides several benefits:

• Different log levels (trace, debug, info, warn, error, fatal)
• JSON logs saved to disk (in log/cli.log)
• Pretty-printed logs to the console
• Performance measurements

Log Level Configuration

You can configure the log level with the --log-level option:

bktide orgs --log-level=debug  # Show debug messages
bktide builds --log-level=trace # Show all messages including trace

Available log levels (from most to least verbose):

• trace: Very detailed tracing for debugging
• debug: Detailed information for developers
• info: General information (default)
• warn: Warning conditions
• error: Error conditions
• fatal: Severe errors causing termination

Log Files

All logs are written to ~/.local/state/bktide/logs/cli.log in JSON format, which can be processed with tools like jq:

# View recent errors
cat ~/.local/state/bktide/logs/cli.log | grep -v '"level":30' | jq

# Analyze performance 
cat ~/.local/state/bktide/logs/cli.log | jq 'select(.duration != null) | {msg, duration}'