Droid CLI Reference

Complete reference for the Droid CLI, including commands and flags

Installation

macOS/Linux

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

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-7
-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 (off, none, low, medium, high). 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-sonnet-4-6
--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 (off, none, low, medium, high)	droid exec --mission --worker-reasoning-effort medium
--validator-model <id>	Model used for mission validator agents	droid exec --mission --validator-model claude-opus-4-7
--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 (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 (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) 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 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

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

macOS/Linux

export 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

See also

• Quickstart guide - Getting started with the Droid CLI
• Interactive mode - Shortcuts, input modes, and features
• Choosing your model - Model selection guidance
• Settings - Configuration options
• Custom commands - Create your own shortcuts
• Custom droids - Build specialized agents
• Droid Exec overview - Detailed automation guide
• MCP configuration - External tool integration