mirror of
https://github.com/RooVetGit/Roo-Code.git
synced 2026-09-07 08:26:51 +00:00
7dc83a522e
* Allow selecting a specific shell Add --terminal-shell CLI flag to specify which shell ExecaTerminalProcess uses for inline command execution. The shell path is validated at the CLI layer and passed through the standard settings mechanism (BaseTerminal static getter/setter), matching how all other CLI terminal settings flow through the system. * test(cli): make shell path access test cross-platform
313 lines
12 KiB
Markdown
313 lines
12 KiB
Markdown
# @roo-code/cli
|
|
|
|
Command Line Interface for Roo Code - Run the Roo Code agent from the terminal without VSCode.
|
|
|
|
## Overview
|
|
|
|
This CLI uses the `@roo-code/vscode-shim` package to provide a VSCode API compatibility layer, allowing the main Roo Code extension to run in a Node.js environment.
|
|
|
|
## Installation
|
|
|
|
### Quick Install (Recommended)
|
|
|
|
Install the Roo Code CLI with a single command:
|
|
|
|
```bash
|
|
curl -fsSL https://raw.githubusercontent.com/RooCodeInc/Roo-Code/main/apps/cli/install.sh | sh
|
|
```
|
|
|
|
**Requirements:**
|
|
|
|
- Node.js 20 or higher
|
|
- macOS Apple Silicon (M1/M2/M3/M4) or Linux x64
|
|
|
|
**Custom installation directory:**
|
|
|
|
```bash
|
|
ROO_INSTALL_DIR=/opt/roo-code ROO_BIN_DIR=/usr/local/bin curl -fsSL ... | sh
|
|
```
|
|
|
|
**Install a specific version:**
|
|
|
|
```bash
|
|
ROO_VERSION=0.1.0 curl -fsSL https://raw.githubusercontent.com/RooCodeInc/Roo-Code/main/apps/cli/install.sh | sh
|
|
```
|
|
|
|
### Updating
|
|
|
|
Re-run the install script to update to the latest version:
|
|
|
|
```bash
|
|
curl -fsSL https://raw.githubusercontent.com/RooCodeInc/Roo-Code/main/apps/cli/install.sh | sh
|
|
```
|
|
|
|
Or run:
|
|
|
|
```bash
|
|
roo upgrade
|
|
```
|
|
|
|
### Uninstalling
|
|
|
|
```bash
|
|
rm -rf ~/.roo/cli ~/.local/bin/roo
|
|
```
|
|
|
|
### Development Installation
|
|
|
|
For contributing or development:
|
|
|
|
```bash
|
|
# From the monorepo root.
|
|
pnpm install
|
|
|
|
# Build the main extension first.
|
|
pnpm --filter roo-cline bundle
|
|
|
|
# Build the CLI.
|
|
pnpm --filter @roo-code/cli build
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Interactive Mode (Default)
|
|
|
|
By default, the CLI auto-approves actions and runs in interactive TUI mode:
|
|
|
|
```bash
|
|
export OPENROUTER_API_KEY=sk-or-v1-...
|
|
|
|
roo "What is this project?" -w ~/Documents/my-project
|
|
```
|
|
|
|
You can also run without a prompt and enter it interactively in TUI mode:
|
|
|
|
```bash
|
|
roo -w ~/Documents/my-project
|
|
```
|
|
|
|
In interactive mode:
|
|
|
|
- Tool executions are auto-approved
|
|
- Commands are auto-approved
|
|
- Followup questions show suggestions with a 60-second timeout, then auto-select the first suggestion
|
|
- Browser and MCP actions are auto-approved
|
|
|
|
### Approval-Required Mode (`--require-approval`)
|
|
|
|
If you want manual approval prompts, enable approval-required mode:
|
|
|
|
```bash
|
|
roo "Refactor the utils.ts file" --require-approval -w ~/Documents/my-project
|
|
```
|
|
|
|
In approval-required mode:
|
|
|
|
- Tool, command, browser, and MCP actions prompt for yes/no approval
|
|
- Followup questions wait for manual input (no auto-timeout)
|
|
|
|
### Print Mode (`--print`)
|
|
|
|
Use `--print` for non-interactive execution and machine-readable output:
|
|
|
|
```bash
|
|
# Prompt is required
|
|
roo --print "Summarize this repository"
|
|
```
|
|
|
|
### Stdin Stream Mode (`--stdin-prompt-stream`)
|
|
|
|
For programmatic control (one process, multiple prompts), use `--stdin-prompt-stream` with `--print`.
|
|
Send one prompt per line via stdin:
|
|
|
|
```bash
|
|
printf '1+1=?\n10!=?\n' | roo --print --stdin-prompt-stream --output-format stream-json
|
|
```
|
|
|
|
### Roo Code Cloud Authentication
|
|
|
|
To use Roo Code Cloud features (like the provider proxy), you need to authenticate:
|
|
|
|
```bash
|
|
# Log in to Roo Code Cloud (opens browser)
|
|
roo auth login
|
|
|
|
# Check authentication status
|
|
roo auth status
|
|
|
|
# Log out
|
|
roo auth logout
|
|
```
|
|
|
|
The `auth login` command:
|
|
|
|
1. Opens your browser to authenticate with Roo Code Cloud
|
|
2. Receives a secure token via localhost callback
|
|
3. Stores the token in `~/.config/roo/credentials.json`
|
|
|
|
Tokens are valid for 90 days. The CLI will prompt you to re-authenticate when your token expires.
|
|
|
|
**Authentication Flow:**
|
|
|
|
```
|
|
┌──────┐ ┌─────────┐ ┌───────────────┐
|
|
│ CLI │ │ Browser │ │ Roo Code Cloud│
|
|
└──┬───┘ └────┬────┘ └───────┬───────┘
|
|
│ │ │
|
|
│ Open auth URL │ │
|
|
│─────────────────>│ │
|
|
│ │ │
|
|
│ │ Authenticate │
|
|
│ │─────────────────────>│
|
|
│ │ │
|
|
│ │<─────────────────────│
|
|
│ │ Token via callback │
|
|
│<─────────────────│ │
|
|
│ │ │
|
|
│ Store token │ │
|
|
│ │ │
|
|
```
|
|
|
|
## Options
|
|
|
|
| Option | Description | Default |
|
|
| --------------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------- |
|
|
| `[prompt]` | Your prompt (positional argument, optional) | None |
|
|
| `--prompt-file <path>` | Read prompt from a file instead of command line argument | None |
|
|
| `-w, --workspace <path>` | Workspace path to operate in | Current directory |
|
|
| `-p, --print` | Print response and exit (non-interactive mode) | `false` |
|
|
| `--stdin-prompt-stream` | Read prompts from stdin (one prompt per line, requires `--print`) | `false` |
|
|
| `-e, --extension <path>` | Path to the extension bundle directory | Auto-detected |
|
|
| `-d, --debug` | Enable debug output (includes detailed debug information, prompts, paths, etc) | `false` |
|
|
| `-a, --require-approval` | Require manual approval before actions execute | `false` |
|
|
| `-k, --api-key <key>` | API key for the LLM provider | From env var |
|
|
| `--provider <provider>` | API provider (roo, anthropic, openai, openrouter, etc.) | `openrouter` (or `roo` if authenticated) |
|
|
| `-m, --model <model>` | Model to use | `anthropic/claude-opus-4.6` |
|
|
| `--mode <mode>` | Mode to start in (code, architect, ask, debug, etc.) | `code` |
|
|
| `--terminal-shell <path>` | Absolute shell path for inline terminal command execution | Auto-detected shell |
|
|
| `-r, --reasoning-effort <effort>` | Reasoning effort level (unspecified, disabled, none, minimal, low, medium, high, xhigh) | `medium` |
|
|
| `--consecutive-mistake-limit <n>` | Consecutive error/repetition limit before guidance prompt (`0` disables the limit) | `10` |
|
|
| `--ephemeral` | Run without persisting state (uses temporary storage) | `false` |
|
|
| `--oneshot` | Exit upon task completion | `false` |
|
|
| `--output-format <format>` | Output format with `--print`: `text`, `json`, or `stream-json` | `text` |
|
|
|
|
## Auth Commands
|
|
|
|
| Command | Description |
|
|
| ----------------- | ---------------------------------- |
|
|
| `roo auth login` | Authenticate with Roo Code Cloud |
|
|
| `roo auth logout` | Clear stored authentication token |
|
|
| `roo auth status` | Show current authentication status |
|
|
|
|
## Environment Variables
|
|
|
|
The CLI will look for API keys in environment variables if not provided via `--api-key`:
|
|
|
|
| Provider | Environment Variable |
|
|
| ----------------- | --------------------------- |
|
|
| roo | `ROO_API_KEY` |
|
|
| anthropic | `ANTHROPIC_API_KEY` |
|
|
| openai-native | `OPENAI_API_KEY` |
|
|
| openrouter | `OPENROUTER_API_KEY` |
|
|
| gemini | `GOOGLE_API_KEY` |
|
|
| vercel-ai-gateway | `VERCEL_AI_GATEWAY_API_KEY` |
|
|
|
|
**Authentication Environment Variables:**
|
|
|
|
| Variable | Description |
|
|
| ----------------- | -------------------------------------------------------------------- |
|
|
| `ROO_WEB_APP_URL` | Override the Roo Code Cloud URL (default: `https://app.roocode.com`) |
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────┐
|
|
│ CLI Entry │
|
|
│ (index.ts) │
|
|
└────────┬────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ ExtensionHost │
|
|
│ (extension- │
|
|
│ host.ts) │
|
|
└────────┬────────┘
|
|
│
|
|
┌────┴────┐
|
|
│ │
|
|
▼ ▼
|
|
┌───────┐ ┌──────────┐
|
|
│vscode │ │Extension │
|
|
│-shim │ │ Bundle │
|
|
└───────┘ └──────────┘
|
|
```
|
|
|
|
## How It Works
|
|
|
|
1. **CLI Entry Point** (`index.ts`): Parses command line arguments and initializes the ExtensionHost
|
|
|
|
2. **ExtensionHost** (`extension-host.ts`):
|
|
|
|
- Creates a VSCode API mock using `@roo-code/vscode-shim`
|
|
- Intercepts `require('vscode')` to return the mock
|
|
- Loads and activates the extension bundle
|
|
- Manages bidirectional message flow
|
|
|
|
3. **Message Flow**:
|
|
- CLI → Extension: `emit("webviewMessage", {...})`
|
|
- Extension → CLI: `emit("extensionWebviewMessage", {...})`
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Run directly from source (no build required)
|
|
pnpm dev --provider roo --api-key $ROO_API_KEY --print "Hello"
|
|
|
|
# Run tests
|
|
pnpm test
|
|
|
|
# Type checking
|
|
pnpm check-types
|
|
|
|
# Linting
|
|
pnpm lint
|
|
```
|
|
|
|
By default the `start` script points `ROO_CODE_PROVIDER_URL` at `http://localhost:8080/proxy` for local development. To point at the production API instead, override the environment variable:
|
|
|
|
```bash
|
|
ROO_CODE_PROVIDER_URL=https://api.roocode.com/proxy pnpm dev --provider roo --api-key $ROO_API_KEY --print "Hello"
|
|
```
|
|
|
|
## Releasing
|
|
|
|
Official releases are created via the GitHub Actions workflow at `.github/workflows/cli-release.yml`.
|
|
|
|
To trigger a release:
|
|
|
|
1. Go to **Actions** → **CLI Release**
|
|
2. Click **Run workflow**
|
|
3. Optionally specify a version (defaults to `package.json` version)
|
|
4. Click **Run workflow**
|
|
|
|
The workflow will:
|
|
|
|
1. Build the CLI on all platforms (macOS Apple Silicon, Linux x64)
|
|
2. Create platform-specific tarballs with bundled ripgrep
|
|
3. Verify each tarball
|
|
4. Create a GitHub release with all tarballs attached
|
|
|
|
### Local Builds
|
|
|
|
For local development and testing, use the build script:
|
|
|
|
```bash
|
|
# Build tarball for your current platform
|
|
./apps/cli/scripts/build.sh
|
|
|
|
# Build and install locally
|
|
./apps/cli/scripts/build.sh --install
|
|
|
|
# Fast build (skip verification)
|
|
./apps/cli/scripts/build.sh --skip-verify
|
|
```
|