CLI Commands

npm install -g @orchagent/cli

Want AI to DO something now?
  |-- Need it local/private? --> orch run --local
  \-- Want managed infra?    --> orch run

Want AI to KNOW something?
  \-- Download knowledge     --> orch skill install

Want to DELEGATE to sub-agents?
  \-- Export for AI tools    --> orch install

Building an agent locally?
  \-- HTTP dev server        --> orch dev

Want to RECONSTRUCT a local project?
  \-- Pull published source    --> orch pull

Want to CUSTOMIZE an existing agent?
  \-- Copy into your workspace --> orch fork

Managing agents?
  |-- List your agents       --> orch agents
  |-- Inspect details        --> orch info / orch tree
  \-- Move between workspaces --> orch transfer

Managing secrets & keys?
  |-- Workspace secrets      --> orch secrets
  \-- Agent service keys     --> orch agent-keys

Connecting GitHub?
  \-- Import from repos      --> orch github

Debugging a run?
  |-- View execution logs    --> orch logs
  |-- Replay a failed run    --> orch replay
  |-- Inspect trace timeline --> orch trace
  \-- View call graph        --> orch dag

Checking platform health?
  \-- Service status         --> orch status

# Run agent with a URL input
orch run joe/leak-finder https://github.com/user/repo

# Run with JSON input
orch run joe/summarizer --data '{"text": "..."}'

# Just download without running
orch run joe/leak-finder --download-only

# Auto-download all dependencies
orch run joe/security-review --with-deps https://github.com/user/repo

# Override LLM provider and model
orch run joe/summarizer --data '{"text":"..."}' --provider openai --model gpt-4o-mini

# List latest version of each agent
orch agents

# Filter by name
orch agents --filter scanner

# Show all versions
orch agents --all-versions

# JSON output
orch agents --json

# Show agent info
orch info joe/code-reviewer

# Show specific version
orch info joe/code-reviewer@v2

# JSON output
orch info joe/code-reviewer --json

# Show dependency tree
orch tree joe/security-review

# JSON output
orch tree joe/security-review --json

# Disable colors
orch tree joe/security-review --no-color

# Transfer agent to another workspace
orch transfer my-agent --to team-workspace

# Transfer from a specific source workspace
orch transfer my-agent --to team-workspace --workspace my-team

# Preview what would happen
orch transfer my-agent --to team-workspace --dry-run

# Skip confirmation prompt
orch transfer my-agent --to team-workspace --yes

# Install to home directory (available in all projects)
orch install joe/code-reviewer

# Install to current project only
orch install joe/code-reviewer --scope project

# Same as --scope user (matches skill install syntax)
orch install joe/code-reviewer --global

# Specify format (default: claude-code)
orch install joe/code-reviewer --format cursor

# Install to multiple formats
orch install joe/code-reviewer --format claude-code,cursor

# Preview what would be installed
orch install joe/code-reviewer --dry-run

# Specify version
orch install joe/code-reviewer@v2

# Update all installed agents
orch update

# Update specific agent
orch update joe/code-reviewer

# Check for updates without installing
orch update --check

# Force update even if locally modified
orch update --force

# List formats
orch formats

# JSON output
orch formats --json

Available export formats:

  claude-code    Claude Code Sub-Agent
                 Supports: agent, skill
                 Format version: 2026-01
                 user: ~/.claude/agents/
                 project: ./.claude/agents/

  cursor         Cursor Rules
                 Supports: agent, skill
                 Format version: 2026-01
                 user: ~/.cursor/rules/
                 project: ./.cursor/rules/

  agents-md      AGENTS.md (Universal)
                 Supports: agent, skill
                 Format version: 1.0
                 project: ./AGENTS.md

Use with: orch install <agent> --format <id>
Set default: orch config set default-format <ids>

# List installed agents
orch list

# Show format details for each installation
orch list --verbose

# Clean up orphaned entries (tracked files that no longer exist)
orch list --verify

# JSON output
orch list --json

# Install to current directory (project-specific)
orch skill install yourorg/react-best-practices

# Install to home directory (global)
orch skill install yourorg/react-best-practices --global

# Specify version
orch skill install yourorg/react-best-practices@v2

# Specify format(s)
orch skill install yourorg/react-best-practices --format claude-code,cursor

# Install to all supported AI tool directories
orch skill install yourorg/react-best-practices --all-formats

# Preview what would be installed
orch skill install yourorg/react-best-practices --dry-run

# JSON output for scripting
orch skill install yourorg/react-best-practices --json

./.claude/skills/react-best-practices.md
./.cursor/skills/react-best-practices.md
./.codex/skills/react-best-practices.md
./.agent/skills/react-best-practices.md

~/.claude/skills/react-best-practices.md
~/.cursor/skills/react-best-practices.md
~/.codex/skills/react-best-practices.md
~/.agent/skills/react-best-practices.md

# Add skills to an agent run
orch run acme/code-reviewer code.py --skills yourorg/react-best-practices

# Use ONLY specific skills (ignore agent's default_skills)
orch run acme/code-reviewer code.py --skills-only yourorg/react-rules

# Ignore all skills
orch run acme/code-reviewer code.py --no-skills

# Interactive mode (recommended)
orch login

# Non-interactive mode (for CI/CD)
orch login --key sk_live_xxx

orch logout

orch whoami

# Set active workspace
orch workspace use marketing-team

# These now look in marketing-team workspace:
orch run my-agent --data '{}'         # → marketing-team/my-agent
orch run --local my-agent --input '{}' # → marketing-team/my-agent
orch install my-agent                 # → marketing-team/my-agent
orch skill install my-skill           # → marketing-team/my-skill

# Explicit org always overrides workspace:
orch run other-team/my-agent --data '{}' # → other-team/my-agent

# List workspaces (→ marks active)
orch workspace list

# JSON output
orch workspace list --json

# Create a workspace (slug auto-generated)
orch workspace create "My Team"

# Create with custom slug
orch workspace create "My Team" --slug my-team

orch workspace use my-team

# List members of current workspace
orch workspace members

# List members of specific workspace
orch workspace members my-team

# Invite with default role (member)
orch workspace invite [email protected]

# Invite as owner
orch workspace invite [email protected] --role owner

orch workspace leave

# Create an agent (default: direct LLM, on-demand)
orch init my-agent

# Create a JavaScript tool agent
orch init my-tool --type tool --language javascript

# Create a JavaScript Discord bot from template
orch init my-bot --template discord-js

# Create an agent with a specific run mode
orch init my-agent --run-mode always_on

# Create a skill
orch init my-skill --type skill

# Initialize in the current directory (no subdirectory created)
orch init

# Scaffold in current directory
orch scaffold orchestration acme/scanner acme/auditor@v2

# Scaffold into a new directory with an explicit orchestrator name
orch scaffold orchestration acme/scanner --output ./security-orch --name security-orchestrator

# Overwrite existing scaffold files
orch scaffold orchestration acme/scanner --force

# Preview what would be published
orch publish --dry-run

# Publish your agent
orch publish

# Publish all agents in subdirectories (dependency order)
orch publish --all

# Preview batch publish plan
orch publish --all --dry-run

# Publish with default skills
orch publish --skills yourorg/style@v1,yourorg/rules@v1

# Publish with local download enabled (allows orch run --local)
orch publish --local-download

# Pull an agent into a local directory
orch pull acme/my-agent

# Pull a specific version
orch pull acme/my-agent@v2

# Pull using short ref (uses workspace/default-org)
orch pull my-agent

# Pull into a custom directory
orch pull acme/my-agent --output ./custom-dir

# Overwrite an existing directory
orch pull acme/my-agent --overwrite

# Machine-readable output (still writes files)
orch pull acme/my-agent --json

# Delete latest version (prompts for confirmation)
orch delete yourorg/my-agent

# Delete a specific version
orch delete yourorg/my-agent@v2

# Skip confirmation prompt
orch delete yourorg/my-agent -y

# Preview what would be deleted
orch delete yourorg/my-agent --dry-run

# Fork latest version into your current workspace
orch fork orchagent/security-agent

# Fork a specific version into a target workspace
orch fork orchagent/security-agent@v2 --workspace acme-corp

# Fork with a custom name
orch fork orchagent/security-agent --name my-security-scanner

# JSON output for scripting
orch fork orchagent/security-agent --json

# Run tests in current directory
orch test

# Run tests in a specific directory
orch test ./my-agent

# Verbose output
orch test --verbose

# Watch mode - re-run on file changes
orch test --watch

{
  "input": {"text": "Hello world"},
  "expected_output": {"greeting": "Hello!"},
  "expected_contains": ["Hello"],
  "description": "Tests greeting response"
}

{
  "description": "Orchestrator aggregates scan results",
  "input": {"code": "import os; os.getenv('SECRET')"},
  "mocks": {
    "scan_secrets": {"findings": [{"type": "env_access", "severity": "medium"}]},
    "scan_deps": {"vulnerabilities": []}
  },
  "expected_contains": ["env_access", "medium"]
}

# Start dev server in current directory
orch dev

# Start dev server for agent in a specific directory
orch dev ./my-agent

# Use a custom port
orch dev --port 3001

# Show detailed execution output
orch dev --verbose

# Disable file watching (no hot-reload)
orch dev --no-watch

# Terminal 1: Start the dev server
orch dev

# Terminal 2: Send requests
curl -X POST http://localhost:4900/run \
  -H "Content-Type: application/json" \
  -d '{"task": "summarize this text", "text": "..."}'

# Estimate cost for an agent
orch estimate yourorg/my-agent

# Estimate a specific version
orch estimate yourorg/my-agent@v2

# JSON output for scripting
orch estimate yourorg/my-agent --json

yourorg/my-agent@v1
========================================

Type: agent
Engine: managed_loop
Providers: anthropic, openai

Cost Estimate (25 runs, last 30d)
----------------------------------------
  Average:   $0.015
  Median:    $0.012
  95th pct:  $0.045

Tokens (avg per run)
  Input:  1.5k
  Output: 500

Duration
  Average: 3.2s
  Success: 96%

By Provider
  anthropic (claude-haiku-4-5-20251001): $0.012 avg · 20 runs
  openai (gpt-4o-mini): $0.020 avg · 5 runs

orch run yourorg/my-agent --data '{"text": "..."}' --estimate

# Compare two specific versions
orch diff yourorg/my-agent@v1 v2

# Compare against latest
orch diff yourorg/my-agent@v1

# Compare two different agents
orch diff yourorg/agent-a@v1 otherorg/agent-b@v1

# JSON output for scripting
orch diff yourorg/my-agent@v1 v2 --json

# List secrets (names and metadata, never values)
orch secrets list

# List secrets in a specific workspace
orch secrets list --workspace acme-team

# JSON output
orch secrets list --json

# Create or update a secret
orch secrets set ANTHROPIC_API_KEY sk-ant-xxx

# Set with a description
orch secrets set STRIPE_SECRET_KEY sk_live_xxx --description "Production Stripe key"

# Delete a secret
orch secrets delete OLD_API_KEY

# List keys for an agent
orch agent-keys list my-agent

# Create a new key
orch agent-keys create my-agent

# Delete a key
orch agent-keys delete my-agent key_abc123

# List environments in your workspace
orch env list

# JSON output
orch env list --json

# Check build status
orch env status <environment-id>

# Create from Dockerfile
orch env create --file ./Dockerfile --name my-env

# Delete an environment
orch env delete <environment-id>

# Set workspace default environment
orch env set-default <environment-id>

# Clear workspace default (revert to base image)
orch env clear-default

# Install the GitHub App
orch github connect

# Remove GitHub connection
orch github disconnect

# Check connection status
orch github status
orch github status --json

# Scan a repo for agents and skills
orch github scan owner/repo
orch github scan owner/repo --json

# Import an agent from GitHub
orch github import owner/repo
orch github import owner/repo --path agents/my-agent
orch github import owner/repo --name custom-name --json

# View or update sync configuration
orch github sync-config <agent-id>
orch github sync-config <agent-id> --set-auto-publish true

# Approve a pending sync
orch github approve <agent-id>

# List recent runs
orch logs

# Filter by agent name
orch logs scanner

# Filter by status
orch logs --status failed

# View detailed logs for a specific run
orch logs a1b2c3d4-e5f6-7890-abcd-ef1234567890

# View logs using a short run ID prefix (7+ hex chars)
orch logs a1b2c3d

# Limit results
orch logs --limit 50

# JSON output
orch logs --json

# Run security test
orch security test my-org/my-agent@latest

# Filter by attack categories
orch security test my-org/my-agent@v1 --categories persona_roleplay logic_trap

# Filter by severity
orch security test my-org/my-agent@v1 --severities critical high

# Limit number of attacks
orch security test my-org/my-agent@v1 --max-attacks 10

# Output as markdown report
orch security test my-org/my-agent@v1 --output markdown --output-file report.md

# JSON output
orch security test my-org/my-agent@v1 --output json

# Replay a run and wait for results
orch replay a1b2c3d4-e5f6-7890-abcd-ef1234567890

# Replay using a short run ID prefix
orch replay a1b2c3d4

# Queue the replay and return immediately
orch replay a1b2c3d4 --no-wait

# Replay with a reason (stored in audit log)
orch replay a1b2c3d4 --reason "debugging timeout issue"

# Replay with a different provider policy
orch replay a1b2c3d4 --override-policy policy-abc

# JSON output
orch replay a1b2c3d4 --json

Replay bbbbbbbb-cccc-dddd-eeee-ffffffffffff
  Agent:    joe/scanner@v2
  Status:   completed
  Duration: 1.5s

── Output ─────────────────────────────────
{"findings": [], "summary": "No issues found."}

── Stdout ─────────────────────────────────
Scanning repository...
Done.

View trace: orch trace bbbbbbbb-cccc-dddd-eeee-ffffffffffff

# View trace for a run
orch trace a1b2c3d4-e5f6-7890-abcd-ef1234567890

# View trace using a short run ID prefix
orch trace a1b2c3d4

# JSON output (includes full event details)
orch trace a1b2c3d4 --json

Trace for a1b2c3d4-e5f6-...
  Agent:    joe/scanner@v2
  Status:   completed
  Duration: 3.2s

── Timeline ─────────────────────────────────
  # 1  ✔ LLM  anthropic / claude-haiku-4-5-20251001 │ 1,200 in, 350 out │ $0.0004 │ 1.2s
  # 2  ✔ Tool scan-repo │ 1.5s
  # 3  ✔ LLM  anthropic / claude-haiku-4-5-20251001 │ 2,100 in, 180 out │ $0.0005 │ 0.8s

── Summary ─────────────────────────────────
  LLM calls:  2
  Tool calls: 1
  Tokens:     3,300 in, 530 out
  Cost:       $0.0009
  Providers:  anthropic

# Show metrics for the last 30 days (default)
orch metrics

# Show metrics for the last 7 days
orch metrics --days 7

# Filter to a specific agent
orch metrics --agent scanner

# Use a specific workspace
orch metrics --workspace acme-corp

# JSON output for scripting
orch metrics --json

Agent Metrics (last 30d)
==================================================

  Total Runs:   150
  Success Rate: 93.3%
  Error Rate:   6.7% (8 failed, 2 timeout)
  p50 Latency:  1.2s
  p95 Latency:  4.5s
  Avg Latency:  1.8s
  Runs/Day:     5

Per Agent
------------------------------------------------------------------------------------------
Agent                       Runs   Success       p50       p95  Errors  Top Error
------------------------------------------------------------------------------------------
scanner                      100      96%     800ms     3.2s       4  SANDBOX_TIMEOUT
review-agent                  50      88%     2.5s     8.0s       6  LLM_RATE_LIMIT

# View DAG for a run
orch dag a1b2c3d4-e5f6-7890-abcd-ef1234567890

# View DAG using a short run ID prefix
orch dag a1b2c3d4

# Live mode — polls for updates while the run is active
orch dag a1b2c3d4 --live

# Custom poll interval (default: 2 seconds)
orch dag a1b2c3d4 --live --interval 5

# JSON output
orch dag a1b2c3d4 --json

Orchestration DAG [LIVE]
  Root:     a1b2c3d4...
  Agents:   3
  Duration: 8.0s
  Cost:     $0.0150
  Status:   2 completed, 1 active
  Costly:   orchestrator

  ✓ orchestrator v1
    completed | 8.0s | $0.0050 | claude-sonnet-4-20250514 (2 LLM, 1 tool, 1.2K tok)
    └── ✓ audit-agent v2
          completed | 5.0s | $0.0060 | claude-haiku-4-5-20251001 (1 LLM, 1 tool, 950 tok)
          └── ✓ scanner-tool v1
                completed | 3.0s | $0.0040 (2 tool, 600 tok)

View trace:  orch trace a1b2c3d4
View logs:   orch logs a1b2c3d4

# Set default export format(s)
orch config set default-format claude-code,cursor

# Set default scope
orch config set default-scope user

# Set default LLM provider (used when --provider flag is omitted)
orch config set default-provider gemini

# Get current value
orch config get default-format

# List all config values
orch config list

{
  "api_key": "sk_live_xxx",
  "api_url": "https://api.orchagent.io",
  "default_org": "myorg",
  "workspace": "optional-workspace-slug",
  "profiles": {
    "staging": {
      "api_key": "sk_staging_xxx",
      "api_url": "https://staging.api.orchagent.io"
    }
  },
  "default_formats": ["claude-code", "cursor"],
  "default_scope": "user"
}

# Check your setup
orch doctor

# Show extra details
orch doctor --verbose

# JSON output
orch doctor --json

# Basic health check
orch health acme/my-agent

# Health check a specific version
orch health acme/my-agent@v2

# JSON output (for CI/CD pipelines)
orch health acme/my-agent --json

# Custom input instead of auto-generated
orch health acme/my-agent --data '{"query": "test"}'

# Custom timeout (default: 30s)
orch health acme/my-agent --timeout 60000

✔ PASS joe/my-agent@v1 — 2340ms

  Resolve:  pass
  Execute:  pass
  Run ID:   run_abc123
  Logs:     orch logs run_abc123

{
  "agent": "joe/my-agent",
  "version": "v1",
  "status": "pass",
  "latency_ms": 2340,
  "run_id": "run_abc123",
  "checks": {
    "resolve": "pass",
    "execute": "pass"
  }
}

# Check service status
orch status

# JSON output
orch status --json

# Open docs homepage
orch docs

# Open specific topic
orch docs cli
orch docs agents
orch docs skills
orch docs sdk
orch docs api
orch docs quickstart

# Generate completions for your shell
orch completion bash
orch completion zsh
orch completion fish

# Bash — add to ~/.bashrc
eval "$(orch completion bash)"

# Zsh — add to ~/.zshrc
eval "$(orch completion zsh)"

# Fish — add to config.fish
orch completion fish | source

# Bash
orch completion bash > ~/.local/share/bash-completion/completions/orch

# Zsh
orch completion zsh > "${fpath[1]}/_orch"

# Fish
orch completion fish > ~/.config/fish/completions/orch.fish

# List all schedules
orch schedule list

# Filter by agent name
orch schedule list --agent report-generator

# Filter by type
orch schedule list --type cron

# JSON output
orch schedule list --json

# Cron schedule — daily at 9am UTC
orch schedule create acme/report-generator --cron "0 9 * * *"

# Cron schedule with timezone and input
orch schedule create acme/report-generator \
  --cron "0 9 * * 1-5" \
  --timezone "America/New_York" \
  --input '{"format": "pdf"}'

# Webhook schedule
orch schedule create acme/github-processor --webhook

# Change cron expression
orch schedule update <schedule-id> --cron "0 10 * * 1"

# Disable a schedule
orch schedule update <schedule-id> --disable

# Re-enable
orch schedule update <schedule-id> --enable

# Update timezone and input
orch schedule update <schedule-id> \
  --timezone "America/Los_Angeles" \
  --input '{"threshold": 2000}'

# Delete a schedule (prompts for confirmation)
orch schedule delete <schedule-id>

# Skip confirmation prompt
orch schedule delete <schedule-id> --yes

# Trigger with default input
orch schedule trigger <schedule-id>

# Trigger with input override
orch schedule trigger <schedule-id> --input '{"test": true}'

# View schedule details
orch schedule info <schedule-id>

# JSON output
orch schedule info <schedule-id> --json

# List recent runs
orch schedule runs <schedule-id>

# Filter by status
orch schedule runs <schedule-id> --status failed

# Limit results
orch schedule runs <schedule-id> --limit 50

# Deploy an agent as a service
orch service deploy acme/discord-bot

# Deploy with a custom service name
orch service deploy acme/discord-bot --name my-discord-bot

# Deploy with instance scaling
orch service deploy acme/discord-bot --min-instances 1 --max-instances 3

# Deploy with environment variables
orch service deploy acme/discord-bot \
  --env BOT_PREFIX="!" \
  --env LOG_LEVEL=debug

# Deploy with workspace secrets (for sensitive values)
orch service deploy acme/discord-bot \
  --secret DISCORD_TOKEN \
  --secret DATABASE_URL

# Deploy with a custom command and arguments
orch service deploy acme/worker --command python --arg worker.py --arg --verbose

# JSON output
orch service deploy acme/discord-bot --json

# List all services
orch service list

# Filter by status
orch service list --status running

# JSON output
orch service list --json

# View service details
orch service info <service-id>

# JSON output
orch service info <service-id> --json

# View recent logs
orch service logs <service-id>

# Limit number of log lines
orch service logs <service-id> --limit 200

# View logs since a specific time
orch service logs <service-id> --since 2026-02-10T00:00:00Z

# JSON output
orch service logs <service-id> --json

# Restart a service
orch service restart <service-id>

# JSON output
orch service restart <service-id> --json

# Delete a service
orch service delete <service-id>

# JSON output
orch service delete <service-id> --json

# Set one variable
orch service env set my-bot DEPLOY_ENV=production

# Set multiple variables
orch service env set my-bot LOG_LEVEL=debug BATCH_SIZE=100

# With workspace
orch service env set my-bot FOO=bar --workspace acme-team

# Remove one variable
orch service env unset my-bot DEBUG_MODE

# Remove multiple
orch service env unset my-bot DEBUG_MODE VERBOSE

orch service env list my-bot

DEPLOY_ENV=production
LOG_LEVEL=warn

# Attach one secret
orch service secret add my-bot DISCORD_BOT_TOKEN

# Attach multiple
orch service secret add my-bot DISCORD_BOT_TOKEN DATABASE_URL

orch service secret remove my-bot OLD_API_KEY

orch billing

# Capture response, see errors
result=$(orch run acme/scanner doc.pdf)

# Suppress errors, check exit code
orch run acme/scanner doc.pdf 2>/dev/null && echo "success"

# Process JSON output
orch run acme/scanner doc.pdf --json | jq '.data.total'

# Install agents in CI
orch install acme/code-reviewer --format claude-code --scope project