> ## Documentation Index
> Fetch the complete documentation index at: https://docs.factory.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Complete reference for droid command-line interface, including commands and flags

## Installation

<CodeGroup>
  ```bash macOS/Linux theme={null}
  curl -fsSL https://app.factory.ai/cli | sh
  ```

  ```powershell Windows theme={null}
  irm https://app.factory.ai/cli/windows | iex
  ```
</CodeGroup>

The CLI operates in two modes:

* **Interactive (`droid`)** - Chat-first REPL with slash commands
* **Non-interactive (`droid exec`)** - Single-shot execution for automation and scripting

## CLI commands

| Command                      | Description                               | Example                                        |
| :--------------------------- | :---------------------------------------- | :--------------------------------------------- |
| `droid`                      | Start interactive REPL                    | `droid`                                        |
| `droid "query"`              | Start REPL with initial prompt            | `droid "explain this project"`                 |
| `droid exec "query"`         | Execute task without interactive mode     | `droid exec "summarize src/auth"`              |
| `droid exec -f prompt.md`    | Load prompt from file                     | `droid exec -f .factory/prompts/review.md`     |
| `cat file \| droid exec`     | Process piped content                     | `git diff \| droid exec "draft release notes"` |
| `droid exec -s <id> "query"` | Resume existing session in exec mode      | `droid exec -s session-123 "continue"`         |
| `droid exec --list-tools`    | List available tools, then exit           | `droid exec --list-tools`                      |
| `droid update`               | Manually update the CLI to latest version | `droid update`                                 |

## CLI flags

Customize droid's behavior with command-line flags:

| Flag                              | Description                                                        | Example                                                      |
| :-------------------------------- | :----------------------------------------------------------------- | :----------------------------------------------------------- |
| `-f, --file <path>`               | Read prompt from a file                                            | `droid exec -f plan.md`                                      |
| `-m, --model <id>`                | Select a specific [model ID](/models)                              | `droid exec -m claude-opus-4-7`                              |
| `-s, --session-id <id>`           | Continue an existing session                                       | `droid exec -s session-abc123`                               |
| `--auto <level>`                  | Set [autonomy level](#autonomy-levels) (`low`, `medium`, `high`)   | `droid exec --auto medium "run tests"`                       |
| `--enabled-tools <ids>`           | Force-enable specific tools (comma or space separated)             | `droid exec --enabled-tools ApplyPatch,Bash`                 |
| `--disabled-tools <ids>`          | Disable specific tools for this run                                | `droid exec --disabled-tools execute-cli`                    |
| `--list-tools`                    | Print available tools and exit                                     | `droid exec --list-tools`                                    |
| `-o, --output-format <format>`    | Output format (`text`, `json`, `stream-json`, `stream-jsonrpc`)    | `droid exec -o json "document API"`                          |
| `--input-format <format>`         | Input format (`stream-jsonrpc` for multi-turn)                     | `droid exec --input-format stream-jsonrpc -o stream-jsonrpc` |
| `-r, --reasoning-effort <level>`  | Override reasoning effort (`off`, `none`, `low`, `medium`, `high`) | `droid exec -r high "debug flaky test"`                      |
| `--spec-model <id>`               | Use a different [model ID](/models) for specification planning     | `droid exec --spec-model claude-sonnet-4-6`                  |
| `--spec-reasoning-effort <level>` | Override reasoning effort for spec mode                            | `droid exec --use-spec --spec-reasoning-effort high`         |
| `--use-spec`                      | Start in specification mode (plan before executing)                | `droid exec --use-spec "add user profiles"`                  |
| `--skip-permissions-unsafe`       | Skip all permission prompts (⚠️ use with extreme caution)          | `droid exec --skip-permissions-unsafe`                       |
| `--cwd <path>`                    | Execute from a specific working directory                          | `droid exec --cwd ../service "run tests"`                    |
| `--tag <spec>`                    | Session tag (name or JSON, repeatable)                             | `droid exec --tag code-review`                               |
| `--log-group-id <id>`             | Log group ID for filtering logs                                    | `droid exec --log-group-id grp-123`                          |
| `-v, --version`                   | Display CLI version                                                | `droid -v`                                                   |
| `-h, --help`                      | Show help information                                              | `droid --help`                                               |

<Tip>
  Use `--output-format json` for scripting and automation, allowing you to parse droid's responses
  programmatically.
</Tip>

## Autonomy levels

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

| Level                       | Intended for             | Notable allowances                                            |
| :-------------------------- | :----------------------- | :------------------------------------------------------------ |
| *(default)*                 | Read-only reconnaissance | File reads, git diffs, environment inspection                 |
| `--auto low`                | Safe edits               | Create/edit files, run formatters, non-destructive commands   |
| `--auto medium`             | Local development        | Install dependencies, build/test, local git commits           |
| `--auto high`               | CI/CD & orchestration    | Git push, deploy scripts, long-running operations             |
| `--skip-permissions-unsafe` | Isolated sandboxes only  | Removes all guardrails (⚠️ use only in disposable containers) |

**Examples:**

```bash theme={null}
# 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"
```

<Warning>
  `--skip-permissions-unsafe` removes all safety checks. Use **only** in isolated environments like Docker
  containers.
</Warning>

## Model IDs

Use any [available model ID](/models) with `-m, --model` or `--spec-model`. For custom models, see [Bring Your Own Key (BYOK)](/cli/byok/overview).

See [Choosing Your Model](/cli/user-guides/choosing-your-model) for detailed guidance on which model to use for different tasks.

## Interactive mode features

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

### Slash commands

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

| Command                | Description                                                    |
| :--------------------- | :------------------------------------------------------------- |
| `/account`             | Open Factory account settings in browser                       |
| `/billing`             | View and manage billing settings                               |
| `/bg-process`          | Manage background processes                                    |
| `/bug [title]`         | Create a bug report with session data and logs                 |
| `/clear`               | Start a new session (alias for `/new`)                         |
| `/commands`            | Manage custom slash commands                                   |
| `/compress [prompt]`   | Compress session and move to new one with summary              |
| `/cost`                | Show token usage statistics                                    |
| `/create-skill`        | Create a reusable skill from current session                   |
| `/droids`              | Manage custom droids                                           |
| `/missions`            | Enter Mission mode                                             |
| `/favorite`            | Mark current session as a favorite                             |
| `/fork`                | Duplicate current session with all messages into a new session |
| `/generate_blog`       | Generate semantic diff blog post                               |
| `/help`                | Show available slash commands                                  |
| `/hooks`               | Manage lifecycle hooks                                         |
| `/ide`                 | Configure IDE integrations                                     |
| `/install-code-review` | Set up automated code review                                   |
| `/login`               | Sign in to Factory                                             |
| `/logout`              | Sign out of Factory                                            |
| `/mcp`                 | Manage Model Context Protocol servers                          |
| `/mission`             | Open Mission Control                                           |
| `/missions`            | List and select missions to resume                             |
| `/model`               | Switch AI model mid-session                                    |
| `/new`                 | Start a new session                                            |
| `/plugins`             | Manage plugins and marketplaces                                |
| `/quit`                | Exit droid (alias: `exit`, or press Ctrl+C)                    |
| `/readiness-report`    | Generate readiness report                                      |
| `/rename`              | Rename current session                                         |
| `/review`              | Start AI-powered code review workflow                          |
| `/rewind-conversation` | Undo recent changes in the session                             |
| `/sessions`            | List and select previous sessions                              |
| `/settings`            | Configure application settings                                 |
| `/share`               | Share session with organization                                |
| `/skills`              | Manage and invoke skills                                       |
| `/status`              | Show current droid status and configuration                    |
| `/statusline`          | Configure custom status line                                   |
| `/terminal-setup`      | Configure terminal keybindings for Shift+Enter                 |
| `/wrapped`             | Show Droid usage statistics                                    |

For detailed information on slash commands, see the [interactive mode documentation](/cli/getting-started/quickstart#useful-slash-commands).

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

```bash theme={null}
droid mcp add <name> <url> --type http    # Add HTTP server
droid mcp add <name> "<command>"          # Add stdio server
droid mcp remove <name>                   # Remove a server
```

See [MCP Configuration](/cli/configuration/mcp) for the full registry list, CLI options (`--env`, `--header`), configuration files, and how user vs project config layering works.

## Authentication

1. Generate an API key at [app.factory.ai/settings/api-keys](https://app.factory.ai/settings/api-keys)
2. Set the environment variable:

<CodeGroup>
  ```bash macOS/Linux theme={null}
  export FACTORY_API_KEY=fk-...
  ```

  ```powershell Windows (PowerShell) theme={null}
  $env:FACTORY_API_KEY="fk-..."
  ```

  ```cmd Windows (CMD) theme={null}
  set FACTORY_API_KEY=fk-...
  ```
</CodeGroup>

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

<Warning>
  Never commit API keys to source control. Use environment variables or secure secret management.
</Warning>

## Exit codes

| Code | Meaning                       |
| :--- | :---------------------------- |
| `0`  | Success                       |
| `1`  | General runtime error         |
| `2`  | Invalid CLI arguments/options |

## Common workflows

### Code review

```bash theme={null}
# Local review workflow
> /review

# Analysis via exec (non-interactive)
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](/cli/features/code-review) for detailed guidance on review types, workflows, and best practices.

### Testing and debugging

```bash theme={null}
# 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

```bash theme={null}
# Planning
droid exec "Create refactoring plan for auth module"

# Execution
droid exec --auto low --use-spec "Refactor auth module"
```

### CI/CD integration

```yaml theme={null}
# 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
```

## See also

* [Quickstart guide](/cli/getting-started/quickstart) - Getting started with Factory CLI
* [Interactive mode](/cli/getting-started/quickstart) - Shortcuts, input modes, and features
* [Choosing your model](/cli/user-guides/choosing-your-model) - Model selection guidance
* [Settings](/cli/configuration/settings) - Configuration options
* [Custom commands](/cli/configuration/custom-slash-commands) - Create your own shortcuts
* [Custom droids](/cli/configuration/custom-droids) - Build specialized agents
* [Droid Exec overview](/cli/droid-exec/overview) - Detailed automation guide
* [MCP configuration](/cli/configuration/mcp) - External tool integration