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.
composer require jtsternberg/buddy-cli --devThe buddy command is available via vendor/bin/buddy.
composer global require jtsternberg/buddy-cliEnsure ~/.composer/vendor/bin is in your PATH, then run buddy from anywhere.
git clone https://github.com/jtsternberg/buddy-cli.git
cd buddy-cli
composer install
./bin/buddy self:installThis creates a symlink in ~/.local/bin/buddy (or similar) for pathless execution.
Enable tab-completion for commands, options, and arguments. Supports bash, zsh, and fish.
# buddy-cli completions
eval "$(buddy completion bash)"First generate the completion file:
mkdir -p ~/.buddy-cli/completions
buddy completion zsh > ~/.buddy-cli/completions/_buddyThen add to ~/.zshrc (before compinit if you call it manually):
# buddy-cli completions
fpath=(~/.buddy-cli/completions $fpath)# buddy-cli completions
buddy completion fish | sourceSet the BUDDY_TOKEN environment variable, or run:
buddy config:set token <your-token>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 BuddyProvide 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 loginOr 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 can be set via environment variables, config files, or command-line flags.
BUDDY_TOKEN=<token>
BUDDY_WORKSPACE=<workspace-name>
BUDDY_PROJECT=<project-name>- User config:
~/.config/buddy-cli/config.json - Project config:
.buddy-cli.json(in project root)
{
"workspace": "my-workspace",
"project": "my-project"
}- Command-line flags (
--workspace,--project) - Environment variables
- Project config (
.buddy-cli.json) - User config (
~/.config/buddy-cli/config.json)
Tip
Run buddy <command> --help for detailed documentation including all options, supported fields, and examples.
buddy pipelines:list # List all pipelines
buddy pipelines:show <id> # Show pipeline details
buddy pipelines:show <id> --yaml # Output as 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 YAML file
buddy pipelines:create <file> # Create new pipeline from YAML file
buddy pipelines:update <id> <file> # Update existing pipeline from YAMLbuddy 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 patternsbuddy 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 confirmationbuddy projects:list # List projects in workspace
buddy projects:show <name> # Show project detailsbuddy 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
buddy vars:delete <id> # Delete variable (with confirmation)
buddy vars:delete <id> --force # Delete without confirmationbuddy 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- Ask questions in NotebookLM - Interactive Q&A about buddy-cli
- Debugging Pipeline Executions - Real-world walkthrough of diagnosing and fixing a failed pipeline run
All commands support:
--workspace,-w- Workspace name--project,-p- Project name--json- Output as JSON
This repository includes a Claude Code plugin for AI-assisted CI/CD management. Control deployments and debug pipelines using natural language.
You: "Deploy to production and wait for it to finish"
You: "Why did my last build fail?"
You: "Show me what's currently running"
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
- 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.
This repository uses Beads for issue tracking—an AI-native system that stores issues directly in the repo. See .beads/README.md for details.
MIT