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.

​
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)
/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