How to use Droid: a step-by-step guide to the Factory Droid CLI

To use Droid, Factory’s coding agent, you install the CLI with curl -fsSL https://app.factory.ai/cli | sh, run droid inside a project, sign in through the browser and describe the task. Droid asks before it edits a file or runs a command; for scripts and CI there is droid exec, which is read-only until you raise its autonomy.

This guide covers the Droid CLI as of November 2026 (version 1.12): install, sign-in, models, the interactive session, droid exec and its autonomy levels, AGENTS.md, MCP servers, custom droids and what it costs.

What Droid is

Droid is the terminal coding agent from Factory. It reads your codebase, proposes changes and applies them after you approve. The same agent also runs in Factory’s desktop and web apps, in IDE integrations and through an SDK. Version 1.0 shipped on October 29, 2026, and new versions come out several times a week.

Droid is not tied to one model vendor. It offers Anthropic, OpenAI, Google and xAI models, plus open-weight models that Factory groups as “Droid Core”, and you can add your own endpoints.

Step 1: install the CLI

On macOS or Linux:

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

Other options:

brew install --cask droid      # Homebrew
npm install -g droid           # npm

On Windows PowerShell:

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

On Linux, sign-in also needs xdg-utils (sudo apt-get install xdg-utils). Update later with droid update.

Step 2: sign in

cd my-project
droid

The first run opens the browser to sign in with a Factory account. For CI and other machines without a browser, create an API key in Factory’s settings and export it:

export FACTORY_API_KEY=fk-...

Step 3: work in a session

Describe the task in plain words. Droid explains what it plans, then asks before each edit or command. Useful keys and commands:

• Shift+Tab switches between the normal mode and spec mode, where Droid writes a plan before it changes code.
• ! runs a shell command yourself; ? lists the shortcuts.
• /model changes the model, /settings opens the settings, /review asks for a review of the changes.
• /compress shortens a long conversation; /sessions lists earlier ones.

To come back later, run droid --resume (or droid --resume <id>). droid search "checkout bug" finds an old session by its text, and --fork <id> copies one.

Step 4: pick a model

Switch models with /model in a session, -m on the command line, or a model key in settings. On paid plans each model counts against your usage with a multiplier: as of November 2026 Claude Opus 5.5 counts 1.6x, Claude Sonnet 5.5 0.8x and Claude Haiku 5.5 0.04x. Use a small model for routine edits and a large one for design and debugging.

To bring your own key, add a custom model to ~/.factory/settings.json:

{
  "customModels": [
    {
      "model": "claude-sonnet-5-5",
      "displayName": "Sonnet (my key)",
      "baseUrl": "https://api.anthropic.com",
      "apiKey": "${ANTHROPIC_API_KEY}",
      "provider": "anthropic"
    }
  ]
}

provider is anthropic, openai, generic-chat-completion-api or bedrock-converse. Keys stay on your machine.

Step 5: droid exec and autonomy levels

droid exec runs one task without a chat, which is what you want in scripts and CI:

droid exec "summarize the changes on this branch"
droid exec --auto low "fix the failing unit test in price.test.ts"
droid exec -f task.md -o json --auto medium

By default it is read-only. You raise what it may do:

--skip-permissions-unsafe turns off all prompts; keep it for throwaway containers. Note that exit code 0 means Droid finished, not that the task succeeded, so check the result in CI. For interactive sessions you can set a default level with sessionDefaultSettings.autonomyLevel and finer permissionRules (allow, ask, block) in settings.

Step 6: AGENTS.md and settings

Droid reads AGENTS.md as the repository’s instructions. Keep it short: the stack, how to run tests, what not to touch and what “done” means. Our guide to CLAUDE.md and AGENTS.md covers what to put in it.

Settings live in ~/.factory/settings.json for you and .factory/settings.json for the project, each with a settings.local.json for overrides you don’t commit.

Step 7: MCP servers and custom droids

Add MCP servers from the command line:

droid mcp add docs https://example.com/mcp --type http
droid mcp add memory "npx -y @modelcontextprotocol/server-memory"

They are saved in ~/.factory/mcp.json (or .factory/mcp.json for the project) under mcpServers. In a session, /mcp manages them, including OAuth sign-ins.

Custom droids are subagents: a Markdown file with a YAML header (name, description, model, tools and more) in .factory/droids/ or ~/.factory/droids/. Droid hands work to them through its Task tool, and /droids manages them. A small “test writer” or “reviewer” droid on a cheap model is a good first one.

What Droid costs (as of November 2026)

Check Factory’s pricing page before you decide; plans change often.

Common pitfalls

• Old docs links. The docs moved from docs.factory.ai to docs.factory.com; install URLs still use app.factory.ai.
• Running exec with high autonomy too early. Start CI jobs at --auto low and raise the level only for steps that need it.
• Trusting exit code 0. It only means the run ended. Check tests or the diff afterwards.
• -r means two things. In droid, -r resumes a session; in droid exec, it sets the reasoning effort. Use --resume in full to avoid surprises.

Running Droid next to other CLIs in AgentVera

If Droid is your only agent, Factory’s own apps may be all you need. It gets harder when Droid runs next to Claude Code, Codex or Gemini CLI on the same project. AgentVera is a desktop app that runs these CLIs side by side in real terminals, with your own installs and logins. Droid support works like this:

• One session per agent. AgentVera finds the session Droid creates and reopens it with droid --resume <id> on later launches, so the conversation survives an app restart.
• Model, effort and role. The model and effort you pick for the agent are passed through a settings file, and the agent’s role with --append-system-prompt.
• Your login or API keys. Droid keeps your Factory login. Under Settings → Accounts you can add FACTORY_API_KEY accounts and give each agent its own.
• Panes, worktrees and review. Run Droid in the workspace grid next to other agents, each in its own git worktree, and check their changes with code review.

The free plan includes up to 18 agents, MCP, Git, Docker, SSH, code review and token savings. Pro is $9.99 a month; if you have never had a trial, your first sign-in to the app turns on Pro for 7 days with no card. To try it, download AgentVera.

Wrapping up

Droid takes two commands to start: the install script and droid. What matters after that is control: keep interactive sessions on approval, start droid exec at --auto low, put the project’s rules in AGENTS.md, and pick a model per task with the usage multiplier in mind.

Sources: Droid quickstart, CLI reference, droid exec, models, MCP, changelog.