repobird-cli

module

v0.10.0 Latest Latest Go to latest Published: Jun 26, 2026 License: AGPL-3.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/repobird/repobird-cli

Links

Open Source Insights

README ¶

RepoBird CLI

One-shot issue to PR with OpenCode-powered cloud agents

RepoBird CLI is the command-line interface for RepoBird.ai - OpenCode-powered cloud coding agents that handle everything from issue to PR. No chat loop, no local workstation babysitting, no manual Git operations. Write the task once, track the run, and review the PR when it is ready.

🎯 What is RepoBird?

RepoBird provides one-shot coding agents with complete Git automation. Unlike chat-based AI tools that require back-and-forth iterations and manual Git operations, RepoBird is simple: issue in, PR out.

Write your issue description once, and autonomous OpenCode-based agents handle the workflow: repository setup, implementation, testing, commits, and PR creation. Credits are the customer-facing unit for cloud agent work, so RepoBird no longer models availability around fixed Basic/Pro monthly run counts.

Key Features

🚀 One-Shot Execution: No chat, no iterations - write once, ship automatically
🔧 Complete Git Automation: Never touch Git - perfect commits, branches, and PRs every time
⚡ OpenCode Cloud Execution: Launch OpenCode-backed coding agents without tying up your local machine
🤖 Autonomous Agents: Full cycle from repository setup to PR without human intervention
📊 Real-Time Monitoring: Track progress of all parallel runs in the TUI dashboard
🔒 Isolated VM Execution: Each agent runs in its own secure Debian microVM with full development tools
💳 Credit-Based Usage: Runs consume credits based on cloud agent work instead of fixed Basic/Pro run limits
🌐 Complete Dev Environment: Multi-language support, package managers, databases - everything needed to build real software
🤖 AI Agent Skill: .skills/default/SKILL.md teaches coding agents how to install, configure, and use RepoBird CLI

🎯 Why RepoBird?

The Problem with Other AI Tools

IDE-based tools: Run locally with resource constraints, handle one task at a time, require IDE context switching and manual Git operations
Other AI Agents: Chat interfaces requiring multiple iterations, manual PR creation, no parallel execution capabilities, lack native GitHub integration

The RepoBird Difference

GitHub-Native Integration: Lives entirely within your GitHub workflow as a GitHub App. Complete automation from issue to PR - no external tools, no context switching.

Cloud-Based Execution: Launch coding agents in managed cloud environments with full resources and no local constraints.

One-Shot Simplicity: Write your issue once, get a production-ready PR back. No chat, no iterations, no manual steps. 73% of PRs merge without changes.

Complete Git Automation: Our agents handle everything - branching, atomic commits with proper messages, comprehensive PR descriptions. You never touch Git.

Enterprise-Grade Environment: Each agent runs in an isolated cloud VM with full development tools, package managers, and internet access. RepoBird's forward-looking agent workflow is OpenCode-based.

Credit-Based Runs: Credits cover cloud agent work across model usage, orchestration, runtime, logs, and storage. Basic and Pro language may still appear as capability or model-selection presets in some API responses, but it should not be interpreted as fixed monthly run-count availability.

📦 Installation

Quick Install (Linux/macOS)

curl -fsSL https://repobird.ai/install.sh | sh

Windows PowerShell:

iwr -useb https://repobird.ai/install.ps1 | iex

Direct Download

macOS

# Apple Silicon
curl -L https://github.com/RepoBird/repobird-cli/releases/latest/download/repobird-cli_darwin_arm64.tar.gz | tar xz && \
sudo mv repobird /usr/local/bin/

# Intel
curl -L https://github.com/RepoBird/repobird-cli/releases/latest/download/repobird-cli_darwin_amd64.tar.gz | tar xz && \
sudo mv repobird /usr/local/bin/

Linux

curl -L https://github.com/RepoBird/repobird-cli/releases/latest/download/repobird-cli_linux_amd64.tar.gz | tar xz && \
sudo mv repobird /usr/local/bin/

Windows

Download repobird-cli_windows_amd64.zip from the latest release and extract repobird.exe.

Build from Source

# Requires Go 1.20+
git clone https://github.com/RepoBird/repobird-cli.git
cd repobird-cli
make build
sudo cp build/repobird /usr/local/bin/

🚀 Quick Start

1. Install the Agent Skill

Install the default skill so your coding agent knows how to use RepoBird CLI:

npx skills add RepoBird/repobird-cli

Then ask your agent to use the repobird-cli skill when you want it to submit, monitor, or troubleshoot RepoBird runs from your terminal.

2. Get Your API Key

Sign up for a free account at RepoBird.ai and get your API key from Dashboard → API Keys.

3. Authenticate

# One-time setup
repobird login
# Enter your API key when prompted

4. Submit Your First Task (One-Shot)

# Quickest way - direct command with flags (no file needed)
repobird run -r your-org/your-repo -p "Fix the login bug where users get stuck on loading screen"

# Simple cloud-agent presets
repobird basic -r your-org/your-repo "Fix a small bug"  # DeepSeek V4 Flash
repobird pro -r your-org/your-repo "Implement OAuth"    # GLM 5.2

# Push commits to an output branch without opening a PR
repobird run -r your-org/your-repo -p "Update generated docs" --output-branch automation/docs --branch-only

# Self-managed GitLab projects use stored token references, not raw tokens
repobird run -r your-group/your-project -p @task.txt --gitlab-token-reference-id glref_123

# Resend only after reviewing a prompt-risk acknowledgement error
repobird run -r your-org/your-repo -p @reviewed-task.md --acknowledge-prompt-risk

# Retry-safe creation uses an auto-derived key; pass your own key for scripted retries
repobird run -r your-org/your-repo -p @task.txt --idempotency-key task-2026-06-10-auth

# Inside a git repo with an origin remote, the repo can be auto-detected
repobird pro "Fix the login bug where users get stuck on loading screen"

# Or read prompt from a file using @ prefix
echo "Fix the login bug where users get stuck on loading screen" > task.txt
repobird run -r your-org/your-repo -p @task.txt

# Or use a JSON file for more options
echo '{
  "repository": "your-org/your-repo",
  "prompt": "Fix the login bug where users get stuck on loading screen"
}' > fix.json

repobird run fix.json --follow
# That's it. PR will be created automatically. No further action needed.

# Script-friendly wait mode: one JSON object on stdout, stable exit code
repobird run fix.json --wait --json --timeout 45m

📖 Usage Guide

Authentication Management

repobird login          # Interactive login with API key
repobird verify         # Verify your API key is valid
repobird info           # Show authentication status
repobird logout         # Remove stored credentials

# Alternative: Use environment variable
export REPOBIRD_API_KEY=your-api-key

# Optional: disable colored human-readable output
repobird config set color never

Submitting Tasks

# Single task
repobird run task.json --follow
repobird run task.json --wait --json --timeout 45m
repobird basic "Fix a small bug"
repobird pro "Implement OAuth"
repobird run --basic -r myorg/webapp -p "Fix a small bug"
repobird run --pro -r myorg/webapp -p "Implement OAuth"

# If an identical run was submitted in the last 30 seconds, review first, then force if intentional
repobird run -r myorg/webapp -p @task.txt --force

# From different formats
repobird run task.yaml          # YAML format
repobird run task.md            # Markdown with frontmatter
cat task.json | repobird run -  # From stdin

Command	Use When	Default Model
`repobird basic "prompt"`	Quick Basic preset from inside a git repo	DeepSeek V4 Flash
`repobird pro "prompt"`	Quick Pro preset from inside a git repo	GLM 5.2
`repobird run --basic -r owner/repo -p "prompt"`	Basic preset with explicit repository	DeepSeek V4 Flash
`repobird run --pro -r owner/repo -p "prompt"`	Pro preset with explicit repository	GLM 5.2

The basic and pro commands auto-detect the repository from the current git remote when -r/--repo is omitted. After submission, the CLI prints the selected run type and model before showing the run ID/status.

Scripted Run Waiting

Use --wait when automation should block until the created run reaches a terminal state. Combine it with --json to keep stdout machine-readable:

repobird run task.json --wait --json --timeout 45m

With --wait --json, stdout contains one final JSON object with the final or last observed run, exitCode, status, timedOut, and error. Human progress and errors are written to stderr when needed.

Exit-code contract:

Code	Meaning
`0`	Run reached `completed`
`1`	Generic CLI, validation, network, or unexpected error
`2`	Authentication/API key error
`3`	Quota or credits error
`4`	Run reached a non-success terminal state such as `failed` or `cancelled`
`5`	`--wait` timed out before a terminal state

Monitoring & Management

# Check status
repobird status                 # List all runs
repobird status RUN_ID          # Check specific run
repobird status --follow RUN_ID # Live updates
repobird logs RUN_ID            # Inspect agent conversation logs
repobird logs RUN_ID --json     # Current log snapshot as JSON
repobird logs RUN_ID --follow   # Poll for new log messages as NDJSON

# Interactive dashboard
repobird tui                    # Launch terminal UI

Machine-Readable Output

Use --json for scripting. The flag is available globally and on run-related commands, so both repobird --json run ... and repobird run ... --json emit parseable JSON without human progress text.

repobird run -r your-org/your-repo -p "Fix auth" --json
repobird run task.json --dry-run --json
repobird status RUN_ID --json
repobird repo list --json

Run creation emits schema: "repobird.run.create.v1" with operation, success, run, url, and request fields. Dry runs emit schema: "repobird.run.dry_run.v1" with valid and request fields. Development-gated bulk commands use repobird.bulk.create.v1 and repobird.bulk.dry_run.v1.

Repository Defaults

When repository branch defaults are enabled on the API, the CLI can inspect and update persisted defaults. Per-run flags such as --base-branch, --pr-target-branch, --output-branch, and --branch-only still override repository defaults.

repobird repo list
repobird repo show repo_123
repobird repo defaults repo_123 --base develop --pr-target release
repobird repo defaults repo_123 --clear-base --clear-pr-target
repobird repo defaults repo_123 --clear-output  # branch-only runs generate an output branch

The interactive dashboard features a Miller column layout inspired by the ranger file manager, providing hierarchical navigation through repositories → runs → details in a three-column view. This intuitive layout allows you to see context at every level while drilling down into specific run details.

Key	Action
`Tab` / `→`	Navigate forward between columns
`Shift+Tab` / `←`	Navigate backward
`↑` / `↓`	Move selection up/down
`Enter`	Select item
`f`	Fuzzy search in current column
`n`	Create new run
`r`	Refresh data
`?`	Show help
`q`	Quit

Example Templates

# Generate example configurations
repobird examples generate minimal -o task.json
repobird examples schema  # View full schema documentation

📝 Task Configuration

Tasks are defined in JSON, YAML, or Markdown files with two required fields:

repository - Target repository (format: "owner/repo")
prompt - Task description for the AI

Simple Example

{
  "repository": "myorg/webapp",
  "prompt": "Add user authentication with JWT tokens"
}

Advanced Example

{
  "repository": "myorg/webapp",
  "prompt": "Implement OAuth2 authentication",
  "source": "main",
  "target": "feature/oauth",
  "title": "Add OAuth2 support",
  "context": "Use Google and GitHub as providers",
  "files": ["src/auth/", "config/oauth.json"],
  "gitlabCredential": {
    "mode": "stored_token_reference",
    "tokenReferenceId": "glref_123"
  }
}

Managed GitLab.com repositories may not require gitlabCredential. Self-managed GitLab repositories require a stored token reference; never put raw provider tokens in task files, prompts, shell history, or logs.

For complete configuration options and examples, see the Run Configuration Guide.

🛡️ Advanced Features

Smart Caching

Local caching reduces API calls and improves performance
Repository and run data cached for quick access
Automatic cache invalidation on updates

Retry Logic

Automatic exponential backoff for transient failures
Configurable retry attempts and timeouts
Graceful handling of rate limits

📚 Documentation

For the live product documentation, start at repobird.ai/docs.

Getting Started

RepoBird Docs - Product guides, GitHub setup, workflow docs, and feature documentation
Getting Started Guide - Connect GitHub and trigger your first RepoBird run
CLI Quick Start - Install the CLI, authenticate, and submit your first terminal run
Installation Guide - Platform-specific CLI setup instructions
Configuration Guide - Authentication and settings

User Guides

Terminal UI Guide - Master the interactive dashboard
Run Configuration Formats - Task file examples
Branch Workflow - How RepoBird creates branches and pull requests
Troubleshooting Guide - CLI troubleshooting
Error Messages Guide - Product error codes and recovery steps

Reference

CLI Command Reference - Complete command documentation
REST API Reference - Live API reference for RepoBird integrations
OpenAPI Specification - Public OpenAPI YAML for /api/v1
CLI API Notes - CLI REST client implementation details
Keyboard Shortcuts - TUI navigation cheat sheet

Development

Architecture Overview - System design and components
Development Guide - Setup for contributors
Testing Guide - Test strategies and patterns

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Development Setup

# Clone your fork
git clone https://github.com/your-username/repobird-cli.git
cd repobird-cli

# Install dependencies
make deps

# Run tests
make test

# Build locally
make build

📄 License

This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.

🌟 Support

Application Documentation: repobird.ai/docs
Technical/Developer Docs: docs/ - Architecture, API reference, development guides
Issues: GitHub Issues
Discussions: GitHub Discussions

🙏 Acknowledgments

Built with:

Cobra - CLI framework
Bubble Tea - Terminal UI framework
Lipgloss - Terminal styling

Made with ❤️ by the RepoBird team

Directories ¶

Path	Synopsis
cmd
repobird command
internal
api
api/dto
bulk
cache
commands
config
container
domain
errors
idempotency
mock
models
output
prompts
repository
retry
services
tui
tui/cache
tui/components Package components provides reusable UI components for the TUI	Package components provides reusable UI components for the TUI
tui/debug
tui/forms
tui/interfaces
tui/keymap
tui/messages
tui/styles
tui/views
utils
pkg
utils
version
tests
helpers

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL