Droid CLI Reference

Installation

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:

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:

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.

Direct binary download

Release binaries and their SHA256 checksums use the following paths:

https://downloads.factory.ai/factory-cli/releases/<version>/<platform>/<arch>/<binary>
https://downloads.factory.ai/factory-cli/releases/<version>/<platform>/<arch>/<binary>.sha256

• <platform>: linux, darwin, or windows
• <arch>: x64, arm64, or x64-baseline
• <binary>: droid on Linux and macOS, or droid.exe on Windows

For example, download and verify the Linux x64 binary:

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

Droid CLI flags

Customize droid's behavior with command-line flags:

Autonomy levels

droid exec uses tiered autonomy to control what operations the agent can perform. Only raise access when the environment is safe.

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"

Model IDs

Use any available model ID with -m, --model or --spec-model. For custom models, see Custom Models (BYOK).

Interactive mode features

Keyboard shortcuts

The interactive REPL supports a rich set of keyboard shortcuts for navigation, overlays, and input control:

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, 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:

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.

Subcommand flags

In addition to the global flags above, several droid subcommands accept their own flags.

droid update flags

droid search flags

droid mcp add flags

droid plugin flags

droid computer register flags

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

1. 1
   Generate an API key in the Factory API keys settings
2. 2
   Set the environment variable:

export FACTORY_API_KEY=fk-...

Persist the variable in your shell profile (~/.bashrc, ~/.zshrc, or PowerShell $PROFILE) for long-term use.

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:

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 and organization controls.

Exit codes

Common workflows

Code review

Interactive review inside a Droid session:

> /review

Non-interactive review through droid exec:

# 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 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