Skip to content

docs(cli): comprehensive CLI documentation update #1132

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
factory-davidgu merged 1 commit into from
May 19, 2026
Merged

docs(cli): comprehensive CLI documentation update #1132

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions docs/cli/configuration/custom-droids.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,22 @@ Custom droids live as `.md` files under either your project's `.factory/droids/`

Changes to droid files are picked up on the next menu open or Task tool invocation.

### AI-assisted droid generation

Don't want to write the system prompt by hand? Droid ships with a built-in `GenerateDroid` tool that creates a complete custom droid configuration from a short description. Just describe what the droid should do — e.g. "review pull requests for security issues, focused on Node.js services" — and Droid will:

- Suggest a normalized `name`
- Draft a focused system prompt
- Pick a sensible `tools` set and `model`
- Save the resulting `.md` file to your chosen project or personal location

You can invoke it two ways:

- From the **Create a new Droid** wizard in `/droids`, choose the AI-generated prompt option and provide a description.
- Ask the assistant directly: "Use `GenerateDroid` to create a droid that…" and pass `location: project` or `location: personal` to control where the file is saved.

This is the fastest way to scaffold a new droid; you can always open the generated `.md` file and tweak the prompt, model, or tool list afterwards.

---

## 4 · Configuration
Expand Down
24 changes: 24 additions & 0 deletions docs/cli/configuration/mcp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -298,3 +298,27 @@ For **http** servers:

Droid automatically reloads when the configuration file changes, so servers are immediately available after adding them.

## Enterprise MCP policy

Organizations can centrally control which MCP servers are allowed via the `mcpPolicy` setting in org-managed settings. This lets administrators restrict MCP access at the org level so users can only connect to vetted servers.

| Field | Type | Description |
| :---- | :--- | :---------- |
| `enabled` | `boolean` | Toggle MCP support on or off for the org. When `false`, all MCP servers are blocked. |
| `allowlist` | `string[]` | Optional list of server names users are permitted to enable. When set, any server not on the list is blocked. |

**Example org-managed settings:**

```json
{
"mcpPolicy": {
"enabled": true,
"allowlist": ["linear", "sentry", "notion"]
}
}
```

<Note>
`mcpPolicy` is an enterprise/org-level setting and is enforced through managed settings — individual users cannot override it. Servers blocked by policy will not appear in the `/mcp` registry browser or load from `mcp.json`.
</Note>

26 changes: 26 additions & 0 deletions docs/cli/configuration/plugins.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -286,6 +286,32 @@ For organizations that need centralized control over approved plugins, see [Ente

Droid is compatible with plugins built for Claude Code. If you find a Claude Code plugin you'd like to use, you can install it directly - the plugin format is interoperable. See the [Claude Code plugins documentation](https://code.claude.com/docs/en/plugins) for more details.

## CLI command reference

Quick reference for the `droid plugin` subcommands. All commands accept `--scope user|project` (alias `-s`) to control where the plugin is installed; omit the flag to be prompted.

| Command | Purpose | Example |
| :------ | :------ | :------ |
| `droid plugin install <plugin@marketplace>` | Install a plugin from a registered marketplace. Alias: `droid plugin i`. | `droid plugin install droid-control@factory-plugins --scope project` |
| `droid plugin uninstall <plugin@marketplace>` | Remove an installed plugin. Alias: `droid plugin remove`. | `droid plugin uninstall droid-control@factory-plugins` |
| `droid plugin update [plugin@marketplace]` | Update a specific plugin, or all plugins when called without an argument. | `droid plugin update droid-control@factory-plugins` |
| `droid plugin list` | List installed plugins, optionally scoped. | `droid plugin list --scope user` |
| `droid plugin marketplace` | Manage marketplaces (`add`, `remove`, `list`, `update`). | `droid plugin marketplace add https://github.com/Factory-AI/factory-plugins` |

**Common workflows:**

```bash
droid plugin marketplace add https://github.com/Factory-AI/factory-plugins
droid plugin install droid-control@factory-plugins
droid plugin list
droid plugin update
droid plugin uninstall droid-control@factory-plugins
```

<Tip>
Prefer the interactive `/plugins` UI for browsing and one-off installs. Use the CLI when scripting onboarding, CI setup, or shared dotfiles.
</Tip>

## Next steps

<CardGroup cols={2}>
Expand Down
95 changes: 95 additions & 0 deletions docs/cli/configuration/settings.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,6 +154,101 @@ Commands that appear in both lists default to the denylist behavior. Any command

Review and update these arrays periodically to match your workflow and security posture, especially when sharing configurations across teams.

## Session defaults

Defaults applied when a new session starts. See also `sessionDefaultSettings.interactionMode` and `sessionDefaultSettings.autonomyLevel` in the table above.

| Setting | Type | Options | Default | Description |
| ------------------------------------------------ | ------ | ---------------------------------------- | -------------- | ---------------------------------------------------------- |
| `sessionDefaultSettings.specModeModel` | string | Any [available model ID](/models) | Inherits model | Override the model used when sessions start in Spec Mode. |
| `sessionDefaultSettings.specModeReasoningEffort` | string | `off`, `none`, `low`, `medium`, `high` | Model default | Reasoning effort applied to the spec model. |

## Display and UI

Tune how droid renders content in the terminal.

| Setting | Type | Options | Default | Description |
| -------------------------- | --------- | -------------------------------------- | ------------ | -------------------------------------------------------------------------------------------- |
| `toolResultDisplay` | string | `expanded`, `compact` | `expanded` | How tool results are rendered in the transcript. |
| `showTokenUsageIndicator` | boolean | `true`, `false` | `false` | Show the live token usage indicator at the bottom of the input. |
| `logoAnimation` | string | `once`, `always`, `off` | `once` | Animate the droid logo on startup. |
| `theme` | string | Theme ID (see `/themes`) | System theme | Color theme used by the TUI. |
| `overrideTerminalColors` | boolean | `true`, `false` | `false` | Force droid's theme to override the terminal's color scheme. |
| `nerdFont` | boolean | `true`, `false` | `false` | Enable Nerd Font glyphs in the UI (requires a Nerd Font in your terminal). |

## Additional sound and notification settings

Extends the [Sound notifications](#sound-notifications) section with toggles for the bell, per-event focus modes, and subagent activity.

| Setting | Type | Options | Default | Description |
| -------------------------------- | ------- | -------------------------------------- | --------- | -------------------------------------------------------------------- |
| `subagentSounds` | string | `on`, `off` | `off` | Play sounds for subagent lifecycle events (start, complete, error). |

## Mission settings

Configure [Missions](/cli/features/missions) — multi-agent orchestration runs.

| Setting | Type | Options | Default | Description |
| ---------------------------------------------------- | ------- | ---------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------- |
| `missionModelSettings.workerModel` | string | Any [available model ID](/models) | Inherits | Default model used by mission worker subagents. |
| `missionModelSettings.workerReasoningEffort` | string | `off`, `none`, `low`, `medium`, `high` | Model default | Reasoning effort for mission workers. |
| `missionModelSettings.validationWorkerModel` | string | Any [available model ID](/models) | Inherits | Model used by mission validators (scrutiny / user-testing workers). |
| `missionModelSettings.validationWorkerReasoningEffort` | string | `off`, `none`, `low`, `medium`, `high` | Model default | Reasoning effort for validation workers. |
| `missionModelSettings.skipScrutiny` | boolean | `true`, `false` | `false` | Skip scrutiny validation milestones during missions. |
| `missionModelSettings.skipUserTesting` | boolean | `true`, `false` | `false` | Skip user-testing validation milestones during missions. |
| `missionOrchestratorModel` | string | Any [available model ID](/models) | Inherits | Model used by the mission orchestrator. |
| `missionOrchestratorReasoningEffort` | string | `off`, `none`, `low`, `medium`, `high` | Model default | Reasoning effort for the mission orchestrator. |
| `keepSystemAwakeDuringMissions` | boolean | `true`, `false` | `true` | Prevent the OS from sleeping while a mission is running. |

## Context and compaction

Controls when and how droid compacts the conversation to stay within the model's context window.

| Setting | Type | Options | Default | Description |
| -------------------------------- | ------- | ---------------------------------------- | --------------- | ------------------------------------------------------------------------------------------ |
| `compactionTokenLimit` | number | Token count | Model-dependent | Token threshold that triggers automatic compaction of the current session. |
| `compactionTokenLimitPerModel` | object | `{ "<modelId>": number }` map | `{}` | Per-model overrides for `compactionTokenLimit`. |
| `compactionModelMode` | string | `same`, `<modelId>` | `same` | Which model performs compaction: `same` uses the current session model, or specify a model ID. |

## Spec mode settings

Controls the persistent spec store created by Spec Mode.

| Setting | Type | Options | Default | Description |
| ----------------- | ------- | ------------------------ | ----------------------------- | -------------------------------------------------------------------------- |
| `specSaveDir` | string | Directory path | `~/.factory/specs` | Directory where saved specs are written. Supports `~` expansion. |

## Infrastructure

System-level settings for status line, worktrees, and request timeouts.

| Setting | Type | Options | Default | Description |
| ---------------------- | ------- | ------------------------------------------------------------------------------------------------ | --------------------- | ---------------------------------------------------------------------------------------------------- |
| `statusLine` | object | `{ "command": string, "padding"?: number, "maxRows"?: number }` | unset | Custom status line configuration. The `command` is executed and its stdout rendered above the input. Configure interactively with `/statusline`. |
| `worktreeDirectory` | string | Directory path | `~/.factory/worktrees` | Default parent directory for git worktrees created with `--worktree` / `-w`. |
| `llmRequestTimeout` | number | Milliseconds | Product default | Timeout for individual LLM requests before they are aborted. |

## Enterprise and org-level settings

<Note>
**Enterprise / Org-level.** The settings below are typically managed by an organization administrator and pushed to members through the Factory web app or a managed `settings.json`. Individual users generally do not set these directly.
</Note>

| Setting | Type | Options | Default | Description |
| ------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `maxAutonomyLevel` | string | `off`, `low`, `medium`, `high` | `high` | **Enterprise.** Maximum [Autonomy Level](/cli/user-guides/auto-run) any session may use. Higher levels selected by users are clamped. |
| `modelPolicy` | object | `{ "allowedModelIds"?: string[], "blockedModelIds"?: string[], "allowCustomModels"?: boolean, "allowedBaseUrls"?: string[] }` | unset | **Enterprise.** Restrict which models members can select, control whether custom models are permitted, and allowlist base URLs for custom model providers. |
| `mcpPolicy` | object | `{ "enabled"?: boolean, "allowlist"?: string[] }` | unset | **Enterprise.** Control whether MCP servers can run and which servers are permitted. See [MCP](/cli/configuration/mcp). |
| `missionPolicy` | object | `{ "restrictedAccess"?: boolean, "allowedUserIds"?: string[] }` | unset | **Enterprise.** Restrict who can launch [Missions](/cli/features/missions). |
| `networkPolicy` | object | `{ "allowedIps": string[] }` | unset | **Enterprise.** Restrict outbound network access from droid sessions to the specified IPs or CIDR ranges in `allowedIps`. |
| `sandbox` | object | `{ "enabled"?: boolean, "mode"?: string, "filesystem"?: object, "network"?: object }` | unset | **Enterprise.** Sandbox configuration controlling filesystem and network isolation for tool execution. |
| `restrictMemberVisibility` | boolean | `true`, `false` | `false` | **Org-level.** Hide other org members from non-admin users. |
| `restrictApiKeyCreationToManagers` | boolean | `true`, `false` | `false` | **Org-level.** Only org managers may create API keys. |
| `sessionRetentionDays` | number | `14`–`365` | Org default | **Org-level.** How long synced session history is retained before deletion. |
| `wikiCloudSync` | boolean | `true`, `false` | `true` | **Org-level.** Sync generated [Wiki](/cli/features/wiki/overview) content to Factory cloud. |
| `managedComputersEnabled` | boolean | `true`, `false` | `false` | **Enterprise.** Enable Factory-managed remote computers for the org. |
| `byomComputersEnabled` | boolean | `true`, `false` | `false` | **Enterprise.** Allow members to register their own machines via `droid computer register` (BYOM). |

## Example configuration

```json
Expand Down
Loading
Loading