# Droid CLI Reference
Complete reference for the Droid CLI, including commands and flags
## Installation
**macOS/Linux:** `curl -fsSL https://app.factory.ai/cli | sh`
**Homebrew:** `brew install --cask droid`
**Windows:** `irm https://app.factory.ai/cli/windows | iex`
**npm:** `npm install -g droid`
The Droid CLI operates in two modes:
- **Interactive (`droid`)** - Chat-first REPL with slash commands
- **Non-interactive (`droid exec`)** - Single-shot execution for automation and scripting
### Installing a specific version
Pin a version when upgrades must be reviewed and applied intentionally, such as in CI runners,
provisioned development environments, or other reproducible systems.
#### npm
Specify an exact package version:
```bash
npm install -g droid@0.174.0
```
The binaries published through npm have auto-updates disabled at build time, so the installed
version remains pinned. To upgrade, install the new version explicitly with npm.
#### Built-in updater
After installing Droid through the standalone installer, select a version with:
```bash
droid update --version 0.174.0
```
This command can also roll back to an older version. Use `droid update --check` to check for an
available update without installing it.
Standalone installations enable automatic updates by default. After selecting a version, follow
the [auto-update guidance](#auto-updates) to keep it pinned.
#### Direct binary download
Release binaries and their SHA256 checksums use the following paths:
```text
https://downloads.factory.ai/factory-cli/releases////
https://downloads.factory.ai/factory-cli/releases////.sha256
```
- ``: `linux`, `darwin`, or `windows`
- ``: `x64`, `arm64`, or `x64-baseline`
- ``: `droid` on Linux and macOS, or `droid.exe` on Windows
For example, download and verify the Linux x64 binary:
```bash
VERSION=0.174.0
BASE_URL="https://downloads.factory.ai/factory-cli/releases/${VERSION}/linux/x64"
curl -fsSLO "${BASE_URL}/droid"
curl -fsSLO "${BASE_URL}/droid.sha256"
echo "$(awk '{print $1}' droid.sha256) droid" | sha256sum --check
chmod +x droid
```
Move the verified binary to a directory on `PATH`. The download URL layout is an implementation
detail, so always pin a version and verify its checksum.
## Droid CLI commands
| Command | Description | Example |
| :----------------------------------- | :--------------------------------------------------------------------- | :--------------------------------------------- |
| `droid` | Start interactive REPL | `droid` |
| `droid "query"` | Start REPL with initial prompt | `droid "explain this project"` |
| `droid --resume [sessionId]` | Resume a session (defaults to last modified). Alias: `-r` | `droid --resume` |
| `droid --fork ` | Fork and resume a session in a new copy | `droid --fork session-abc123` |
| `droid exec "query"` | Execute task without interactive mode | `droid exec "summarize src/auth"` |
| `droid exec -f prompt.md` | Load prompt from file | `droid exec -f .factory/prompts/review.md` |
| `cat file \| droid exec` | Process piped content | `git diff \| droid exec "draft release notes"` |
| `droid exec -s "query"` | Resume existing session in exec mode | `droid exec -s session-123 "continue"` |
| `droid exec --list-tools` | List available tools, then exit | `droid exec --list-tools` |
| `droid search "query"` | Search across local sessions (messages, documents, tool results). Alias: `droid find` | `droid search "auth bug"` |
| `droid mcp add ` | Add an MCP server | `droid mcp add api https://api.example.com/mcp --type http` |
| `droid mcp remove ` | Remove an MCP server | `droid mcp remove linear` |
| `droid plugin install ` | Install a plugin. Alias: `droid plugin i` | `droid plugin install droid-control@factory-plugins` |
| `droid plugin uninstall ` | Uninstall a plugin. Alias: `droid plugin remove` | `droid plugin uninstall droid-control@factory-plugins` |
| `droid plugin update ` | Update a plugin to the latest version | `droid plugin update droid-control@factory-plugins` |
| `droid plugin list` | List installed plugins | `droid plugin list` |
| `droid plugin marketplace` | Manage plugin marketplaces | `droid plugin marketplace` |
| `droid computer register [name]` | Register this machine as a Bring-Your-Own-Machine (BYOM) computer | `droid computer register laptop` |
| `droid computer remove` | Remove this machine's BYOM registration | `droid computer remove` |
| `droid computer list` | List registered BYOM computers | `droid computer list` |
| `droid computer ssh ` | SSH into a registered BYOM computer | `droid computer ssh laptop` |
| `droid computer port-forward ` | Forward local ports to a computer over the relay | `droid computer port-forward laptop 8080:80` |
| `droid daemon` | Run the Factory daemon server | `droid daemon` |
| `droid update` | Manually update the CLI to latest version | `droid update` |
## Droid CLI flags
Customize droid's behavior with command-line flags:
| Flag | Description | Example |
| :-------------------------------- | :----------------------------------------------------------------- | :----------------------------------------------------------- |
| `-f, --file ` | Read prompt from a file | `droid exec -f plan.md` |
| `-m, --model ` | Select a specific [model ID](/models) | `droid exec -m claude-opus-4-7` |
| `-s, --session-id ` | Continue an existing session | `droid exec -s session-abc123` |
| `--auto ` | Set [autonomy level](#autonomy-levels) (`low`, `medium`, `high`) | `droid exec --auto medium "run tests"` |
| `--restrict-tools ` | Restrict the run to only the specified tools (comma or space separated) | `droid exec --auto low --restrict-tools ApplyPatch,Execute` |
| `--additional-tools ` | Force-enable additional tools beyond the defaults (comma or space separated) | `droid exec --additional-tools ApplyPatch` |
| `--disabled-tools ` | Disable specific tools for this run | `droid exec --disabled-tools execute-cli` |
| `--disable-builtin-skills` | Disable Factory-provided builtin skills in interactive or exec sessions while preserving other skill sources | `droid --disable-builtin-skills` |
| `--list-tools` | Print available tools and exit | `droid exec --list-tools` |
| `-o, --output-format ` | Output format (`text`, `json`, `stream-json`, `stream-jsonrpc`) | `droid exec -o json "document API"` |
| `--input-format ` | Input format for multi-turn sessions. Use `stream-jsonrpc`; the older `stream-json` mode is deprecated. Must match `--output-format`. | `droid exec --input-format stream-jsonrpc -o stream-jsonrpc` |
| `-r, --resume [sessionId]` | Resume a previous session. In interactive mode, `-r` is `--resume`; in `droid exec`, `-r` is `--reasoning-effort`. | `droid -r` |
| `-r, --reasoning-effort ` | Override reasoning effort; valid levels are model-dependent (see [/models](/models)). In `droid exec`, `-r` maps to this flag. | `droid exec -r high "debug flaky test"` |
| `--spec-model ` | Use a different [model ID](/models) for specification planning | `droid exec --spec-model claude-opus-4-7` |
| `--spec-reasoning-effort ` | Override reasoning effort for spec mode | `droid exec --use-spec --spec-reasoning-effort high` |
| `--use-spec` | Start in specification mode (plan before executing) | `droid exec --use-spec "add user profiles"` |
| `--skip-permissions-unsafe` | Skip all permission prompts (use with extreme caution) | `droid exec --skip-permissions-unsafe` |
| `--cwd ` | Execute from a specific working directory | `droid exec --cwd ../service "run tests"` |
| `-w, --worktree [name]` | Run the session in an isolated [git worktree](#git-worktrees) | `droid --worktree fix-bug` |
| `--tag ` | Session tag (name or JSON, repeatable) | `droid exec --tag code-review` |
| `--log-group-id ` | Log group ID for filtering logs | `droid exec --log-group-id grp-123` |
| `--fork ` | Fork and resume an existing session into a new copy | `droid exec --fork session-abc123` |
| `--mission` | Run `droid exec` in [Mission Mode](/missions/overview) (multi-agent orchestration). Requires `--auto high` or `--skip-permissions-unsafe`. | `droid exec --mission --auto high -f mission.md` |
| `--worker-model ` | Model used for mission worker agents | `droid exec --mission --worker-model claude-sonnet-4-6` |
| `--worker-reasoning-effort ` | Reasoning effort for mission worker agents (model-dependent; see [/models](/models)) | `droid exec --mission --worker-reasoning-effort medium` |
| `--validator-model ` | Model used for mission validator agents | `droid exec --mission --validator-model claude-opus-4-7` |
| `--validator-reasoning-effort ` | Reasoning effort for mission validator agents | `droid exec --mission --validator-reasoning-effort high` |
| `--append-system-prompt ` | Append custom text to the end of the system prompt | `droid --append-system-prompt "Always run tests."` |
| `--append-system-prompt-file ` | Append the contents of a file to the end of the system prompt | `droid --append-system-prompt-file .factory/system.md` |
| `-v, --version` | Display CLI version | `droid -v` |
| `-h, --help` | Show help information | `droid --help` |
Use `--output-format json` for scripting and automation, so you can parse droid's responses
programmatically.
## Autonomy levels
`droid exec` uses tiered autonomy to control what operations the agent can perform. Only raise access when the environment is safe.
| Level | Intended for | Notable allowances |
| :-------------------------- | :----------------------- | :------------------------------------------------------------ |
| _(default)_ | Read-only reconnaissance | File reads, git diffs, environment inspection |
| `--auto low` | Safe edits | Create/edit files, run formatters, non-destructive commands |
| `--auto medium` | Local development | Install dependencies, build/test, local git commits |
| `--auto high` | CI/CD & orchestration | Git push, deploy scripts, long-running operations |
| `--skip-permissions-unsafe` | Isolated sandboxes only | Removes all guardrails (use only in disposable containers) |
**Examples:**
```bash
# Default (read-only)
droid exec "Analyze the auth system and create a plan"
# Low autonomy - safe edits
droid exec --auto low "Add JSDoc comments to all functions"
# Medium autonomy - development work
droid exec --auto medium "Install deps, run tests, fix issues"
# High autonomy - deployment
droid exec --auto high "Run tests, commit, and push changes"
```
`--skip-permissions-unsafe` removes all safety checks. Use **only** in isolated environments like Docker
containers.
## Model IDs
Use any [available model ID](/models) with `-m, --model` or `--spec-model`. For custom models, see [Custom Models (BYOK)](/model-independence/byok).
## Interactive mode features
### Keyboard shortcuts
The interactive REPL supports a rich set of keyboard shortcuts for navigation, overlays, and input control:
| Shortcut | Action |
| :------- | :----- |
| | Cancel the current operation / interrupt the agent. Press twice quickly to exit |
| | Suspend the process (Unix only). Resume with `fg` |
| | Toggle the detailed transcript view (full message details) |
| | Toggle the Mission Control overlay (orchestrator sessions only) |
| | Cycle through available models (when typing in chat input) |
| | Cycle through autonomy levels (when typing in chat input) |
| | Toggle the `/btw` scroll view (side-question history) |
| | Toggle the changelog display (dismiss / restore) |
| | Toggle the approval details view |
| | Paste an image from the clipboard as an attachment |
| Tab | Cycle through the model's available reasoning-effort levels |
| | Toggle Normal Mode and Spec Mode |
| @ | File path autocomplete: typing `@` triggers fuzzy file search |
| Up / Down | Navigate input history (cycle through previously submitted messages) |
| Double Escape | Second press clears the input draft; a third Escape opens the rewind menu |
| ? | Toggle the help popup (when the input is empty) |
| | Toggle the help popup (works even when the input has content) |
| | Move the cursor to the start of the line |
| | Delete the word before the cursor |
| | Delete from the cursor to the end of the line |
| | Delete from the cursor to the start of the line |
| | Clear all attached images, or forward-delete the next character if none attached |
| | Rename the highlighted session (in the `/sessions` list view) |
| | Archive the highlighted session (in the `/sessions` list view) |
| | Scroll the transcript up (navigate any turn) |
| | Scroll the transcript down (navigate any turn) |
| | Scroll the transcript up to the previous user turn |
| | Scroll the transcript down to the next user turn |
| Escape | Close the active overlay or menu |
| | Insert a newline in the chat input (multiline editing) |
| ! | Toggle [bash mode](#bash-mode) (when the input is empty) |
Run `/terminal-setup` once to configure your terminal so reliably produces a newline
in the chat input.
### Bash mode
Press ! when the input is empty to toggle bash mode. In bash mode, commands execute directly in your shell without AI interpretation, useful for quick operations like checking `git status` or running `npm test`.
{/* sweep-allow: term-bullets */}
- **Toggle on:** Press ! (when input is empty)
- **Execute commands:** Type any shell command and press Enter
- **Toggle off:** Press Esc to return to normal AI chat mode
The prompt changes from `>` to `$` when bash mode is active.
### Mermaid diagram rendering
Droid automatically renders Mermaid diagram code blocks as ASCII art directly in the terminal, with no external viewer or browser required. When a response contains a fenced ```` ```mermaid ```` block of a supported diagram type, the diagram is drawn inline in the transcript.
**Supported diagram types:**
- `flowchart` (and `graph`)
- `sequenceDiagram`
- `stateDiagram`
- `classDiagram`
- `erDiagram`
Unsupported diagram types (for example `gantt`, `pie`, `mindmap`, `timeline`, `journey`, `gitGraph`) fall back to displaying the raw Mermaid source and a link to view the diagram externally.
### Slash commands
Available when running `droid` in interactive mode. Type the command at the prompt:
| Command | Description |
| :---------------------------- | :------------------------------------------------------------- |
| `/account` | Open Factory account settings in browser |
| `/billing` | View and manage billing settings |
| `/btw ` | Ask a side question without polluting the main transcript |
| `/bug [title]` | Create a bug report with session data and logs |
| `/clear` | Clear conversation context, keep current model & autonomy |
| `/commands` | Manage custom slash commands |
| `/compress [prompt]` | Compress session and move to new one with summary |
| `/context` | Show context window usage breakdown with progress bar |
| `/copy` | Copy prompts, responses, turn ranges, or session ID |
| `/cost` | Show usage statistics |
| `/create-skill` | Create a reusable skill from current session |
| `/cwd ` | Change session working directory |
| `/diagnostics` | Show settings configuration errors |
| `/droids` | Manage custom droids |
| `/missions` | Enter Mission Mode |
| `/fast` | Enable fast mode for current model (`/fast off` to disable) |
| `/favorite` | Mark current session as a favorite |
| `/fork` | Duplicate current session with all messages into a new session |
| `/help` | Show available slash commands |
| `/hooks` | Manage lifecycle hooks |
| `/ide` | Configure IDE integrations |
| `/install-code-review` | Set up automated code review |
| `/install-slack-app` | Install/connect Slack integration |
| `/language ` | Switch TUI display language |
| `/limits` | Manage token usage limits and overage preferences |
| `/login` | Sign in to Factory |
| `/logout` | Sign out of Factory |
| `/mcp` | Manage Model Context Protocol servers |
| `/model` | Switch AI model mid-session |
| `/new` | Start a fresh session, reset model & autonomy to defaults |
| `/plugins` | Manage plugins and marketplaces |
| `/quit` | Exit droid (alias: `exit`, or press ) |
| `/readiness-fix` | Fix failing agent readiness signals from latest report |
| `/readiness-report` | Generate readiness report |
| `/rename` | Rename current session |
| `/review` | Start AI-powered code review workflow |
| `/rewind-conversation` | Undo recent changes in the session |
| `/sessions` | List and select previous sessions |
| `/settings` | Configure application settings |
| `/setup-incident-response` | Set up Slack auto-run for incident-response channel |
| `/share` | Share session with organization |
| `/skills` | Manage and invoke skills |
| `/stats [period]` | Show usage statistics (supports relative periods, date ranges) |
| `/status` | Show current droid status and configuration |
| `/statusline` | Configure custom status line |
| `/terminal-setup` | Configure terminal keybindings for |
| `/themes` | Choose a color theme |
For detailed information on slash commands, see the [interactive mode documentation](/droid-cli/quickstart#useful-slash-commands).
### Git worktrees
Use `-w, --worktree [name]` to run a session inside a native [git worktree](https://git-scm.com/docs/git-worktree) so you can work on multiple branches of the same repository in parallel without file conflicts. This flag is available on both `droid` (interactive) and `droid exec`.
Each worktree is created as a sibling directory next to your repo (`../-wt-/`) with its own checkout and dedicated branch.
**Branch naming:**
- **`--worktree`** (no value): Creates/reuses a worktree on a branch named `-wt`.
- **`--worktree `**: Uses `` as the branch. If the branch already exists, it is checked out in the worktree; otherwise it is created from `HEAD`.
- If the target branch is already checked out in another worktree, the command fails with a clear error.
**Examples:**
```bash
# Interactive: derive branch from current branch (creates -wt)
droid --worktree
# Interactive: explicit branch name
droid -w fix-auth-bug "start debugging the login flow"
# Headless: isolate an automated task on its own branch
droid exec --worktree refactor-tests --auto medium "migrate jest suites to vitest"
# Run two parallel sessions on the same repo, each on its own branch
droid --worktree feature-a &
droid --worktree feature-b &
```
**Session lifecycle:**
- **Interactive mode**: The worktree persists after the session ends so you can resume work, inspect changes, or push the branch.
- **`droid exec` mode**: On exit, a clean worktree (no uncommitted changes) is removed automatically; a dirty worktree is preserved and its path is printed so you can review the work.
- The underlying git branch is **never deleted** by Droid; only the worktree directory is removed during cleanup.
When `--worktree` is active, Droid operates entirely inside the worktree directory. Run follow-up
commands (tests, builds, installs) from that directory rather than the original repo root. Fresh
worktrees may not have dependencies installed yet (for example `node_modules`); set them up if
builds or tests fail with missing-module errors.
### Subcommand flags
In addition to the global flags above, several `droid` subcommands accept their own flags.
#### `droid update` flags
| Flag | Description | Example |
| :------------------------ | :------------------------------------------------- | :--------------------------- |
| `-c, --check` | Check for updates without installing | `droid update --check` |
| `-v, --version ` | Update to or roll back to a specific version | `droid update -v 0.174.0` |
#### `droid search` flags
| Flag | Description | Example |
| :-------------------- | :----------------------------------------------------------------------- | :--------------------------------------- |
| `--kind ` | Filter by entry kind: `message_text`, `document`, `tool_use`, `tool_result`, or `all` | `droid search "auth" --kind document` |
| `--limit-sessions ` | Maximum number of sessions to return | `droid search "auth" --limit-sessions 5` |
| `--limit-hits ` | Maximum number of matches per kind per session | `droid search "auth" --limit-hits 3` |
| `--context-chars ` | Number of characters of context shown around each match | `droid search "auth" --context-chars 200`|
| `--json` | Emit results as JSON | `droid search "auth" --json` |
| `--reindex` | Drop the search cache and rebuild the local index | `droid search "auth" --reindex` |
#### `droid mcp add` flags
| Flag | Description | Example |
| :------------------------- | :----------------------------------------------------------------------- | :--------------------------------------------------------------- |
| `--type ` | Server transport: `http` (streamable HTTP), `sse` (legacy HTTP+SSE), or `stdio` (local) | `droid mcp add api https://api.example.com/mcp --type http` |
| `--env ` | Set an environment variable for a stdio server (repeatable) | `droid mcp add gh "gh-mcp" --type stdio --env GH_TOKEN=$GH_TOKEN`|
| `--header ` | Add an HTTP header for a remote server (repeatable) | `droid mcp add api https://api.example.com/mcp --type http --header "Authorization: Bearer $TOKEN"` |
#### `droid plugin` flags
| Flag | Description | Example |
| :-------------------- | :----------------------------------------------------------------------- | :------------------------------------------------------- |
| `-s, --scope ` | Installation scope: `user` (default) or `project` | `droid plugin install droid-control@factory-plugins --scope project` |
#### `droid computer register` flags
| Flag | Description | Example |
| :----------- | :------------------------------------------------------- | :----------------------------------- |
| `-y, --yes` | Skip interactive prompts and accept registration defaults | `droid computer register laptop -y` |
### MCP command reference
The `/mcp` slash command opens an interactive manager UI for browsing and managing MCP servers.
**Quick start:** Type `/mcp` and select **"Add from Registry"** to browse 40+ pre-configured servers (Linear, Sentry, Notion, Stripe, Vercel, and more). Select a server, authenticate if required, and you're ready to go.
**CLI commands** for scripting and automation:
```bash
droid mcp add --type http # Add HTTP (streamable) server
droid mcp add --type sse # Add legacy HTTP+SSE server
droid mcp add "" # Add stdio server
droid mcp remove # Remove a server
```
See [MCP Configuration](/harness/mcp) for the full registry list, CLI options (`--env`, `--header`), configuration files, and how user vs project config layering works.
## Authentication
1. Generate an API key in the Factory API keys settings
2. Set the environment variable:
```bash macOS/Linux
export FACTORY_API_KEY=fk-...
```
```powershell Windows (PowerShell)
$env:FACTORY_API_KEY="fk-..."
```
```cmd Windows (CMD)
set FACTORY_API_KEY=fk-...
```
**Persist the variable** in your shell profile (`~/.bashrc`, `~/.zshrc`, or PowerShell `$PROFILE`) for long-term use.
Never commit API keys to source control. Use environment variables or secure secret management.
## Auto-updates
Standalone Droid installations check for and install CLI updates automatically. Run `droid update`
to trigger an update on demand.
To keep a standalone installation pinned, disable its in-process updater:
```bash
export FACTORY_DROID_AUTO_UPDATE_ENABLED=false
```
With this variable set, automatic updates are disabled and `droid update` does not install another
version. Set it in the environment that launches every Droid process, including `droid daemon`.
The npm distribution has auto-updates disabled at build time and does not require this variable.
Running `droid update` from an npm installation reports that auto-update is unavailable. Setting
`FACTORY_DROID_AUTO_UPDATE_ENABLED=true` explicitly overrides the npm build default.
Enterprise administrators can disable CLI auto-updates for all organization members with the
`disableAutoUpdate` organization setting. See the [release notes](/changelog/release-notes) and
[organization controls](/enterprise/hierarchical-settings-and-org-control).
Pin the CLI and disable auto-updates in reproducible environments. For local developer
installations, leave auto-updates enabled to receive fixes and security updates.
## Exit codes
| Code | Meaning |
| :--- | :---------------------------- |
| `0` | Success |
| `1` | General runtime error |
| `2` | Invalid CLI arguments/options |
## Common workflows
### Code review
Interactive review inside a Droid session:
```text
> /review
```
Non-interactive review through `droid exec`:
```bash
# Analysis only
droid exec "Review this PR for security issues"
# With modifications
droid exec --auto low "Review code and add missing type hints"
```
See the [Local Code Review documentation](/software-factory/code-review) for detailed guidance on review types, workflows, and best practices.
### Testing and debugging
```bash
# Investigation
droid exec "Analyze failing tests and explain root cause"
# Fix and verify
droid exec --auto medium "Fix failing tests and run test suite"
```
### Refactoring
```bash
# Planning
droid exec "Create refactoring plan for auth module"
# Execution
droid exec --auto low --use-spec "Refactor auth module"
```
### Parallel sessions on one repo
```bash
# Work on two branches of the same repo at the same time, each in its own worktree
droid --worktree feature-a &
droid --worktree feature-b &
# Fan out headless tasks across branches without clobbering each other's files
droid exec -w migration-step-1 --auto medium "apply codemod A" &
droid exec -w migration-step-2 --auto medium "apply codemod B" &
wait
```
See [Git worktrees](#git-worktrees) for details.
### CI/CD integration
```yaml
# GitHub Actions example
- name: Run Droid Analysis
env:
FACTORY_API_KEY: ${{ secrets.FACTORY_API_KEY }}
run: |
droid exec --auto medium -f .github/prompts/deploy.md
```
Model IDs and reasoning options.
Create your own shortcuts.
Build specialized agents.
External tool integration.