Factory Droid CLI: install, commands, and safe automation

Install Droid CLI

Factory publishes standalone installers for macOS, Linux, and Windows, a Homebrew cask, an npm package, and versioned direct binaries with checksums. The standalone path is the quickest for an individual machine. npm or verified direct binaries are easier to pin in CI and managed development images.

# macOS or Linux standalone installer
curl -fsSL https://app.factory.ai/cli | sh

# macOS Homebrew cask
brew install --cask droid

# npm on macOS, Linux, or Windows
npm install -g droid

irm https://app.factory.ai/cli/windows | iex

After installation, open a new terminal if the installer changed PATH, then run droid --version. Linux users need xdg-utils for browser-based authentication and related desktop handoffs. On Debian or Ubuntu, Factory documents sudo apt-get install xdg-utils.

Pin a version for reproducible environments

Standalone installations enable automatic updates by default. That is convenient on a personal machine and undesirable in a reproducible CI image. The npm package has auto-updates disabled at build time, so installing an exact version keeps it fixed until the package is upgraded. Factory also supports selecting or rolling back a standalone version with the built-in updater.

# Pin the npm package
npm install -g droid@0.174.0

# Select or roll back a standalone installation
droid update --version 0.174.0

# Check without installing
droid update --check

The version above is an example from the documentation, not a recommendation to stay on that release. Choose a version tested by your organization. Factory publishes direct binaries and .sha256 files under version, platform, architecture, and binary paths. Supported platform labels include Linux, Darwin, and Windows; architectures include x64, arm64, and x64-baseline.

Run a small acceptance suite when upgrading: read-only repository analysis, one patch in a disposable branch, focused tests, JSON output parsing, permission denial, MCP connectivity, session resumption, and any custom hooks or plugins. Agent CLI releases can change prompts, tools, models, defaults, and output fields even when the command still launches.

Authenticate and start the first session

Navigate to a git repository and run droid. The CLI opens a full-screen terminal interface and, when needed, opens a browser login for the Factory account. Starting in a clean repository makes the first diff easy to understand and provides a reliable undo path.

cd /path/to/your/project
git status --short
droid

Use the first session to map the repository before granting writes. Ask for entry points, test commands, architecture boundaries, build tooling, and local instructions. Compare the answer with the repository. This catches missing dependencies, wrong working directories, and stale documentation before an edit trajectory begins.

Inside the TUI, Shift+Tab switches interaction modes, Ctrl+L cycles autonomy, ! enters direct shell mode from an empty prompt, and Ctrl+O shows the detailed transcript. Press ? for the current shortcut pane because bindings can evolve.

Interactive commands worth learning

Resume and fork serve different purposes. Resuming continues the same session state. Forking creates a copy so two approaches can diverge without contaminating the original trajectory. Compression summarizes older context so the model has room for later work, and can discard detail. After compression, restate critical invariants or keep them in repository instructions.

Use direct shell mode for known commands you want to run yourself. Its output appears in the working terminal without asking the model to interpret the command. When the output should inform Droid, return to normal input and reference the result or ask the agent to inspect the relevant artifact.

Droid Exec basics

Droid Exec performs one non-interactive task. It is the right surface for CI, scripts, scheduled jobs, pull request checks, and any workflow that needs explicit inputs and machine-readable outputs. The default is read-only reconnaissance, which makes an unadorned command safe for analysis jobs.

# Direct prompt
droid exec "summarize the authentication subsystem"

# Prompt file
droid exec -f .factory/prompts/security-review.md

# Piped input
git diff origin/main...HEAD | droid exec "write release notes"

# JSON result
droid exec -o json "list public API changes"

# Resume an exec session
droid exec -s session-123 "continue after the reviewer feedback"

Text output is for people and build logs. JSON returns a result object containing success state, duration, turn count, text, and a session ID. Streaming formats expose progress events. The current lower-level integration path uses matching stream-jsonrpc input and output, allowing a long-lived client to initialize, send turns, handle permission requests, receive tool events, interrupt, update settings, fork, and compact.

Use exit codes in automation: 0 means success, 1 indicates a general runtime error, and 2 indicates invalid arguments. A successful process still needs task-specific validation. Parse the output and then run deterministic format, type, test, or policy checks as separate steps.

Choose the minimum autonomy level

A request above the configured autonomy causes Droid Exec to stop rather than wait indefinitely for an interactive response. Current documentation describes fail-fast behavior with a nonzero exit and no partial changes from the denied operation. That makes missing privileges visible in CI.

Tool restrictions narrow the surface further. --restrict-tools limits a run to named tools. --additional-tools exposes an extra tool beyond defaults. --disabled-tools removes a specific tool. Run droid exec --list-tools to discover the IDs in the current installation before hard-coding them.

Plan first with Specification Mode

Add --use-spec to make Droid create a specification before executing. A different planning model and reasoning effort can be selected with --spec-model and --spec-reasoning-effort. This is useful when architecture work deserves a stronger model while implementation workers can use a faster one.

droid exec --use-spec --auto low "add user data export"

droid exec \
+  --use-spec \
+  --spec-model claude-opus-4-7 \
+  --spec-reasoning-effort high \
+  --auto medium \
+  -f feature.md

For interactive work, enter Specification Mode with Shift+Tab. Review the proposed acceptance criteria, affected files, migration behavior, compatibility, tests, and operational impact. Approving the plan also selects how implementation proceeds. Save the specification to the repository when another reviewer or remote session needs the same agreed artifact.

Specification Mode is valuable for multi-file features, unfamiliar code, security-sensitive changes, and migrations. A one-line mechanical fix may cost more to plan than to inspect. Pick the mode from the uncertainty and blast radius of the task.

Isolate changes with a worktree

The CLI can create an isolated git worktree with -w or --worktree. Each worktree has its own files and branch while sharing repository history. This prevents two concurrent sessions from editing the same checkout and makes cleanup easier after a rejected approach.

# Interactive isolated session
droid --worktree fix-auth-timeout

# Headless isolated task
droid exec --worktree docs-refresh --auto low "update API docs and run doc checks"

Inspect git status, branch, and worktree list before starting automation. A worktree does not isolate shared databases, ports, package caches, home-directory credentials, or external services. Concurrent agents can still collide outside the checkout. Assign distinct ports and test databases, and keep production credentials out of the session.

Models, reasoning, and session control

Use -m or --model to select a model ID. Reasoning effort is model-dependent and can be set for Droid Exec with -r. Be careful with the short flag: -r means resume in interactive mode and reasoning effort under droid exec. Prefer long flags in scripts.

droid exec --model claude-opus-4-7 --reasoning-effort high "debug the race"

droid --resume

droid --resume session-abc123

droid --fork session-abc123

droid search "authentication timeout"

Session IDs let automation continue after a gate, reviewer comment, or transient failure. Fork when two solution paths should be evaluated independently. Tags and log group IDs help group sessions for reporting. Use --cwd instead of relying on the caller’s current directory when a job runner can launch from several paths.

Model choice affects capability, latency, and plan consumption. Start with a model appropriate to the uncertainty. Use a lower-cost model for bounded mechanical work and a stronger model for ambiguous debugging or architecture. Verification remains external to model confidence.

MCP, plugins, and Droid Computers

The CLI manages MCP servers directly. Add an HTTP server with droid mcp add, inspect it in the TUI with /mcp, and remove it when no longer required. MCP tools can expose tickets, documents, databases, or services. Treat each server as executable capability and scope its credentials.

droid mcp add linear https://mcp.linear.app/sse --type http
droid mcp remove linear

droid plugin install droid-control@factory-plugins
droid plugin list

droid computer register buildbox
droid daemon --remote-access
droid computer list
droid computer ssh buildbox
droid computer port-forward buildbox 8080:80 5432

Plugins package skills, commands, hooks, agents, and supporting code. Review source and requested capabilities before installation. Pin versions in controlled environments. Built-in and custom skills can alter the procedures loaded for a task; use --disable-builtin-skills when a minimal baseline is required.

Droid Computer commands register customer-owned machines, connect through the Factory relay, open SSH, and forward TCP ports. Managed computers are created in the Factory app. Persistent hosts retain state across sessions, so their lifecycle requires patching, secret rotation, cleanup, monitoring, and an operator outside the agent.

Run Missions headlessly

Use --mission for multi-agent orchestration from Droid Exec. The run requires High autonomy or the unsafe permission bypass. Worker and validator models plus reasoning effort can be selected independently. Put the Mission definition in a versioned prompt file so the goal, milestones, boundaries, and checks are reviewable.

droid exec --mission --auto high \
+  --worker-model claude-sonnet-4-6 \
+  --worker-reasoning-effort medium \
+  --validator-model claude-opus-4-7 \
+  --validator-reasoning-effort high \
+  -f migration-mission.md

Run Missions in a dedicated worktree or isolated runner with narrow credentials. Define file ownership, shared interfaces, integration sequence, test commands, failure policy, and a spend ceiling outside the agent transcript. Factory Missions consume normal rolling limits and require Extra Usage enabled, so a long run can pause when limits or credits are exhausted.

A validator model is a useful second pass and remains probabilistic. Deterministic builds, tests, schema checks, linters, migration inventories, and security scanners should decide milestone acceptance where possible.

Common installation and runtime failures

When a regression follows an upgrade, record droid --version, operating system, installation method, command, exit code, sanitized stderr, working directory, autonomy, model, and whether the issue reproduces in a clean repository. Roll back to the last accepted version when the fix cannot wait.

Do not debug an agent error by immediately granting High autonomy or the unsafe bypass. A permission failure says which capability the task requires. Decide whether the job should have that capability, then change the environment or command deliberately.

Preserve the denied command in the job log so the policy decision stays auditable.

Questions people ask

Keep reading