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-1-20250805
-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)droid exec -o json "document API"
--input-format <format>Input format (stream-json for multi-turn)droid exec --input-format stream-json -o stream-json
-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
--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>Override delegation service endpointdroid exec --delegation-url https://custom.factory.ai
-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-sonnet-4-5-20250929Claude Sonnet 4.5Yesoff
gpt-5-codexGPT-5 Codex (Auto)Nonone
gpt-5-2025-08-07GPT-5Yesmedium
claude-opus-4-1-20250805Claude Opus 4.1Yesoff
claude-haiku-4-5-20251001Claude Haiku 4.5Yesoff
glm-4.6Droid Core (GLM-4.6)Nonone
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.

​
Slash commands (interactive mode)

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)
/compress [prompt]Compress session and move to new one with summary
/costShow token usage statistics
/helpShow available slash commands
/mcpManage Model Context Protocol servers
/modelSwitch AI model mid-session
/newStart a new session
/sessionsList and select previous sessions
/settingsConfigure application settings
/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 command manages Model Context Protocol servers: 
/mcp list                    # List all configured servers
/mcp add <name> <command>    # Add stdio-based server
/mcp add --type http <url>   # Add HTTP-based server
/mcp remove <name>           # Remove a server
/mcp get <name>              # Show server details
/mcp enable <name>           # Enable a disabled server
/mcp disable <name>          # Temporarily disable a server
See MCP Configuration for complete documentation.

​
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

# Analysis only
droid exec "Review this PR for security issues"

# With modifications
droid exec --auto low "Review code and add missing type hints"

​
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