droid

droid [options]droid exec [options] [prompt]droid subcommand [options]

droid is Factory.ai's coding agent for the terminal. It runs in two shapes: an interactive REPL, and droid exec, which takes a prompt, works until the task is done, and exits, which is what makes it usable from scripts and CI.Permissions are graduated rather than all-or-nothing. Without --auto the agent is effectively read-only: it can inspect the codebase and produce a plan, but not change it. --auto low permits file edits and little else. --auto medium additionally auto-approves reversible actions such as installing dependencies and running tests, while still asking before anything risky. --auto high hands over everything, including commits and pushes. The sensible progression is to start low on an unfamiliar repository, see what the agent actually proposes to touch, and raise the level once you trust it.--use-spec inverts the flow: the agent writes a specification first and only then implements against it, optionally using a stronger model for the planning step via --spec-model. --mission goes further, orchestrating several agents and splitting work between worker and validator roles.Custom sub-agents ("Custom Droids") are markdown files with YAML frontmatter under `.factory/droids/`, so a repository can ship its own specialised agents alongside its code.

.factory/droids/

Custom sub-agent definitions, as markdown files with YAML frontmatter.

droid

Start the interactive REPL.

Run a task non-interactively. This is the scripting entry point.

Search across local sessions: messages, documents, and tool results.

Manage Model Context Protocol servers.

Install, uninstall, and update plugins, and manage marketplaces.

Register and manage Bring-Your-Own-Machine computers.

Run the Factory daemon server.

Update the CLI to the latest version.

--auto LEVEL

Autonomy level: low, medium, or high. Omitting it leaves the agent read-only.

Read the prompt from a file.

Select a specific model.

Override reasoning effort: `off`, `none`, `low`, `medium`, or `high`.

Output format: `text` (default), `json`, `stream-json`, or `stream-jsonrpc`.

Input format. `stream-jsonrpc` enables multi-turn sessions.

Continue an existing session.

Fork an existing session into a new copy and resume that.

Run the session in an isolated git worktree, leaving the working tree untouched.

Execute from a specific working directory.

Start in specification mode: plan before executing.

Use a different model or reasoning effort for the planning phase.

Force-enable tools, disable them for this run, or print the available ones and exit.

Run in mission mode, orchestrating multiple agents. --worker-model and --validator-model, with their matching reasoning-effort flags, control the sub-agents.

Append custom instructions to the system prompt.

Attach a session tag. Repeatable.

Skip every permission prompt. Dangerous; see CAVEATS.

Print the version, or show help.

--skip-permissions-unsafe disables every safety check, including the confirmations before destructive commands. It is meant for throwaway containers, and running it on a machine you care about, or with live credentials in the environment, is exactly the mistake its name warns about.--auto high can rewrite history, force-push, and run arbitrary commands without asking. Combining it with a session that has push access to a shared branch is a real risk, and --worktree is the cheap mitigation, since it isolates the agent's changes from your working tree.The tool needs a Factory.ai account, and prompts, code context, and tool results are sent to Factory's service and to the underlying model providers. That has obvious implications for proprietary code and is worth checking against your organisation's policy before pointing it at a private repository.

droid is the CLI of Factory.ai, a company building agent tooling aimed at enterprise engineering teams rather than individual developers, which shows in its emphasis on session management, worktree isolation, multi-agent missions, and model choice. It is one of a crowded field of terminal coding agents that appeared from 2024 onward, alongside Claude Code, Codex CLI, Aider, and others.

claude(1), codex(1), aider(1), opencode(1), gemini(1)

Homepage · Documentation