Skip to main content

​
Installation

curl -fsSL https://app.factory.ai/cli | sh
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

CommandDescriptionExample
droidStart interactive REPLdroid
droid "query"Start REPL with initial promptdroid "explain this project"
droid exec "query"Execute task without interactive modedroid exec "summarize src/auth"
droid exec -f prompt.mdLoad prompt from filedroid exec -f .factory/prompts/review.md
cat file | droid execProcess piped contentgit diff | droid exec "draft release notes"
droid exec -s <id> "query"Resume existing session in exec modedroid exec -s session-123 "continue"
droid exec --list-toolsList available tools, then exitdroid exec --list-tools

​
CLI flags

Customize droid’s behavior with command-line flags:
FlagDescriptionExample
-f, --file <path>Read prompt from a filedroid exec -f plan.md
-m, --model <id>Select a specific model (see model IDs)droid exec -m claude-opus-4-5-20251101
-s, --session-id <id>Continue an existing sessiondroid exec -s session-abc123
--auto <level>Set autonomy level (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 rundroid exec --disabled-tools execute-cli
--list-toolsPrint available tools and exitdroid 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-json, 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 for specification planningdroid exec --spec-model claude-sonnet-4-5-20250929
--spec-reasoning-effort <level>Override reasoning effort for spec modedroid exec --use-spec --spec-reasoning-effort high
--use-specStart in specification mode (plan before executing)droid exec --use-spec "add user profiles"
--skip-permissions-unsafeSkip all permission prompts (⚠️ use with extreme caution)droid exec --skip-permissions-unsafe
--cwd <path>Execute from a specific working directorydroid exec --cwd ../service "run tests"
--delegation-url <url>URL for delegated sessions (Slack thread or Linear issue)droid exec --delegation-url <slack-or-linear-url>
-v, --versionDisplay CLI versiondroid -v
-h, --helpShow help informationdroid --help
Use --output-format json for scripting and automation, allowing you to parse droid’s responses programmatically.

​
Autonomy levels

droid exec uses tiered autonomy to control what operations the agent can perform. Only raise access when the environment is safe.
LevelIntended forNotable allowances
(default)Read-only reconnaissanceFile reads, git diffs, environment inspection
--auto lowSafe editsCreate/edit files, run formatters, non-destructive commands
--auto mediumLocal developmentInstall dependencies, build/test, local git commits
--auto highCI/CD & orchestrationGit push, deploy scripts, long-running operations
--skip-permissions-unsafeIsolated sandboxes onlyRemoves all guardrails (⚠️ use only in disposable containers)
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"
--skip-permissions-unsafe removes all safety checks. Use only in isolated environments like Docker containers.

​
Available models

Model IDNameReasoning supportDefault reasoning
claude-opus-4-5-20251101Claude Opus 4.5 (default)Yes (Off/Low/Medium/High)off
gpt-5.1-codex-maxGPT-5.1-Codex-MaxYes (Low/Medium/High/Extra High)medium
gpt-5.1-codexGPT-5.1-CodexYes (Low/Medium/High)medium
gpt-5.1GPT-5.1Yes (None/Low/Medium/High)none
gpt-5.2GPT-5.2Yes (Low/Medium/High)low
claude-sonnet-4-5-20250929Claude Sonnet 4.5Yes (Off/Low/Medium/High)off
claude-haiku-4-5-20251001Claude Haiku 4.5Yes (Off/Low/Medium/High)off
gemini-3-pro-previewGemini 3 ProYes (Low/High)high
gemini-3-flash-previewGemini 3 FlashYes (Minimal/Low/Medium/High)high
glm-4.6Droid Core (GLM-4.6)None onlynone
Custom models configured via BYOK use the format: custom:<alias> See 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:
CommandDescription
/accountOpen Factory account settings in browser
/billingView and manage billing settings
/bug [title]Create a bug report with session data and logs
/clearStart a new session (alias for /new)
/commandsManage custom slash commands
/compress [prompt]Compress session and move to new one with summary
/costShow token usage statistics
/droidsManage custom droids
/favoriteMark current session as a favorite
/helpShow available slash commands
/hooksManage lifecycle hooks
/ideConfigure IDE integrations
/loginSign in to Factory
/logoutSign out of Factory
/mcpManage Model Context Protocol servers
/modelSwitch AI model mid-session
/newStart a new session
/quitExit droid (alias: exit, or press Ctrl+C)
/readiness-reportGenerate readiness report
/reviewStart AI-powered code review workflow
/rewind-conversationUndo recent changes in the session
/sessionsList and select previous sessions
/settingsConfigure application settings
/skillsManage and invoke skills
/statusShow current droid status and configuration
/terminal-setupConfigure terminal keybindings for Shift+Enter
For detailed information on slash commands, see the interactive mode documentation.

​
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 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. Generate an API key at app.factory.ai/settings/api-keys
  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.
Never commit API keys to source control. Use environment variables or secure secret management.

​
Exit codes

CodeMeaning
0Success
1General runtime error
2Invalid CLI arguments/options

​
Common workflows

​
Code review

# Interactive 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 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"

​
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

​
See also