> ## Documentation Index > Fetch the complete documentation index at: https://factory-changelog-jun24-v0158.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Droid CLI Reference > Complete reference for the Droid CLI, including commands and flags ## Installation ```bash macOS/Linux theme={null} curl -fsSL https://app.factory.ai/cli | sh ``` ```powershell Windows theme={null} irm https://app.factory.ai/cli/windows | iex ``` 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 ## 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 factory/code-review` | | `droid plugin uninstall ` | Uninstall a plugin. Alias: `droid plugin remove` | `droid plugin uninstall factory/code-review` | | `droid plugin update ` | Update a plugin to the latest version | `droid plugin update factory/code-review` | | `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 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"` | | `--enabled-tools ` | Force-enable specific tools (comma or space separated) | `droid exec --enabled-tools ApplyPatch,Bash` | | `--disabled-tools ` | Disable specific tools for this run | `droid exec --disabled-tools execute-cli` | | `--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 (`stream-jsonrpc` for multi-turn) | `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 (`off`, `none`, `low`, `medium`, `high`). 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](/features/missions/overview) (multi-agent orchestration) | `droid exec --mission -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 (`off`, `none`, `low`, `medium`, `high`) | `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, allowing you to 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 theme={null} # 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 [Bring Your Own Key (BYOK)](/cli/byok/overview). See [Choosing Your Model](/cli/user-guides/choosing-your-model) for detailed guidance on which model to use for different tasks. ## Interactive mode features ### Keyboard shortcuts The interactive REPL supports a rich set of keyboard shortcuts for navigation, overlays, and input control: | Shortcut | Action | | :-------------- | :------------------------------------------------------------------------------- | | `Ctrl+C` | Cancel the current operation / interrupt the agent. Press twice quickly to exit | | `Ctrl+Z` | Suspend the process (Unix only). Resume with `fg` | | `Ctrl+O` | Toggle the detailed transcript view (full message details) | | `Ctrl+T` | Toggle the Mission Control overlay (orchestrator sessions only) | | `Ctrl+N` | Cycle through available models (when typing in chat input) | | `Ctrl+L` | Cycle through autonomy levels (when typing in chat input) | | `Ctrl+Y` | Toggle the `/btw` scroll view (side-question history) | | `Ctrl+J` | Toggle the changelog display (dismiss / restore) | | `Ctrl+E` | Toggle the approval details view | | `Ctrl+V` | Paste an image from the clipboard as an attachment | | `Tab` | Cycle reasoning effort (`low` → `medium` → `high` → `off`) | | `Shift+Tab` | Cycle interaction modes (Auto → Spec → Mission) | | `@` | 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) | | `Ctrl+/` | Toggle the help popup (works even when the input has content) | | `Ctrl+A` | Move the cursor to the start of the line | | `Ctrl+W` | Delete the word before the cursor | | `Ctrl+K` | Delete from the cursor to the end of the line | | `Ctrl+U` | Delete from the cursor to the start of the line | | `Ctrl+D` | Clear all attached images, or forward-delete the next character if none attached | | `Ctrl+R` | Rename the highlighted session (in the `/sessions` list view) | | `Ctrl+X` | Archive the highlighted session (in the `/sessions` list view) | | `Alt+Up` | Scroll the transcript up (navigate any turn) | | `Alt+Down` | Scroll the transcript down (navigate any turn) | | `Alt+PageUp` | Scroll the transcript up to the previous user turn | | `Alt+PageDown` | Scroll the transcript down to the next user turn | | `Escape` | Close the active overlay or menu | | `Shift+Enter` | 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 `Shift+Enter` 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`. * **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 — 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` | Start a new session (alias for `/new`) | | `/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 new session | | `/plugins` | Manage plugins and marketplaces | | `/quit` | Exit droid (alias: `exit`, or press Ctrl+C) | | `/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 Shift+Enter | | `/themes` | Choose a color theme | For detailed information on slash commands, see the [interactive mode documentation](/cli/getting-started/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 theme={null} # 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 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 factory/code-review --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 theme={null} 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](/cli/configuration/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 at [app.factory.ai/settings/api-keys](https://app.factory.ai/settings/api-keys) 2. Set the environment variable: ```bash macOS/Linux theme={null} export FACTORY_API_KEY=fk-... ``` ```powershell Windows (PowerShell) theme={null} $env:FACTORY_API_KEY="fk-..." ``` ```cmd Windows (CMD) theme={null} 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. ## Exit codes | Code | Meaning | | :--- | :---------------------------- | | `0` | Success | | `1` | General runtime error | | `2` | Invalid CLI arguments/options | ## Common workflows ### Code review ```bash theme={null} # Local review workflow > /review # Analysis via exec (non-interactive) 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](/cli/features/code-review) for detailed guidance on review types, workflows, and best practices. ### Testing and debugging ```bash theme={null} # 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 theme={null} # 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 theme={null} # 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 theme={null} # 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 ``` ## See also * [Quickstart guide](/cli/getting-started/quickstart) - Getting started with the Droid CLI * [Interactive mode](/cli/getting-started/quickstart) - Shortcuts, input modes, and features * [Choosing your model](/cli/user-guides/choosing-your-model) - Model selection guidance * [Settings](/cli/configuration/settings) - Configuration options * [Custom commands](/cli/configuration/custom-slash-commands) - Create your own shortcuts * [Custom droids](/cli/configuration/custom-droids) - Build specialized agents * [Droid Exec overview](/cli/droid-exec/overview) - Detailed automation guide * [MCP configuration](/cli/configuration/mcp) - External tool integration