factory/docs/reference/cli-reference.mdx at 7f2091031efebcd937b15aa741925100621f0313 · Factory-AI/factory

title	Droid CLI Reference
description	Complete reference for the Droid CLI, including commands and flags

Installation

curl -fsSL https://app.factory.ai/cli | sh

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 <sessionId>`	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 <id> "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 <name> <url>`	Add an MCP server	`droid mcp add api https://api.example.com/mcp --type http`
`droid mcp remove <name>`	Remove an MCP server	`droid mcp remove linear`
`droid plugin install <plugin>`	Install a plugin. Alias: `droid plugin i`	`droid plugin install factory/code-review`
`droid plugin uninstall <plugin>`	Uninstall a plugin. Alias: `droid plugin remove`	`droid plugin uninstall factory/code-review`
`droid plugin update <plugin>`	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 <name>`	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 <path>`	Read prompt from a file	`droid exec -f plan.md`
`-m, --model <id>`	Select a specific model ID	`droid exec -m claude-opus-4-8`
`-s, --session-id <id>`	Continue an existing session	`droid exec -s session-abc123`
`--auto <level>`	Set autonomy level (`low`, `medium`, `high`)	`droid exec --auto medium "run tests"`
`--enabled-tools <ids>`	Force-enable specific tools (comma or space separated)	`droid exec --enabled-tools ApplyPatch,Bash`
`--disabled-tools <ids>`	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 <format>`	Output format (`text`, `json`, `stream-json`, `stream-jsonrpc`)	`droid exec -o json "document API"`
`--input-format <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 <level>`	Override reasoning effort; valid values are model-dependent (see Reasoning effort). In `droid exec`, `-r` maps to this flag.	`droid exec -r high "debug flaky test"`
`--spec-model <id>`	Use a different model ID for specification planning	`droid exec --spec-model claude-opus-4-8`
`--spec-reasoning-effort <level>`	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 <path>`	Execute from a specific working directory	`droid exec --cwd ../service "run tests"`
`-w, --worktree [name]`	Run the session in an isolated git worktree	`droid --worktree fix-bug`
`--tag <spec>`	Session tag (name or JSON, repeatable)	`droid exec --tag code-review`
`--log-group-id <id>`	Log group ID for filtering logs	`droid exec --log-group-id grp-123`
`--fork <id>`	Fork and resume an existing session into a new copy	`droid exec --fork session-abc123`
`--mission`	Run `droid exec` in mission mode (multi-agent orchestration)	`droid exec --mission -f mission.md`
`--worker-model <id>`	Model used for mission worker agents	`droid exec --mission --worker-model claude-sonnet-4-6`
`--worker-reasoning-effort <level>`	Reasoning effort for mission worker agents (model-dependent; see Reasoning effort)	`droid exec --mission --worker-reasoning-effort medium`
`--validator-model <id>`	Model used for mission validator agents	`droid exec --mission --validator-model claude-opus-4-8`
`--validator-reasoning-effort <level>`	Reasoning effort for mission validator agents	`droid exec --mission --validator-reasoning-effort high`
`--append-system-prompt <text>`	Append custom text to the end of the system prompt	`droid --append-system-prompt "Always run tests."`
`--append-system-prompt-file <path>`	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:

# 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 with -m, --model or --spec-model. For custom models, see Bring Your Own Key (BYOK).

See 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+P`	Toggle the blog post viewer
`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 through the levels supported by the current model
`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 (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 <question>`	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 <path>`	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
`/generate_blog`	Generate semantic diff blog post
`/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 <locale>`	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.

Git worktrees

Use -w, --worktree [name] to run a session inside a native 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 (../<repo>-wt-<branch>/) with its own checkout and dedicated branch.

Branch naming:

--worktree (no value) — Creates/reuses a worktree on a branch named <current-branch>-wt.
--worktree <name> — Uses <name> 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:

# Interactive: derive branch from current branch (creates <current>-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 <kind>`	Filter by entry kind: `message_text`, `document`, `tool_use`, `tool_result`, or `all`	`droid search "auth" --kind document`
`--limit-sessions <n>`	Maximum number of sessions to return	`droid search "auth" --limit-sessions 5`
`--limit-hits <n>`	Maximum number of matches per kind per session	`droid search "auth" --limit-hits 3`
`--context-chars <n>`	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 <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 <KEY=VALUE>`	Set an environment variable for a stdio server (repeatable)	`droid mcp add gh "gh-mcp" --type stdio --env GH_TOKEN=$GH_TOKEN`
`--header <KEY: VALUE>`	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 <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:

droid mcp add <name> <url> --type http    # Add HTTP (streamable) server
droid mcp add <name> <url> --type sse     # Add legacy HTTP+SSE server
droid mcp add <name> "<command>"          # Add stdio server
droid mcp remove <name>                   # Remove a server

See MCP Configuration for the full registry list, CLI options (--env, --header), configuration files, and how user vs project config layering works.

Authentication

Generate an API key at app.factory.ai/settings/api-keys
Set the environment variable:

export FACTORY_API_KEY=fk-...

$env:FACTORY_API_KEY="fk-..."

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

# 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 for detailed guidance on review types, workflows, and best practices.

Testing and debugging

# 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

# Planning
droid exec "Create refactoring plan for auth module"

# Execution
droid exec --auto low --use-spec "Refactor auth module"

Parallel sessions on one repo

# 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 for details.

CI/CD integration

# 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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Installation

Droid CLI commands

Droid CLI flags

Autonomy levels

Model IDs

Interactive mode features

Keyboard shortcuts

Bash mode

Mermaid diagram rendering

Slash commands

Git worktrees

Subcommand flags

`droid search` flags

`droid mcp add` flags

`droid plugin` flags

`droid computer register` flags

MCP command reference

Authentication

Exit codes

Common workflows

Code review

Testing and debugging

Refactoring

Parallel sessions on one repo

CI/CD integration

See also

Uh oh!

FilesExpand file tree

cli-reference.mdx

Latest commit

History

cli-reference.mdx

File metadata and controls

Installation

Droid CLI commands

Droid CLI flags

Autonomy levels

Model IDs

Interactive mode features

Keyboard shortcuts

Bash mode

Mermaid diagram rendering

Slash commands

Git worktrees

Subcommand flags

droid search flags

droid mcp add flags

droid plugin flags

droid computer register flags

MCP command reference

Authentication

Exit codes

Common workflows

Code review

Testing and debugging

Refactoring

Parallel sessions on one repo

CI/CD integration

See also

`droid search` flags

`droid mcp add` flags

`droid plugin` flags

`droid computer register` flags