reposwarm-cli

Install

curl -fsSL https://raw.githubusercontent.com/reposwarm/reposwarm-cli/main/install.sh | sh

git clone https://github.com/reposwarm/reposwarm-cli.git
cd reposwarm-cli
go build -o reposwarm ./cmd/reposwarm

🤖 Agent-Native

# Agent gets JSON output
reposwarm status --for-agent --json

# Full local setup — zero human interaction needed
reposwarm new --local --for-agent

# Configure provider non-interactively
reposwarm config provider setup --provider bedrock --auth-method iam-role --region us-east-1 --non-interactive

# Debug logs (truncated at 5000 chars, with path to full file)
reposwarm debug-logs --for-agent

# Investigate and get results
reposwarm investigate https://github.com/org/repo --for-agent
reposwarm results read my-repo --for-agent

Prerequisites

Cookbook

🚀 First Time Setup (Local)

reposwarm new --local             # Bootstrap everything: Temporal, API, Worker, UI
reposwarm status                  # Verify connection
reposwarm doctor                  # Full health check
reposwarm show ui                 # Open the web UI

🚀 First Time Setup (Remote Server)

reposwarm config init             # Interactive setup (enter API URL + token)
reposwarm status                  # Verify connection

🔍 Run Your First Investigation

reposwarm repos add my-app --url https://github.com/org/my-app
reposwarm investigate my-app      # Pre-flight checks run automatically
reposwarm wf progress             # Watch it work
reposwarm results sections my-app # Browse the results
reposwarm results read my-app     # Read the full report

🔍 Investigate All Repos

reposwarm investigate --all --parallel 3
reposwarm dashboard               # Live TUI — progress for every repo

🔍 Check Before You Start (Dry Run)

reposwarm preflight my-app        # System + repo readiness check
reposwarm investigate my-app --dry-run  # Pre-flight only, no workflow created

🩺 Something's Stuck — Full Diagnosis

# Step 1: What's wrong?
reposwarm doctor

# Step 2: Full install log (paged for humans, text dump for agents)
reposwarm debug-logs

# Step 3: Check for stalled workflows + worker errors
reposwarm errors

# Step 3: Zoom in on a specific workflow
reposwarm wf status <workflow-id> -v

# Step 4: See the Temporal event timeline
reposwarm wf history <workflow-id>

# Step 5: Check worker logs directly
reposwarm logs worker -f

🔧 Fix Missing Environment Variables

# See what's set and what's missing
reposwarm config worker-env list

# Set the missing vars
reposwarm config worker-env set ANTHROPIC_API_KEY sk-ant-your-key-here
reposwarm config worker-env set GITHUB_TOKEN ghp_your-token-here

# Restart the worker to pick up changes
reposwarm restart worker --wait

# Verify it's healthy now
reposwarm doctor

🔧 Configure LLM Provider

Anthropic (Direct API)

# Interactive
reposwarm config provider setup

# Non-interactive
reposwarm config provider setup \
  --provider anthropic \
  --api-key sk-ant-api03-YOUR-KEY \
  --model sonnet \
  --non-interactive

Amazon Bedrock

# IAM role (EC2 instance profile / ECS task role — recommended)
reposwarm config provider setup \
  --provider bedrock \
  --auth-method iam-role \
  --region us-east-1 \
  --model opus \
  --non-interactive

# AWS access keys
reposwarm config provider setup \
  --provider bedrock \
  --auth-method access-keys \
  --aws-key AKIA... \
  --aws-secret wJalr... \
  --region us-east-1 \
  --model sonnet \
  --non-interactive

# AWS SSO / Identity Center
reposwarm config provider setup \
  --provider bedrock \
  --auth-method sso \
  --aws-profile my-sso-profile \
  --region us-west-2 \
  --model sonnet \
  --non-interactive

# Named AWS profile (~/.aws/credentials)
reposwarm config provider setup \
  --provider bedrock \
  --auth-method profile \
  --aws-profile prod \
  --region us-east-1 \
  --model opus \
  --non-interactive

# Bedrock API keys (from AWS Console → Bedrock → API keys)
reposwarm config provider setup \
  --provider bedrock \
  --auth-method api-keys \
  --bedrock-key br-... \
  --region us-east-1 \
  --model sonnet \
  --non-interactive

Using OpenAI, Gemini, or Other Models via LiteLLM

pip install litellm

# OpenAI
litellm --model openai/gpt-4o --port 4000

# Google Gemini
GEMINI_API_KEY=your-key litellm --model gemini/gemini-2.5-pro --port 4000

# Or use a config file for multiple models:
# See https://docs.litellm.ai/docs/proxy/configs
litellm --config litellm_config.yaml --port 4000

# OpenAI via LiteLLM
reposwarm config provider setup \
  --provider litellm \
  --proxy-url http://localhost:4000 \
  --proxy-key sk-your-litellm-key \
  --model openai/gpt-4o \
  --non-interactive

# Google Gemini via LiteLLM
reposwarm config provider setup \
  --provider litellm \
  --proxy-url http://localhost:4000 \
  --model gemini/gemini-2.5-pro \
  --non-interactive

# Any other LiteLLM-supported model
reposwarm config provider setup \
  --provider litellm \
  --proxy-url https://my-proxy.example.com \
  --proxy-key sk-proxy-key \
  --model mistral/mistral-large-latest \
  --non-interactive

Provider Management

# Quick-switch provider (keeps other settings)
reposwarm config provider set bedrock
reposwarm config provider set anthropic --check

# Check what's configured (detects CLI vs worker drift)
reposwarm config provider show

# List available model aliases
reposwarm config model list

# Pin model versions (prevents silent version drift)
reposwarm config model pin

# Restart worker to apply changes
reposwarm restart worker

🔧 Configure Git Provider

# Interactive setup
reposwarm config git setup

# Direct set
reposwarm config git set github        # GitHub (needs GITHUB_TOKEN)
reposwarm config git set codecommit    # AWS CodeCommit (needs IAM + AWS CLI)
reposwarm config git set gitlab        # GitLab (needs GITLAB_TOKEN)
reposwarm config git set azure         # Azure DevOps (needs AZURE_DEVOPS_PAT + ORG)
reposwarm config git set bitbucket     # Bitbucket (needs USERNAME + APP_PASSWORD)

# Show current config + required env vars
reposwarm config git show

reposwarm doctor
# Worker Environment
#   ✗ GITHUB_TOKEN — NOT SET — GitHub personal access token
#      Set it: reposwarm config worker-env set GITHUB_TOKEN <value>

📋 View Changelog

reposwarm changelog                    # Current version's release notes
reposwarm changelog v1.3.50            # Specific version
reposwarm changelog latest             # Latest release
reposwarm changelog --all              # All releases with dates
reposwarm changelog --since v1.3.45    # Cumulative changes since a version

⬆️ Upgrade Components

reposwarm upgrade                      # Upgrade CLI to latest
reposwarm upgrade api                  # Upgrade API server (git pull + build + restart)
reposwarm upgrade ui                   # Upgrade UI
reposwarm upgrade all                  # Upgrade all components

🌐 Remote Access via SSH Tunnel

reposwarm tunnel                       # Shows copy-paste SSH tunnel command

🗑️ Uninstall

reposwarm uninstall                    # Interactive removal
reposwarm uninstall --force            # Skip confirmation
reposwarm uninstall --keep-config      # Keep ~/.reposwarm for reinstall

🔧 Fix a Stuck Investigation (End-to-End)

reposwarm doctor                  # → finds: ANTHROPIC_API_KEY NOT SET
reposwarm config worker-env set ANTHROPIC_API_KEY sk-ant-xxx
reposwarm config worker-env set GITHUB_TOKEN ghp_xxx
reposwarm restart worker --wait   # → ✅ worker-1 healthy
reposwarm wf retry <workflow-id>  # → terminates old, starts new
reposwarm wf progress             # → watch it go

🔧 Replace a Stuck Investigation

# Terminates any existing workflow for this repo, then starts fresh
reposwarm investigate my-app --replace

🔧 Retry a Failed Investigation with a Different Model

reposwarm wf retry <workflow-id> --model us.anthropic.claude-opus-4-6

📊 Monitor Running Investigations

# Live dashboard (htop-style, all repos)
reposwarm dashboard

# Focus on one repo
reposwarm dashboard --repo my-app

# Watch a specific workflow with step checklist
reposwarm wf progress --repo my-app --wait

# Quick snapshot for scripts/agents
reposwarm dashboard --json
reposwarm errors --json

📊 Check Worker Health

# List all workers
reposwarm workers list

# Deep-dive on a specific worker
reposwarm workers show worker-1

# See all services (Docker containers or processes)
reposwarm services

🔎 Search and Explore Results

# Search across all investigations
reposwarm results search "authentication" --max 10

# Read a specific section
reposwarm results read my-app authentication

# Compare two repos
reposwarm results diff repo-a repo-b

# Export everything to markdown files
reposwarm results export --all -d ./docs

# Audit completeness (all 17 sections present?)
reposwarm results audit

📖 Query Architecture Results — ask CLI

# Install ask
curl -fsSL https://raw.githubusercontent.com/reposwarm/ask-cli/main/install.sh | sh

# Set up local askbox (auto-detects RepoSwarm config)
ask setup

# Query your architecture
ask "how does auth work across services?"
ask results list
ask results search "DynamoDB"
ask results export --all -d ./docs

🧹 Cleanup and Maintenance

# Clean up old workflows (completed/failed/terminated)
reposwarm wf prune --older 7d --dry-run    # Preview first
reposwarm wf prune --older 7d -y           # Actually prune

# Prune only failed workflows
reposwarm wf prune --status failed -y

# Gracefully cancel a running investigation (finishes current step)
reposwarm wf cancel <workflow-id>

# Hard terminate (immediate)
reposwarm wf terminate <workflow-id> -y

⚙️ Service Management (Local Mode)

# See what's running
reposwarm services

# Restart everything
reposwarm restart

# Restart just the worker
reposwarm restart worker --wait

# Stop/start individual services
reposwarm stop worker
reposwarm start worker --wait

# Check all service URLs
reposwarm url all

🤖 Agent / Script Integration

# Check system health programmatically
reposwarm doctor --json | jq '.checks[] | select(.status=="fail")'

# Get all errors as JSON
reposwarm errors --json | jq '.workerErrors, .stalls, .errors'

# Single dashboard snapshot (no TUI, exits immediately)
reposwarm dashboard --json

# Pre-flight check before scripted investigation
reposwarm preflight my-app --json | jq '.ready'

# Investigate with no prompts
reposwarm investigate my-app --force --json

# Worker status for monitoring
reposwarm workers list --json | jq '.workers[] | {name, status, envStatus}'

# Service health for monitoring
reposwarm services --json | jq '.[] | {name, status, pid}'

Command Reference

Setup & Configuration

Diagnostics

Workers & Services

Repositories

Investigation & Workflows

Results & Analysis

Architecture Queries (Askbox)

Prompts

Global Flags

Environment Variables

Provider Environment Variables

Git Provider Environment Variables

Model Alias Resolution

Configurable Keys

Development

go test ./...              # Tests
go vet ./...               # Lint
go build ./cmd/reposwarm   # Build

Ecosystem

License