CLI Reference

Complete reference for RAPID CLI commands.

Installation

npm install -g @a3t/rapid

Global Options

These options work with all commands:

Option	Description
--help, -h	Show help
--version, -v	Show version
--config <path>	Path to rapid.json
--verbose	Verbose output
--quiet, -q	Minimal output

---

rapid init

Initialize RAPID in a project.

rapid init [options]

Options

Option	Default	Description
--template <name>	Auto-detected	Template to use (typescript, python, etc.)
--force	false	Overwrite existing files
--no-devcontainer	false	Skip devcontainer creation
--prebuilt	false	Use pre-built images (faster startup)
--agent <name>	claude	Default agent to configure
--mcp <servers>	context7,tavily	MCP servers to enable (comma-separated)
--no-mcp	false	Skip MCP server configuration
--no-detect	false	Skip auto-detection of project type
--no-claude-plugin	false	Skip Claude Code plugin generation

Examples

# Basic initialization (auto-detects project type)
rapid init

# Use TypeScript template
rapid init --template typescript

# Use pre-built images for faster startup
rapid init --prebuilt

# Initialize with OpenCode as default
rapid init --agent opencode

# Initialize with specific MCP servers
rapid init --mcp context7,tavily,playwright

# Skip MCP servers
rapid init --no-mcp

# Skip devcontainer (use existing)
rapid init --no-devcontainer

# Force overwrite existing config
rapid init --force

Created Files

project/
├── rapid.json              # RAPID configuration
├── .mcp.json               # MCP server config (for Claude Code)
├── opencode.json           # MCP server config (for OpenCode)
├── AGENTS.md               # Generic agent instructions
├── CLAUDE.md               # Claude-specific instructions
├── .devcontainer/          # (if not skipped)
│   └── devcontainer.json
└── .claude-plugin/         # (if using Claude)
    ├── plugin.json         # Plugin manifest
    ├── commands/           # Slash commands
    ├── skills/             # Skill definitions
    └── hooks/              # Lifecycle hooks

---

rapid start

Start the development environment.

rapid start [options]

Options

Option	Default	Description
--rebuild	false	Force rebuild container
--no-cache	false	Build without Docker cache
--reinstall-tools	false	Reinstall AI CLI tools
--skip-secrets	false	Skip secret loading
--detach, -d	false	Run in background

Examples

# Normal start
rapid start

# Force full rebuild
rapid start --rebuild --no-cache

# Start without loading secrets
rapid start --skip-secrets

# Start in background
rapid start -d

Exit Codes

Code	Meaning
0	Success
1	Configuration error
2	Docker not available
3	Build failed
4	Secret loading failed

---

rapid dev

Launch AI coding session. Automatically creates git worktrees for feature branch isolation.

rapid dev [options]

Options

Option	Default	Description
--agent <name>	From config	Agent to use
--multi	false	Launch all agents in tmux
--attach	false	Attach to existing session
--layout <type>	tiled	Tmux layout (multi mode)
--local	false	Run locally instead of in container
--no-start	false	Do not auto-start container if stopped
--no-worktree	false	Skip automatic worktree for branches

Automatic Worktrees

When running on a feature branch (not main/master), rapid dev automatically:

1. Creates a sibling worktree directory (e.g., ../project-feat-my-feature/)
2. Runs the devcontainer in that worktree
3. Keeps your main directory clean for quick branch switching

Use --no-worktree to disable this behavior.

Layout Types (—multi)

Layout	Description
tiled	Equal size panes
horizontal	Stacked horizontally
vertical	Stacked vertically
main-vertical	One large, others small

Examples

# Launch default agent
rapid dev

# Launch specific agent
rapid dev --agent aider

# Launch all agents
rapid dev --multi

# Launch with specific layout
rapid dev --multi --layout main-vertical

# Attach to running session
rapid dev --attach

---

rapid stop

Stop the development environment.

rapid stop [options]

Options

Option	Default	Description
--remove	false	Remove container after stop
--volumes	false	Also remove volumes
--force	false	Force stop (SIGKILL)

Examples

# Normal stop
rapid stop

# Stop and remove container
rapid stop --remove

# Stop, remove container and volumes
rapid stop --remove --volumes

# Force stop
rapid stop --force

---

rapid agent

Manage AI agents.

rapid agent <subcommand> [options]

Subcommands

rapid agent list

List available agents.

rapid agent list

Output:

Available agents:
  * claude (default)
    opencode
    aider

rapid agent add

Add a new agent.

rapid agent add <name> [options]

Option	Description
--cli <command>	CLI command
--instruction-file <path>	Instruction file path
--install-cmd <command>	Installation command

# Add with prompts
rapid agent add my-agent

# Add with options
rapid agent add my-agent \
  --cli my-tool \
  --instruction-file MY_AGENT.md \
  --install-cmd "npm install -g my-tool"

rapid agent remove

Remove an agent.

rapid agent remove <name>

rapid agent default

Set default agent.

rapid agent default <name>

rapid agent yolo

Toggle YOLO mode for an agent (skip permission prompts).

rapid agent yolo <name> [options]

Option	Description
--enable	Enable YOLO mode
--disable	Disable YOLO mode

YOLO mode adds --dangerously-skip-permissions to Claude Code, allowing it to execute commands without confirmation prompts.

Caution

YOLO mode should only be used in isolated development environments (containers or VMs) where the AI has limited blast radius.

Examples

# List agents
rapid agent list

# Set default to opencode
rapid agent default opencode

# Add custom agent
rapid agent add cursor --cli cursor --instruction-file CURSOR.md

# Remove agent
rapid agent remove aider

# Enable YOLO mode for Claude
rapid agent yolo claude --enable

# Disable YOLO mode
rapid agent yolo claude --disable

---

rapid secrets

Manage secrets.

rapid secrets <subcommand>

Subcommands

rapid secrets list

List configured secrets (names only).

rapid secrets list

rapid secrets verify

Verify all secrets are accessible.

rapid secrets verify

rapid secrets refresh

Reload secrets into environment.

rapid secrets refresh

Examples

# List secret names
rapid secrets list

# Verify access
rapid secrets verify

# Refresh after rotation
rapid secrets refresh

---

rapid status

Show environment status.

rapid status [options]

Options

Option	Description
--json	Output as JSON

Output

RAPID Status
────────────
Container:  running (rapid-my-project)
Uptime:     2h 34m
Agent:      claude (active)
Secrets:    loaded (3 items)
MCP:        2 servers connected

---

rapid mcp

Manage MCP (Model Context Protocol) servers.

rapid mcp <subcommand> [options]

Subcommands

rapid mcp list

List configured MCP servers.

rapid mcp list [options]

Option	Description
--json	Output as JSON
--templates	Show available server templates

# List configured servers
rapid mcp list

# Show available templates
rapid mcp list --templates

rapid mcp add

Add an MCP server.

rapid mcp add <name> [options]

Option	Description
--type <type>	Server type: remote or stdio
--url <url>	URL for remote servers
--command <cmd>	Command for stdio servers
--args <args>	Arguments (comma-separated)
--header <header>	HTTP header (name=value), repeatable

# Add from template
rapid mcp add playwright

# Add custom remote server
rapid mcp add myapi --type remote --url https://api.example.com/mcp

# Add custom stdio server
rapid mcp add mytool --type stdio --command npx --args "@example/mcp-server"

rapid mcp remove

Remove an MCP server.

rapid mcp remove <name>

rapid mcp enable

Enable a disabled MCP server.

rapid mcp enable <name>

rapid mcp disable

Disable an MCP server (without removing).

rapid mcp disable <name>

rapid mcp status

Show MCP server status.

rapid mcp status [options]

Option	Description
--json	Output as JSON

rapid mcp sync

Regenerate .mcp.json and opencode.json from rapid.json.

rapid mcp sync

Examples

# List available templates
rapid mcp list --templates

# Add Context7 and Tavily
rapid mcp add context7
rapid mcp add tavily

# Check status
rapid mcp status

# Temporarily disable a server
rapid mcp disable tavily

# Re-enable it
rapid mcp enable tavily

# Remove a server
rapid mcp remove playwright

---

rapid worktree

Manage git worktrees for isolated development.

rapid worktree <subcommand> [options]

Alias: rapid wt

Subcommands

rapid worktree list

List all git worktrees.

rapid worktree list [options]

Option	Description
--json	Output as JSON

Output:

Git Worktrees

* main
    /path/to/project
    HEAD: abc1234

  feat/my-feature
    /path/to/project-feat-my-feature
    HEAD: def5678

rapid worktree prune

Remove stale worktree references (directories that no longer exist).

rapid worktree prune [options]

Option	Description
--dry-run	Show what would be pruned without removing

rapid worktree remove

Remove a specific worktree.

rapid worktree remove <path-or-branch> [options]

Option	Description
-f, --force	Force removal even if worktree is dirty

Alias: rapid worktree rm

rapid worktree cleanup

Remove worktrees for branches that have been merged into main/master.

rapid worktree cleanup [options]

Option	Description
--dry-run	Show what would be removed

Examples

# List all worktrees
rapid worktree list

# Prune stale worktrees
rapid worktree prune

# Remove worktree for a specific branch
rapid worktree remove feat/old-feature

# Force remove a worktree
rapid worktree remove feat/wip --force

# Clean up merged branch worktrees
rapid worktree cleanup

# Preview cleanup without removing
rapid worktree cleanup --dry-run

---

rapid lima

Manage Lima VM for isolated local development on macOS.

rapid lima <subcommand> [options]

Lima provides lightweight Linux VMs using Apple Virtualization.framework for near-native performance.

Subcommands

rapid lima status

Show Lima VM status.

rapid lima status [options]

Option	Description
--json	Output as JSON

rapid lima start

Start the Lima VM.

rapid lima start [options]

Option	Default	Description
--cpus <n>	4	Number of CPUs
--memory <size>	8GiB	Memory size
--disk <size>	50GiB	Disk size

rapid lima stop

Stop the Lima VM.

rapid lima stop [options]

Option	Description
-f, --force	Force stop

rapid lima shell

Open a shell in the Lima VM.

rapid lima shell [options]

Option	Description
-c, --command	Command to run instead of interactive shell

rapid lima delete

Delete the Lima VM and all its data.

rapid lima delete [options]

Option	Description
-f, --force	Force delete without confirmation

rapid lima list

List all Lima instances.

rapid lima list [options]

Option	Description
--json	Output as JSON

Examples

# Check VM status
rapid lima status

# Start with custom resources
rapid lima start --cpus 8 --memory 16GiB

# Open a shell
rapid lima shell

# Run a command in the VM
rapid lima shell --command "node --version"

# Stop the VM
rapid lima stop

# Delete the VM (requires --force)
rapid lima delete --force

Notes

• Lima is only available on macOS
• Uses Apple Virtualization.framework (VZ) for best performance on Apple Silicon
• SSH agent is automatically forwarded for commit signing
• Install Lima with: brew install lima

---

rapid context

Show or inject project context from rapid.json configuration.

rapid context [action] [options]

Arguments

Argument	Default	Description
action	show	Action: show or inject

Options

Option	Description
--json	Output as JSON

Examples

# Show context configuration
rapid context show

# Show as JSON
rapid context show --json

# Output assembled context (for hooks)
rapid context inject

The inject action outputs the assembled context content to stdout, suitable for use in Claude Code hooks.

---

rapid bus

Manage the event bus for multi-agent communication.

rapid bus <subcommand> [options]

The event bus enables agents to communicate with each other in real-time, using Redis for message persistence and delivery.

Subcommands

rapid bus status

Show event bus status.

rapid bus status [options]

Option	Description
--json	Output as JSON

Output:

RAPID Event Bus Status
────────────────────────────────

Project:    my-project
Mode:       Redis (persistent)
URL:        redis://localhost:6379
Container:  d5263f2e5c71

Messages:   12
Agents:     2

rapid bus history

Show recent message history.

rapid bus history [options]

Option	Default	Description
--limit <n>	50	Number of messages to show
--agent <id>	all	Filter by agent ID
--type <type>	all	Filter by message type
--json		Output as JSON

rapid bus agents

List connected agents.

rapid bus agents [options]

Option	Description
--json	Output as JSON

Examples

# Check event bus status
rapid bus status

# View recent messages
rapid bus history

# View last 10 messages
rapid bus history --limit 10

# Filter by agent
rapid bus history --agent claude-abc123

# List connected agents
rapid bus agents

Notes

• The event bus starts automatically when rapid dev runs (if enabled in config)
• Uses Redis in Docker for message persistence
• Messages are retained for the session lifetime
• Agents can send/receive messages via the RAPID MCP server tools

---

rapid auth

Show authentication status for external AI providers.

rapid auth [options]

Options

Option	Description
--json	Output as JSON

Examples

# Check authentication status
rapid auth

# Output as JSON
rapid auth --json

Output shows detected credentials for Claude, Codex, Gemini, Aider, and environment variables.

---

rapid update

Check for and install RAPID updates.

rapid update [options]

Options

Option	Description
--check	Only check for updates
-f, --force	Force update even if current

Examples

# Update RAPID
rapid update

# Check for updates without installing
rapid update --check

# Force update
rapid update --force

---

Environment Variables

RAPID respects these environment variables:

Variable	Description
RAPID_CONFIG	Path to rapid.json
RAPID_LOG_LEVEL	Log verbosity (debug, info, warn, error)
RAPID_NO_COLOR	Disable colored output
DOCKER_HOST	Docker daemon socket
MCP_CONFIG_FILE	Path to MCP configuration file

---

Configuration File

See rapid.json Specification for complete configuration reference.

See MCP Server Configuration for MCP server setup.