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

List computers and environments

droid computer list lists your computers and the Factory Environments visible to your identity, including whether each Environment can launch. It is read-only and prints JSON by default. Use --human for readable tables.

droid computer list
droid computer list --human

To list another identity's inventory, first list the organization's service accounts, then select an active account by its ID or name. Both account discovery and account selection require the Manager role or higher. Replace the example values with an account returned by the first command:

droid computer service-accounts list
droid computer list --service-account-id sa_example
droid computer list --service-account-name "deploy-bot"

The service-account list returns {"ok": true, "data": {"serviceAccounts": [...]}}. Each account has id, name, and status. Deleted accounts are omitted; inactive accounts remain visible, but only active accounts can be selected with the flags above or run automations.

Read the human output

In English, --human prints a computer table with COMPUTER, STATUS, PROVIDER, and ID columns and marks this machine with (this machine) when Droid can identify it. When there are no computers, it prints a message instead: how to register this machine for your own inventory, or No computers registered for service account "<name>". for a selected account.

When Environments are returned, a Factory Environments: section follows after a blank line. The table has ENVIRONMENT, STATUS, SCOPE, LAUNCHABLE, and ID columns, and LAUNCHABLE is yes or no. For example, with illustrative names and IDs:

COMPUTER               STATUS  PROVIDER  ID
laptop (this machine)  active  byom      3f2a9c1e-5b7d-4e8a-9c0f-1d2e3f4a5b6c
dev-box                active  e2b       8b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e
 
Factory Environments:
ENVIRONMENT   STATUS    SCOPE         LAUNCHABLE  ID
team-default  ready     organization  yes         0c56098a-c40d-4a56-bdd2-8f58120dc456
my-sandbox    building  user          no          6de596d4-1a67-4ebc-be46-61265c198698

With --service-account-id or --service-account-name, the heading is Factory Environments service account "<name>" can launch:.

If the Environment lookup fails, one line replaces the Environments section, and the computers still list. The HTTP status appears when one is available:

Factory Environments could not be listed (HTTP <status>: <error>).

Without an HTTP status, the line is Factory Environments could not be listed (<error>). When the lookup succeeds with no Environments, the section is omitted.

Read the JSON result

A successful computer list returns {"ok": true, "data": {...}} with these fields:

Each Environment item has id, name, status, scope, and launchable. Use an Environment with launchable: true when choosing an automation's environmentName. Account selection applies to both the computers and Environments in the result.

An Environment lookup can fail while the computer list succeeds. Check data.environments.ok before reading items: ok: false means the lookup failed, not that no Environments exist. The top-level ok can still be true, and the command can exit successfully with the computer inventory intact.

Migrate existing scripts and prompts

droid computer list defaults to JSON. If a script expects the computer table, add --human and account for the Factory Environments section, or update the script to read data.computers and handle data.environments separately.

Update tool names in prompts and automation instructions:

Check permission rules

Use droid rules check to validate permission rules, run their embedded matching examples, and preview a decision without executing a command.

droid rules check
droid rules check --command 'git push origin main'
droid rules check --file rules.json --command 'npm publish' --json

Without --file, the checker validates resolved settings. A command preview follows the active policy engine; validating rules does not enable enforcement on a client still using legacy policy.

Exit code 0 means the check succeeded, even if the preview says block. Invalid rules or failed examples produce exit code 1. Preview covers command policy only, not hooks, sandbox permissions, autonomy, or session approvals.

The commandAllowlist, commandDenylist, and commandBlocklist settings are deprecated but remain respected for backward compatibility. Use permissionRules for new policy; see migration guidance.

Droid CLI flags

Customize droid's behavior with command-line flags:

Manage automations

droid automations creates and manages automations from your terminal. Each command is the command form of a tool Droid calls in a session, and both take the same inputs. Each field of the tool is a flag in kebab case, such as --execution-location for executionLocation, except automationId: read, edit, delete, and run take it as their first argument.

Every command except templates list and run requires --execution-location: local for automations on this machine, or remote for automations in the cloud. Webhook, Slack, and chained automations are always remote. A local schedule runs only while the desktop app or a standalone droid daemon is running on this machine; a terminal session alone does not run it. Factory-managed Droid Computers never run local schedules, so create a remote automation there.

droid automations templates list --trigger slack
droid automations list --execution-location remote
droid automations read 3f2a9c1e-5b7d-4e8a-9c0f-1d2e3f4a5b6c --execution-location remote

create needs --name and --prompt, unless --template-id incident-response supplies them for a Slack automation. That preset also sets --message-source bots and --session-privacy team; explicit flags override its defaults. A scheduled automation needs --schedule: a five-field cron expression for local, or a cron expression or natural-language cadence for remote. New automations default to --status active.

A remote automation needs exactly one run target: --computer-name or --computer-id for a computer, or --environment-name or --environment-id to start each run on a fresh computer built from a Factory Environment. To deliver runs into an existing session instead, pass --deliver-to-session-id and no run target; runs happen wherever that session lives. Slack automations cannot deliver into a session.

For session delivery, --execution-location is still required, but the session determines the actual location. A session on another unregistered local machine cannot be targeted from this machine. In a tool call, deliverToSessionId: "current" names the calling session; a terminal command must use an explicit session ID. Runs keep that session's autonomy, model, and tools, so --model and --reasoning-effort are ignored and runs can wait for permission. A session-delivery automation cannot start a chain. For a remote automation already configured this way, edit --deliver-to-session-id can move delivery to another session of the same machine kind, but cannot turn session delivery off.

If --computer-id or --computer-name identifies a temporary computer created from an Environment, Factory targets that Environment instead, so each run gets a fresh computer.

Creating a remote scheduled automation also starts its first run right away, unless you pass --status paused or it delivers into a session. If that run cannot start, the automation is still created, and data.notes says why.

droid automations create \
  --execution-location remote \
  --name "Weekday PR summary" \
  --schedule "0 9 * * 1-5" \
  --prompt "Summarize the pull requests merged yesterday." \
  --computer-name dev-box

Flags follow the tool's field types:

• A boolean field takes --<flag> for true and --no-<flag> for false, as in --rotate-webhook-secret.
• A list field takes several values or a repeated flag, and each value is added to the list. A value that starts with [ is read as a JSON array and replaces the list, so --triggered-by-automation-ids '[]' clears it.
• --visualization_instruction and --memory_instruction keep their underscores. On create, they append visualization and memory guidance to the run prompt.

Run droid automations <command> --help to list every flag.

Useful options beyond the run target:

A chain can be at most five automations deep, counting the first. Each automation can have up to five sources and start up to five others; loops are rejected. Sources must have the same owner and be scheduled, webhook, or chained automations, not Slack or CI. --trigger automation waits only for its sources; another trigger keeps working alongside the sources you add.

Each command prints JSON; there is no human-readable mode. A success prints {"ok": true, "data": {...}} to stdout and exits 0. A failure prints {"ok": false, "code": "...", "error": "..."} to stderr, sometimes with details, and exits 1.

A success can still carry a partial result, so read data before you move on. When create or edit saves the change but cannot read the automation back, data.readError says why. When edit --rotate-webhook-secret saves the other changes but cannot rotate the secret, the old secret keeps working and data.rotationError says why. data.notes explains the rest of the result, such as where the automation runs.

In droid exec at the default autonomy, Droid can list templates, list automations, and read one, because those tools are read-only. Creating, editing, or running an automation is medium risk. Deleting one, or creating one that runs as a service account, is high risk. See autonomy levels. The automation tools are not available in an airgapped deployment.

Choose Slack channels

To have someone pick a Slack automation's channels, leave --slack-channels and --slack-channel-patterns out of create, or pass --choose-slack-channels to edit. --name-filter <text> narrows the channels offered to names that contain the text, in any case.

In an interactive terminal, or on a direct tool call in a CLI session that can ask you questions, a channel picker opens. On edit, it starts from the automation's current channels. The selection replaces the channel set, as --slack-channels would. Press Ctrl+R to reload the channel list, or Esc or Ctrl+C to cancel. A command in your terminal exits 130; in a Droid session, cancelling ends Droid's turn.

Calls inside Script never open the picker, even in a CLI session. They return input_required, as do tool calls in the desktop app, the web app, or droid exec when they need a channel selection. details.rows lists up to 100 channels, details.total counts every channel that matches --name-filter, and details.preselectedIds marks the channels already configured. Confirm the set, then run the command again with --slack-channels, or have Droid call the tool again with slackChannels.

On edit, --slack-channels and --choose-slack-channels replace the whole set, so they cannot be combined with --add-slack-channels or --remove-slack-channels. A replacement keeps the configured channels that the Factory Slack app can no longer see; the result lists them in slackChannels.unavailable, next to the channels added and removed.

Read automation results

read returns the automation and its full prompt, or prompt: null when a local automation's prompt could not be read. For a cloud automation, it also returns triggeredBy, the automations whose runs start this one. For a webhook automation, it returns deliveries, up to five recent deliveries with the newest first, which show why a delivery did not start a run. Each is a separate lookup that can fail on its own, so each is either {"ok": true, "items": [...]} or {"ok": false, "error": "..."}, with a status when the lookup got an HTTP error. triggeredBy always fails for an automation someone else owns, because only the owner's list shows what starts it.

Cloud automation records also expose nextAutomationIds for downstream automations and targetSessionId when runs deliver into an existing session.

list omits prompts. Each listed automation can include modelAvailable; read, create, and edit can return it alongside the automation. false means its pinned model does not resolve in the catalog and runs fall back to the default. An absent field means the pin was not checked, including remote custom models.

A webhook's secret appears only once: with its URL in the result of create, or in the result of edit --rotate-webhook-secret, which replaces it.

run returns started: true, automationId, name, sessionId, isPaused, isWebhook, and nextAutomationIds. sessionId is nullable; a local shared-session run returns its target session's ID. nextAutomationIds lists downstream automations. When Factory refuses to start the run, run still exits 0 and returns started: false with a reason and a detail:

In a Droid session that the desktop app or a standalone droid daemon runs, run also starts a local automation that daemon hosts, by its slug or ID.

A run started this way gets no delivery payload or message from the caller. Its downstream automations still run when it ends. A paused automation still runs. If the start request fails, run fails with request_failed, and details.reason is network, backend_error, or dispatch_failed. A call that names no automation, or both an ID and a name, fails with invalid_input.

Renamed automation tools

The automation tools share these commands' names. A Script calls each one at its script path:

A saved denial or --remove-tools entry that names a previous tool name also denies the renamed tool. automations_create does not take chooseSlackChannels; leave the channels out to have someone pick them. automations_edit applies chooseSlackChannels in the same call as any other update.

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).

droid exec --model and --spec-model also accept provider tier aliases such as openai-latest-balanced, which follow Factory's recommended model for that provider and tier as new models ship.

Legacy models

When a newer version of a model is available to you, /model lists the older one in a collapsed Legacy Models section. Selecting a legacy model asks you to Switch to latest or Keep using legacy. Keeping it adds the model to legacyModelOverrides in your user settings.json, and Droid stops asking about it.

When Droid starts, it moves saved default models (including spec mode, subagent, mission, and compaction models) from a legacy model to its newer version, unless the model is in legacyModelOverrides. A model passed to droid exec --model runs as named.

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.

Markdown and math rendering

Droid renders supported inline Markdown styles in responses, including formatting inside table cells. It also converts inline and display TeX into Unicode math for terminal output.

Use \(...\) or $...$ for inline math. Use \[...\] or $$...$$ for display math. A completed code fence labeled latex, math, or tex also renders as display math:

```latex
\frac{a}{b}
```

Slash commands

Available when running droid in interactive mode. Type the command at the prompt:

Slash commands stay usable while the agent is running: read-only and settings commands open right away over the live stream, commands that modify the conversation or session (such as /new, /clear, /compress) ask for confirmation before stopping the current run, and /model, /fast, and /archive apply only between turns. /fork also runs immediately: it copies the session in the background and keeps you in the original session, so there is nothing to interrupt.

Archiving hides a session from your session lists without deleting any data. Restore an archived session anytime from the Archived tab in /sessions (where Ctrl+X restores instead of archiving), or send a new message in the archived session to restore it automatically.

For detailed information on slash commands, see the interactive mode documentation.

Session list

/sessions lists your previous sessions and opens with the newest one selected. Press Enter to resume the selected session, or use the /sessions shortcuts to rename it, archive it, or open its fork tree.

Forks appear directly under the session they came from, marked with ↳, so a session and its forks stay together. Each fork family takes its place in the list from its most recently active member. Search keeps the grouping: when a search hides a fork's parent, the fork stays under its nearest ancestor that still matches.

A chain of sessions that each continue the last, such as the new session /compress starts, stays in one column. The indent grows only below a session that has more than one fork.

Session tree

/tree shows the current session's fork family as one tree: the messages of the original session and every fork, joined at the points where the forks branched off. ← current marks where you are, and ● <title> marks the latest entry of each session in the family.

A conversation with no forks renders flat. Rows indent only where the conversation branches: ├─ and └─ connect each branch to the row it branched from, and │ carries a branch past the rows of its siblings.

Select a row and press Enter to act on it:

• On another session's latest entry, resume that session.
• On a user message, fork just before it and prefill the message so you can edit and resend it.
• On an assistant message, fork just after it and continue with an empty prompt.

The footer names the active filter. The filter keys work even when the current filter shows no rows.

Shift+L opens a one-line editor below the tree, prefilled with the row's label. Press Enter to save it as a [label] badge on the row, or Escape to cancel. Saving an empty label removes it. Letters you type in the editor never trigger tree shortcuts. A label holds one line of up to 32 characters; longer text ends in an ellipsis.

Labels last until you exit Droid. They survive closing /tree and switching or forking from it, and because forks share their history, one label marks the same entry in every session of the fork family. Labels are not saved to disk.

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.

By default, Droid creates worktrees under the worktreeDirectory setting, which defaults to ~/.factory/worktrees. Each worktree uses the path <root>/<8-character group>/<repository name>/ and has 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