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 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 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, --reasoning-effort <level>	Override reasoning effort (off, none, low, medium, high)	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
-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

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.

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
/bg-process	Manage background processes
/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
/cost	Show usage statistics
/create-skill	Create a reusable skill from current session
/droids	Manage custom droids
/missions	Enter Mission Mode
/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
/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-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
/share	Share session with organization
/skills	Manage and invoke skills
/status	Show current droid status and configuration
/statusline	Configure custom status line
/terminal-setup	Configure terminal keybindings for Shift+Enter
/wrapped	Show Droid usage statistics

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.

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