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

URL: https://agentvera.dev/en/blog/how-to-use-droid/ · Published: 2026-11-14

How to use Factory Droid in the terminal: install, sign in, pick a model, run droid exec with autonomy levels, and set up AGENTS.md, MCP and custom droids.

**In short:**

- Install with curl -fsSL https://app.factory.ai/cli | sh (or brew install --cask droid), run droid in a project, sign in through the browser and describe the task. Droid asks before it edits files or runs commands.
- For scripts and CI, droid exec is read-only by default; --auto low allows edits, medium adds installs, builds, tests and commits, high adds pushes and deploys. Use FACTORY_API_KEY for headless runs.
- The Free plan works with your own inference (ChatGPT, Copilot, OpenRouter or API keys); Pro is $20 a month as of November 2026. Rules go in AGENTS.md, settings and MCP servers in ~/.factory/.

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](https://factory.com "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:

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

Other options:

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

On Windows PowerShell:

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

```bash
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:

```bash
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`:

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

```bash
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:

| Level | What it allows |
|---|---|
| (default) | Read only |
| `--auto low` | File edits |
| `--auto medium` | Also installs, builds, tests, commit, checkout and pull |
| `--auto high` | Also pushes and deploys |

`--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](/en/blog/claude-md-agents-md/ "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:

```bash
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)

| Plan | Price | Notes |
|---|---|---|
| Free | $0 | You bring the inference: ChatGPT, Copilot, OpenRouter or your own keys |
| Pro | $20/month | All models, desktop app, CLI and SDK |
| Plus | $100/month | About 5x Pro’s usage |
| Max | $200/month | About 10x Pro’s usage |
| Teams | $60/month + $40/seat | Up to 10 seats |

Check [Factory’s pricing page](https://factory.com/pricing "Factory pricing") before you decide; plans change often.

## Common pitfalls

- **Old docs links.** The docs moved from docs.factory.ai to [docs.factory.com](https://docs.factory.com "Factory docs"); 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](/en/ "AgentVera") is a desktop app that runs these CLIs side by side in real terminals, with your own installs and logins. [Droid support](/en/agents/factory-droid/ "Factory Droid in AgentVera") 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](/en/features/workspace/ "Workspace") grid next to other agents, each in its own git worktree, and check their changes with [code review](/en/features/code-review/ "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](/en/download/ "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](https://docs.factory.com/cli/getting-started/quickstart "Droid quickstart"), [CLI reference](https://docs.factory.com/docs/droid-cli/cli-reference "Droid CLI reference"), [droid exec](https://docs.factory.com/docs/droid-exec/overview "droid exec"), [models](https://docs.factory.com/docs/models "Droid models"), [MCP](https://docs.factory.com/docs/harness/mcp "Droid MCP"), [changelog](https://docs.factory.com/changelog/cli-updates "Droid CLI changelog").

## Frequently asked questions

**Is Factory Droid free?** There is a Free plan at $0 where you bring the inference: sign in with ChatGPT, GitHub Copilot or OpenRouter, or add your own API keys. Paid plans as of November 2026 are Pro at $20, Plus at $100 and Max at $200 a month, with more usage at each step.

**Can I use my own API key with Droid?** Yes. Add a customModels entry to ~/.factory/settings.json with the model name, base URL, provider and key (it can read the key from an environment variable). Keys stay on your machine, and custom models work in the CLI and the desktop app.

**What is the difference between droid and droid exec?** droid opens an interactive session that asks before each edit or command. droid exec runs one task without a chat, for scripts and CI. It is read-only unless you raise the autonomy with --auto low, medium or high.

**Does Droid read AGENTS.md?** Yes. AGENTS.md is the instructions file Droid reads for a repository: put the stack, the test command, the rules and what not to touch there.

**How do I resume a Droid session?** Run droid --resume to pick a recent session, or droid --resume <id> for a specific one. droid search "text" finds old sessions, and --fork <id> copies one so you can try another direction.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/