Buddy Cli

The (Un)official Buddy Works CLI

A PHP CLI tool for managing Buddy.works CI/CD pipelines from the command line. Run pipelines, inspect executions, view logs, manage variables, and export/import pipeline configurations as YAML—all without leaving your terminal.

Works great with LLM assistants for iterative debugging workflows. See Debugging Pipeline Executions for a real-world example.

[!NOTE] The official buddy-works/buddy-cli has been abandoned. This project provides a maintained alternative.

Installation

As a Project Dependency

composer require jtsternberg/buddy-cli --dev

The buddy command is available via vendor/bin/buddy.

Global Installation

composer global require jtsternberg/buddy-cli

Ensure ~/.composer/vendor/bin is in your PATH, then run buddy from anywhere.

From Source

git clone https://github.com/jtsternberg/buddy-cli.git
cd buddy-cli
composer install
./bin/buddy self:install

This creates a symlink in ~/.local/bin/buddy (or similar) for pathless execution.

Shell Completion

Enable tab-completion for commands, options, and arguments. Supports bash, zsh, and fish.

Bash (~/.bashrc):

# buddy-cli completions
eval "$(buddy completion bash)"

Zsh (~/.zshrc):

First generate the completion file:

mkdir -p ~/.buddy-cli/completions
buddy completion zsh > ~/.buddy-cli/completions/_buddy

Then add to ~/.zshrc (before compinit if you call it manually):

# buddy-cli completions
fpath=(~/.buddy-cli/completions $fpath)

Fish (~/.config/fish/config.fish):

# buddy-cli completions
buddy completion fish | source

Authentication

Personal Access Token (Recommended)

Set the BUDDY_TOKEN environment variable, or run:

buddy config:set token <your-token>

OAuth Login

1. Create OAuth Application

Create an OAuth app at buddy.works/api/apps.

For the callback URL, run buddy login --test to start the callback server and verify it works:

buddy login --test
# Outputs: http://127.0.0.1:8085/callback
# Hit the URL in browser or curl to confirm, then register it in Buddy

2. Configure Credentials & Login

Provide your OAuth client ID and secret via one of:

# Option A: Store in config (recommended)
buddy config:set client_id <your-client-id>
buddy config:set client_secret <your-client-secret>

# Option B: Environment variables
export BUDDY_CLIENT_ID=<your-client-id>
export BUDDY_CLIENT_SECRET=<your-client-secret>

Then login:

buddy login

Or pass directly to login command:

buddy login --client-id=<id> --client-secret=<secret>

This opens your browser to authenticate with Buddy and saves your token automatically.

Configuration

Configuration can be set via environment variables, config files, or command-line flags.

Environment Variables

BUDDY_TOKEN=<token>
BUDDY_WORKSPACE=<workspace-name>
BUDDY_PROJECT=<project-name>

Config Files

• User config: ~/.config/buddy-cli/config.json
• Project config: .buddy-cli.json (in project root)

{
  "workspace": "my-workspace",
  "project": "my-project"
}

Precedence

1. Command-line flags (--workspace, --project)
2. Environment variables
3. Project config (.buddy-cli.json)
4. User config (~/.config/buddy-cli/config.json)

Commands

[!TIP] Run buddy <command> --help for detailed documentation including all options, supported fields, and examples.

Pipelines

buddy pipelines:list                      # List all pipelines
buddy pipelines:show <id>                 # Show pipeline details
buddy pipelines:show <id> --yaml          # Output native Buddy YAML configuration
buddy pipelines:run <id>                  # Run a pipeline
buddy pipelines:run <id> --branch=main    # Run with specific branch
buddy pipelines:run <id> --wait           # Run and wait for completion
buddy pipelines:retry <id>                # Retry last failed execution
buddy pipelines:cancel <id>               # Cancel running execution
buddy pipelines:get <id>                  # Get pipeline config as native YAML file
buddy pipelines:create <file>             # Create new pipeline from native YAML file
buddy pipelines:create --name="My Pipeline" --on=MANUAL --refs=refs/heads/main  # Create via flags
buddy pipelines:update <id> <file>        # Update pipeline from native YAML
buddy pipelines:settings <id>             # Show pipeline settings (metadata + variables)
buddy pipelines:settings <id> --update <file>  # Update pipeline settings from YAML

Executions

buddy executions:list --pipeline=<id>              # List recent executions
buddy executions:show <exec-id> --pipeline=<id>    # Show execution details
buddy executions:show <exec-id> --pipeline=<id> --logs     # Include action logs
buddy executions:show <exec-id> --pipeline=<id> --summary  # Compact status overview
buddy executions:failed <exec-id> --pipeline=<id>           # Show failed action details
buddy executions:failed <exec-id> --pipeline=<id> --analyze # Categorize error patterns
buddy executions:actions <exec-id> --pipeline=<id>          # List actions with execution IDs
buddy executions:action-logs <exec-id> <action-exec-id> --pipeline=<id>  # Logs for one action

Actions

buddy actions:list --pipeline=<id>                 # List actions in a pipeline
buddy actions:show <action-id> --pipeline=<id>     # Show action details
buddy actions:show <action-id> --pipeline=<id> --yaml  # Output as YAML configuration
buddy actions:create <file> --pipeline=<id>        # Create new action from YAML file
buddy actions:update <action-id> <file> --pipeline=<id>  # Update action from YAML
buddy actions:delete <action-id> --pipeline=<id>   # Delete action (with confirmation)
buddy actions:delete <action-id> --pipeline=<id> --force  # Delete without confirmation

Projects

buddy projects:list                       # List projects in workspace
buddy projects:show <name>                # Show project details

Variables

buddy vars:list                           # List environment variables
buddy vars:list --project=<name>          # Filter by project
buddy vars:list --pipeline=<id>           # Filter by pipeline
buddy vars:show <id>                      # Show variable details
buddy vars:set <key> <value>              # Create or update variable
buddy vars:set <key> <value> -p <project> # Scope to project
buddy vars:set <key> <value> --encrypted  # Encrypt the value
echo -n "$SECRET" | buddy vars:set <key> - --encrypted   # Read secret from stdin (keeps it off argv/history)
buddy vars:set <key> --value-file=<path> --encrypted     # Read value from a file
buddy vars:delete <id>                    # Delete variable (with confirmation)
buddy vars:delete <id> --force            # Delete without confirmation

Configuration

buddy config:show                         # Show current configuration
buddy config:set <key> <value>            # Set configuration value
buddy config:clear                        # Clear all configuration
buddy config:validate                     # Validate config is complete
buddy config:validate --test-api          # Also test API connectivity

Documentation

• Ask questions in NotebookLM - Interactive Q&A about buddy-cli
• Debugging Pipeline Executions - Real-world walkthrough of diagnosing and fixing a failed pipeline run

Options

All commands support:

• --workspace, -w - Workspace name
• --project, -p - Project name
• --json - Output as JSON

Claude Code Plugin

This repository includes a Claude Code plugin for AI-assisted CI/CD management. Control deployments and debug pipelines using natural language.

Quick Example

You: "Deploy to production and wait for it to finish"
You: "Why did my last build fail?"
You: "Show me what's currently running"

Installation

In Claude Code:

/plugin marketplace add jtsternberg/buddy-cli
/plugin install buddy-cli

Or point to your existing copy of the buddy-cli repository:

/plugin marketplace add ./buddy-cli
/plugin install buddy-cli

Features

• Skills: Auto-invoked when discussing pipelines, deployments, or build failures
• Commands: /buddy-cli:deploy, /buddy-cli:status, /buddy-cli:logs
• Agent: CI/CD specialist for complex multi-step workflows

See claude-plugin/.claude-plugin/README.md for full documentation.

Development

This repository uses Beads for issue tracking—an AI-native system that stores issues directly in the repo. See .beads/README.md for details.

License

MIT