> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryreplicas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Connect to workspaces from your terminal.

The Replicas CLI provides SSH access, VS Code integration, and replica management for workspaces.

<Tip>
  **For Coding Agents:** If you're using coding agents like Claude Code, Codex, Cursor, Opencode, or Pi, the CLI is the recommended way to interact with Replicas. Coding agents tend to perform better with bash commands than MCP integrations. The CLI provides the same functionality as the [Replicas MCP](/features/mcp) through familiar command-line operations.
</Tip>

## Installation

```bash theme={null}
curl -fsSL https://tryreplicas.com/install.sh | bash
```

## Authentication

```bash theme={null}
replicas login
```

Opens a browser to authenticate with your Replicas account. If you belong to more than one organization and none is selected yet, it asks which one to make active. An existing selection is kept.

### Connect a Coding Agent Account

To use Codex or Claude Code inside Replicas workspaces, link the relevant OAuth account. Each command opens a browser to complete the provider OAuth flow and uploads the resulting credentials to Replicas. Cursor uses a Cursor API key configured in [Organization → Coding Agents](https://tryreplicas.com/dashboard/agents).

Credentials attach to your personal account by default, which works in every organization you belong to:

```bash theme={null}
replicas codex-auth
replicas claude-auth
```

Organization admins can pass `--org` to share one set of credentials with every member instead:

```bash theme={null}
replicas codex-auth --org
replicas claude-auth --org
```

## Replica Management

These commands let you create, manage, and interact with replicas from your terminal as part of an interactive session.

### List Replicas

```bash theme={null}
replicas list
```

Shows all replicas in your organization with their status, repository, and any associated pull requests.

This command is available in agent mode.

**Options:**

* `-p, --page <page>` - Page number for pagination
* `-l, --limit <limit>` - Number of items per page

### Get Replica Details

```bash theme={null}
replicas get <id>
```

Shows detailed information about a specific replica including:

* Current coding agent (`claude`, `codex`, `cursor`, `opencode`, or `pi`)
* Current git branch
* Git diff statistics (lines added/removed)
* Associated pull requests

If the workspace is sleeping or archived, it will be woken and you'll be prompted to retry in 30-90 seconds.

### Create a Replica

```bash theme={null}
replicas create [name]
```

Creates a new replica workspace with an initial message. If options are not provided, the CLI will prompt interactively.

**Options:**

* `-m, --message <message>` - Initial message/task for the replica
* `-e, --environment <name|id>` - Environment to use. The environment supplies the repository, variables, files, skills, MCPs, and hooks (see [Environments](/features/environments)).
* `-a, --agent <agent>` - Coding agent: `claude`, `codex`, `cursor`, `opencode`, or `pi`

CLI-created workspaces inherit the org's sandbox tier. Per-workspace `small`/`large` sizing is only available via the [Replica API](/features/api) and [Automations](/features/automations).

**Example:**

```bash theme={null}
replicas create my-feature \
  -e frontend \
  -m "Add user authentication with OAuth" \
  -a claude
```

### Send Message to Replica

```bash theme={null}
replicas send <id>
```

Sends a follow-up message to an existing replica.

**Options:**

* `-m, --message <message>` - Message to send
* `-a, --agent <agent>` - Coding agent to use: `claude`, `codex`, `cursor`, `opencode`, or `pi`

### Delete a Replica

```bash theme={null}
replicas delete <id>
```

Deletes a replica workspace.

**Options:**

* `-f, --force` - Skip confirmation prompt

### Read Replica History

```bash theme={null}
replicas read <id>
```

Reads the conversation history of a replica, showing user messages, assistant responses, and tool results.

**Options:**

* `-l, --limit <limit>` - Maximum number of events to return
* `-o, --offset <offset>` - Number of events to skip from the end (for pagination)

The history is paginated from the end (most recent first). Use `--offset` to view older events.

If the workspace is sleeping or archived, it will be woken and you'll be prompted to retry in 30-90 seconds.

### List Repositories

```bash theme={null}
replicas repos
```

Lists all repositories available in your organization.

## Environment Management

Manage [Environments](/features/environments) from the CLI. Use `replicas environment` or the shorter `replicas env` alias.

### List Environments

```bash theme={null}
replicas env list
```

Shows every environment in your organization, including the Global environment, with attached variable, file, skill, and MCP counts.

### Get Environment Details

```bash theme={null}
replicas env get <name|id|global>
```

Shows one environment by name, UUID, or `global`.

### Create an Environment

```bash theme={null}
replicas env create [name]
```

Creates an environment. Without a name or repository flag, the CLI prompts interactively.

**Options:**

* `-d, --description <description>` - Environment description
* `-r, --repository <name|id>` - Repository to bind to the environment
* `--system-prompt <prompt>` - System prompt for agents started in this environment

**Example:**

```bash theme={null}
replicas env create frontend \
  --repository replicas-web \
  --system-prompt "Use pnpm and run frontend tests before finishing."
```

### Edit an Environment

```bash theme={null}
replicas env edit <name|id>
```

Updates environment metadata or its repository binding.

**Options:**

* `-n, --name <name>` - New name
* `-d, --description <description>` - New description
* `-r, --repository <name|id>` - Repository binding; pass an empty string to unbind
* `--system-prompt <prompt>` - System prompt

### Delete an Environment

```bash theme={null}
replicas env delete <name|id>
```

Deletes an environment after confirmation.

**Options:**

* `-f, --force` - Skip confirmation prompt

### Manage Environment Variables

```bash theme={null}
replicas env vars list <env>
replicas env vars set <env> <key> <value>
replicas env vars delete <env> <key-or-id>
```

Values are masked by default when listed. Pass `--reveal` to show full values.

### Manage Environment Files

```bash theme={null}
replicas env files list <env>
replicas env files set <env> <destination-path> --file <local-path>
replicas env files set <env> <destination-path> --content "..."
replicas env files delete <env> <path-or-id>
```

Files are written into new workspaces at the configured destination path.

### Manage Start Hooks

```bash theme={null}
replicas env start-hooks get <env>
replicas env start-hooks save <env> --content "..." | --file <local-path>
replicas env start-hooks test <env> --content "..." | --file <local-path>
replicas env start-hooks repository-hooks <env>
```

Manage environment-level start hooks that run at workspace startup. See [Start Hooks](/features/environments#start-hooks) for the execution model.

* `get` - show the active start hook
* `save` - persist and activate a new version, or clear the active hook with empty content
* `test` - run a hook in an isolated sandbox without saving (streams output live)
* `repository-hooks` - list per-repo start hooks defined in replicas.json / replicas.yaml

## Learnings Management

Agent-mode commands for [Learnings](/features/learnings), durable org knowledge that agents pull on demand. They run inside a workspace and use the local agent configuration. Reads return matching entries immediately; writes create a proposal for human review and take effect only once approved.

```bash theme={null}
replicas learnings read --query "<task description>" [--fresh]
replicas learnings add --name "<name>" --content "<content>" [--trigger "<when to use>"] [--always] [--global]
replicas learnings update <id> [--name ...] [--content ...] [--trigger ...] [--always true|false]
replicas learnings delete <id>
replicas learnings withdraw <proposal-id>
```

* `read` - fetch always-apply plus trigger-matched learnings for the given task query; entries already shown in the same agent session are omitted unless `--fresh` is passed
* `add` - propose a new learning (`--always` for always-apply; otherwise `--trigger` is required; `--global` for org-wide scope)
* `update` - propose changes to an existing learning by id
* `delete` - propose removal of a learning by id
* `withdraw` - withdraw a pending proposal from the current workspace

## Slack Thread Routing

Slack thread commands attach the current Slack thread to a workspace so replies in that thread route to the selected workspace. Agent mode can attach only to the current workspace.

```bash theme={null}
replicas slack thread attach
replicas slack thread switch <workspace-id-or-name>
```

Use `replicas list` to find the target workspace ID before switching.

Both commands default to `SLACK_CHANNEL_ID` and `SLACK_THREAD_TS`. Pass `--channel <id>` and `--thread-ts <ts>` when attaching a different thread. To switch a thread to another workspace, run the command with user authentication outside agent mode.

## Preview Management

Preview commands register ports from a workspace as public URLs. Agent mode commands run inside a workspace and use the local agent configuration. Human mode commands run from your local terminal and target a workspace by ID.

### Create a Preview

```bash theme={null}
replicas preview create <port>
```

Registers a port from the current workspace and prints the public preview URL. This command is available in agent mode.

**Options:**

* `-a, --authenticated` - Require Replicas login cookies before the preview can be accessed. Use this for user-facing frontends, not backend APIs called by frontend code.

### List Previews

```bash theme={null}
replicas preview list
```

Lists active preview URLs for the current workspace in agent mode.

In human mode, pass the workspace ID:

```bash theme={null}
replicas preview list <workspaceId>
```

### Delete a Preview

```bash theme={null}
replicas preview delete <port>
```

Unregisters a preview port from the current workspace. This command is available in agent mode.

### Add a Preview

```bash theme={null}
replicas preview add <workspaceId> --port <port>
```

Registers a preview port for a workspace from human mode.

**Options:**

* `-p, --port <port>` - Port number to preview
* `-a, --authenticated` - Require Replicas login cookies before the preview can be accessed. Use this for user-facing frontends, not backend APIs called by frontend code.

### Remove a Preview

```bash theme={null}
replicas preview remove <workspaceId> --port <port>
```

Unregisters a preview port from a workspace in human mode.

**Options:**

* `-p, --port <port>` - Port number to unregister

## Service Management

Service commands run long-lived processes (dev servers, APIs, daemons) detached from the agent session. Detached services survive the agent's turn ending and workspace sleep/wake, so a server started for a [preview](#preview-management) is still running after the workspace wakes. Available in agent mode only.

### Start a Service

```bash theme={null}
replicas service start <name> "<command>"
```

Starts the command as a detached daemon. Starting an existing name restarts it. Quote the command when it contains shell operators.

**Options:**

* `-d, --cwd <dir>` - Working directory for the service (defaults to the current directory)

### List Services

```bash theme={null}
replicas service list
```

Lists registered services with pid and running/stopped status.

### Service Logs

```bash theme={null}
replicas service logs <name>
```

Prints the last lines of the service log (`~/.replicas/services/<name>.log`).

**Options:**

* `-n, --lines <n>` - Number of lines to print (default 50)

### Stop a Service

```bash theme={null}
replicas service stop <name>
```

Stops the service and its whole process group.

## Computer Use

Drives the workspace's Linux desktop. The live noVNC viewer is automatically published as an authenticated preview on port 6080 at engine startup, so the dashboard's [Desktop tab](/features/workspaces/overview#desktop-tab) is always available without any agent action. Available in agent mode only.

Multiple viewers can watch the same desktop concurrently. Input commands from separate agents are serialized as complete gestures so clicks, typing, scrolling, and drags do not interleave.

### Get the Viewer URL

```bash theme={null}
replicas computer info
```

Prints the live noVNC viewer URL (`https://6080-<hash>.tryreplicas.com/`) for the workspace desktop. Use this when you want to share the live stream with the user out-of-band (e.g. in a Slack reply) — the dashboard already points at the same URL automatically. The viewer accepts `quality` and `compression` query parameters; the dashboard exposes Fast, Balanced, and Crisp presets.

### Session Status

```bash theme={null}
replicas computer status
```

Checks and repairs the desktop bridge, then shows which desktop services are running and the active preview URL.

### Screenshot

```bash theme={null}
replicas computer screenshot <path> [--raw] [--grid [px]]
```

Captures the desktop to a PNG. By default, the image includes Replicas branding for sharing with `replicas media upload`.

Use `--raw` for a 1:1 desktop capture with no padding or branding. Use `--grid` for a 1:1 capture with a coordinate grid; the optional value sets grid spacing in pixels and defaults to 100. Prefer `--grid` when choosing coordinates for `click`, `move`, or `drag`.

### Observe

```bash theme={null}
replicas computer observe <path> [--raw] [--grid [px]]
```

Waits briefly for the screen to stop changing, saves a 1:1 desktop screenshot, and prints JSON context: dimensions, stability, frame/change counts, mouse location, active window title, and visible window titles.

By default, `observe` waits up to 3s for 600ms of visual stability and saves a 100px coordinate-grid screenshot. Use it after clicks, navigation, typing, or page loads when an agent needs the next reliable screen state.

### Browser State

```bash theme={null}
replicas computer browser-state <path> [--full]
```

Waits for a Chrome page to settle, saves its viewport screenshot, and returns a compact native accessibility tree in the same coordinate space. Actionable nodes have document-bound refs such as `[ref=42] button "Save"`. The tree includes roles, accessible names, values, states, visible bounds, and same-target iframe content.

The first capture returns the full tree. Later captures for the same target and document return accessibility changes by default; navigation or reload forces a new full tree and invalidates old refs. Use `--full` to reset the baseline. Prefer this over coordinate planning for Chrome.

Use `replicas computer browser [--snapshot]` to list Chrome tabs or request the compatibility snapshot format.

### Browser Batch

```bash theme={null}
replicas computer browser-batch '[{"action":"fill","ref":17,"value":"hello"},{"action":"click","ref":42}]'
```

Runs up to 100 ordered `click`, `fill`, `key`, `type`, `scroll`, or `wait` actions through one Chrome session. The batch stops at the first failure and reports per-action and total execution time. Use refs from one `browser-state`; after navigation or a document change, capture fresh state before starting another batch.

### Browser Click

```bash theme={null}
replicas computer browser-click --ref <id>
```

Scrolls the referenced node into view and sends trusted mouse input at its current visible bounds. Refs come from `browser-state`. Text matching remains available as a fallback with `browser-click <text>`.

### Browser Fill

```bash theme={null}
replicas computer browser-fill --ref <id> <value>
```

Focuses the referenced field, fills it with trusted browser input, and verifies the resulting value. Select controls use their semantic option value; typed controls such as date, number, and range inputs use their native value setter. Text matching remains available as a fallback with `browser-fill <field> <value>`.

### Browser Input

```bash theme={null}
replicas computer browser-scroll <up|down|left|right> [--ref <id>] [--amount <px>]
replicas computer browser-key <combo>
replicas computer browser-type <text>
```

Sends trusted wheel or keyboard input directly to the selected Chrome target. Use `browser-fill` when setting a known field value; use `browser-key` and `browser-type` for keyboard-driven widgets.

### Browser Wait

```bash theme={null}
replicas computer browser-wait <text>
```

Waits until the active Chrome page matches text in the title, URL, body text, or visible controls. Use `--mode title|url|text|control|any` to narrow where it matches. Prefer this after `browser-click` or `browser-fill` when waiting for web app state.

For browser state and actions, pass `--target-id <id>`, `--title <text>`, `--url <text>`, or `--page <n>` when multiple Chrome tabs are open. Prefer the stable target ID returned by `computer launch chrome` because titles and URLs can change after an action. The matched tab is brought to the foreground before each action, so driving multiple tabs or recording the screen switches which tab is visible.

### Mouse Input

```bash theme={null}
replicas computer click <x> <y>          # left-click at (x, y)
replicas computer move <x> <y>           # move without clicking
replicas computer drag <fx> <fy> <tx> <ty>
replicas computer scroll <up|down|left|right>
```

Mouse coordinates can be pixels (`960 540`) or percentages (`50% 50%`). Percentages resolve against the current display size.

**Click options:** `--button <n>` (1/2/3), `--double`, `--modifiers <ctrl+shift>`
**Scroll options:** `--amount <n>` (default 3), `--x <x>` `--y <y>` (hover before scrolling)

### Keyboard Input

```bash theme={null}
replicas computer type <text>            # literal string into focused field
replicas computer key <combo>            # e.g. Return, Escape, ctrl+l, alt+Left
```

**Type options:** `--delay <ms>` (default 12, \~80 wpm)

### Launch an App

```bash theme={null}
replicas computer launch <chrome|chromium|firefox|terminal> [args...]
```

Pass a URL directly when opening a known page, for example `replicas computer launch chrome http://localhost:3000/`.

Chrome launches return after the requested page is controllable and print its page ID. Carry that ID with `--target-id` into browser snapshots and actions so unrelated tabs cannot steal task context.

### Screen Recording

```bash theme={null}
replicas computer record start <path>    # writes an enhanced 1080p MP4 on stop
replicas computer record stop
```

**Record options:** `--fps <n>` (default 60)

Recordings are post-processed from the desktop action log: clicks, typing, drags, and scrolls stay at normal speed, idle gaps are accelerated, click moments get eased camera zoom, and a synthetic cursor animates between logged mouse positions with natural settling before spaced-out clicks.

`record start` returns after ffmpeg writes the first bytes. `record stop` waits for ffmpeg to finalize before post-processing; a timeout preserves the recording state so stopping can be retried safely.

### End-to-End Example

```bash theme={null}
replicas computer info                               # get the viewer URL to share with the user (optional)
replicas computer launch chrome https://news.ycombinator.com
replicas computer record start /tmp/demo.mp4
replicas computer browser-state /tmp/state.png --title "Hacker News" --full
replicas computer browser-click --ref 42 --title "Hacker News"
replicas computer browser-state /tmp/after.png --title "Hacker News"
replicas computer record stop
replicas media upload /tmp/demo.mp4 --name "Hacker News demo"
```

### Canvas vs `replicas media upload`

Two related surfaces share the workspace VM:

* The [Canvas](/features/workspaces/canvas) at `~/.replicas/canvas/` is the right place for small, in-line artifacts: plans (`.md`), HTML pages, and small images the user should be able to flip through next to the chat. Items are capped at **5MB** per file.
* `replicas media upload` is the right place for screenshots, screen recordings, generated videos, audio clips, and anything large enough that base64-inflating it through the engine on every dashboard fetch would be wasteful. It returns a presigned URL + dashboard deep-link so the recipient can view it inline in chat or follow the link.
* `replicas media upload <file> --name "<name>" --share` additionally creates a revocable public bearer URL for embedding screenshots or video posters in GitHub pull requests. Rotate it with `replicas media share <media-id>` and revoke it with `replicas media revoke <media-id>`.
* Each upload shows a human-readable display name in the dashboard. `--name` is required, one per file in order (e.g. `replicas media upload a.png b.png --name "Before" --name "After"`). Names are normalized to hyphen-case (`my-screenshot`), the backend still addresses media by UUID, and duplicate names get a `-1`, `-2` suffix.

Rule of thumb: if it is an *output the user should read* (a plan, a report, a small rendered page), Canvas. If it is *captured media* (a screenshot, a recording, a generated image), `replicas media upload`.

## Interactive Mode

```bash theme={null}
replicas interact
```

Launches a full terminal UI dashboard for managing workspaces without leaving the command line. You can also use the alias `replicas i`.

Interactive mode provides a multi-panel interface with a workspace sidebar, chat area, diff viewer, and workspace info panel, all navigable with keyboard shortcuts.

### Layout

The interface adapts to your terminal width:

* **Sidebar** (left): Lists all workspaces grouped by repository. Visible when terminal width is at least 60 columns.
* **Chat area** (center): Chat with your coding agents (Claude Code, Codex, Cursor, Opencode, or Pi). Supports multiple chat tabs when a workspace has multiple agents.
* **Info panel** (right): Shows workspace status, git info, preview URLs, associated PRs, and environment configuration. Visible when terminal width is at least 100 columns.
* **Status bar** (bottom): Displays context-sensitive keyboard hints for the currently focused panel.

### Keyboard Shortcuts

Use **Shift+Tab** to cycle focus between panels. Shortcuts change based on which panel is focused:

| Panel        | Shortcut          | Action                                           |
| ------------ | ----------------- | ------------------------------------------------ |
| Sidebar      | `j` / `k`         | Navigate up/down                                 |
| Sidebar      | `Enter`           | Select workspace or toggle group                 |
| Sidebar      | `a`               | Create workspace (when on "+ New workspace" row) |
| Sidebar      | `d`               | Archive workspace (press twice to confirm)       |
| Sidebar      | `w`               | Wake sleeping or archived workspace              |
| Chat tabs    | `←` / `→` / `Tab` | Switch between agent tabs                        |
| Chat history | `j` / `k`         | Scroll messages                                  |
| Chat input   | `Enter`           | Send message                                     |
| Chat input   | `Shift+Enter`     | Insert new line                                  |
| Chat input   | `Tab`             | Toggle plan/build mode                           |
| Diff viewer  | `j` / `k`         | Navigate file list                               |
| Diff viewer  | `Tab`             | Switch between file list and diff content        |
| Info panel   | `j` / `k`         | Navigate items                                   |
| Info panel   | `g` / `G`         | Jump to first/last item                          |
| Info panel   | `Enter`           | Open selected item                               |
| Info panel   | `o`               | Open workspace in web dashboard                  |
| Info panel   | `w`               | Wake sleeping or archived workspace              |
| Any          | `1` / `2`         | Switch between chat and diff view                |
| Any          | `Shift+Tab`       | Cycle focus between panels                       |
| Any          | `Esc`             | Interrupt agent processing                       |
| Any          | `Ctrl+C`          | Quit                                             |

### Chat

Select a workspace from the sidebar and type messages in the chat input to communicate with the coding agent. The chat area displays the full conversation history including user messages, agent responses, and tool results.

When a workspace has multiple agents configured, use the chat tabs to switch between them.

### Plan and Build Modes

Press **Tab** while the chat input is focused to toggle between **build** and **plan** mode:

* **Build mode** (default): The agent can read and write files, run commands, and make changes to your codebase.
* **Plan mode**: The agent operates in read-only mode, useful for exploring code, discussing architecture, or planning changes before committing to them.

### Diff Viewer

Press **2** to switch from the chat view to the diff viewer, which shows code changes made by the agent. Press **1** to return to chat. You can also open diffs for specific repositories from the info panel.

## Automation Management

Manage [Automations](/features/automations) directly from the CLI. All commands support both flag-based (scriptable) and interactive input modes. Use the alias `auto` for brevity (e.g. `replicas auto list`).

### List Automations

```bash theme={null}
replicas automation list
```

Shows all automations in your organization with their status, triggers, and schedule.

**Options:**

* `-p, --page <page>` - Page number for pagination
* `-l, --limit <limit>` - Number of items per page
* `--owner <org|user|all>` - Show org automations, your personal automations, or both
* `--trigger-type <type>` - Only automations with a trigger of this type: `cron`, `github`, `gitlab`, `slack`, `sentry`, `custom`
* `--enabled <true|false>` - Only enabled or only disabled automations
* `--search <search>` - Case-insensitive substring match on the name

Any [GitHub checks](/features/automations#github-checks) an automation reports on are listed too, so you can see which ones are already configured.

### Get Automation Details

```bash theme={null}
replicas automation get <id>
```

Shows detailed information about a specific automation including triggers, prompt, environment, cron schedule, and lifecycle policy.

### Create an Automation

```bash theme={null}
replicas automation create [name]
```

Creates a new automation. If options are not provided, the CLI will prompt interactively.

**Options:**

* `--prompt <prompt>` - Prompt the agent will receive
* `--environment <name|id>` - Environment the automation runs in (see [Environments](/features/environments))
* `--trigger-cron <expression>` - Cron schedule (e.g. `"0 9 * * 1-5"`)
* `--trigger-cron-timezone <tz>` - Timezone for cron trigger (default: UTC)
* `--trigger-github <event>` - GitHub event trigger (e.g. `pull_request.opened`)
* `--trigger-github-repos <repos>` - Comma-separated repository names to filter GitHub triggers
* `--trigger-github-exclude-users <users>` - Comma-separated GitHub usernames whose events should not fire the trigger
* `--trigger-gitlab <event>` - GitLab event trigger (e.g. `merge_request.opened`)
* `--trigger-gitlab-repos <repos>` - Comma-separated project names to filter GitLab triggers
* `--trigger-gitlab-exclude-users <users>` - Comma-separated GitLab usernames whose events should not fire the trigger
* `--github-checks <names>` - Comma-separated [GitHub check](/features/automations#github-checks) names to report the run's verdict on (requires a PR opened/updated trigger)
* `--lifecycle <policy>` - Workspace lifecycle: `default`, `archive_when_done`, or `sleep_when_done`
* `--sleep-when-done` - Shortcut for `--lifecycle sleep_when_done`
* `--auto-stop-minutes <minutes>` - Inactivity timeout for the `default` lifecycle policy
* `--pr-followups` - Allow follow-up actions on matching PRs
* `--agent-provider <provider>` - Coding agent to use: `claude`, `codex`, `cursor`, `opencode`, or `pi` (or `none` to inherit org default)
* `--model <model>` - Model identifier (must be valid for `--agent-provider`; pass `none` to clear)
* `--thinking-level <level>` - Thinking/reasoning level: `low`, `medium`, `high`, `xhigh`, `max`, Codex-only `ultra`, or Claude Code-only `ultracode` (or `none` to clear)
* `--plan-mode` - Run automation messages in plan mode
* `--goal-mode` - Set automation messages as Codex goals
* `--fast-mode` - Run automation messages in fast mode
* `--personal` - Create a personal automation owned by you
* `--disabled` - Create the automation disabled

**Example:**

```bash theme={null}
replicas automation create "nightly-audit" \
  --prompt "Run the test suite and report failures" \
  --environment "my-repo" \
  --trigger-cron "0 3 * * *" \
  --trigger-cron-timezone "America/New_York" \
  --sleep-when-done
```

To ignore bot or user activity on code-host triggers:

```bash theme={null}
replicas automation create "pr-review" \
  --prompt "Review this PR" \
  --environment "my-repo" \
  --trigger-github pull_request.opened \
  --trigger-github-exclude-users "dependabot[bot],renovate[bot]"
```

### Edit an Automation

```bash theme={null}
replicas automation edit <id>
```

Updates an existing automation. Without flags, opens interactive mode pre-filled with current values.

**Options:**

* `--name <name>` - New name
* `--prompt <prompt>` - New prompt
* `--enabled <true|false>` - Enable or disable
* `--trigger-cron <expression>` - Replace triggers with a cron trigger
* `--trigger-cron-timezone <tz>` - Timezone for the cron trigger
* `--trigger-github <event>` - Replace triggers with a GitHub event trigger
* `--trigger-github-repos <repos>` - Comma-separated repository names to filter GitHub triggers
* `--trigger-github-exclude-users <users>` - Comma-separated GitHub usernames to exclude. Without `--trigger-github`, updates existing GitHub triggers. Pass an empty string (`""`) to clear existing GitHub exclusions.
* `--trigger-gitlab <event>` - Replace triggers with a GitLab event trigger
* `--trigger-gitlab-repos <repos>` - Comma-separated project names to filter GitLab triggers
* `--trigger-gitlab-exclude-users <users>` - Comma-separated GitLab usernames to exclude. Without `--trigger-gitlab`, updates existing GitLab triggers. Pass an empty string (`""`) to clear existing GitLab exclusions.
* `--github-checks <names>` - Comma-separated [GitHub check](/features/automations#github-checks) names to report the run's verdict on. Replaces the current list; pass an empty string (`""`) to stop creating checks.
* `--add-github-checks <names>` - Comma-separated check names to add, keeping the ones already configured. Use this when adding checks across existing automations, so a name someone else configured is never dropped.
* `--environment <name|id>` - Move the automation to a different environment
* `--lifecycle <policy>` - Workspace lifecycle: `default`, `archive_when_done`, or `sleep_when_done`
* `--sleep-when-done` - Shortcut for `--lifecycle sleep_when_done`
* `--auto-stop-minutes <minutes>` - Inactivity timeout for the `default` lifecycle policy
* `--pr-followups <true|false>` - Toggle whether matching PRs can receive follow-up actions
* `--agent-provider <provider>` - Coding agent to use: `claude`, `codex`, `cursor`, `opencode`, or `pi` (or `none` to inherit org default)
* `--model <model>` - Model identifier (must be valid for `--agent-provider`; pass `none` to clear)
* `--thinking-level <level>` - Thinking/reasoning level: `low`, `medium`, `high`, `xhigh`, `max`, Codex-only `ultra`, or Claude Code-only `ultracode` (or `none` to clear)
* `--plan-mode <true|false>` - Enable or disable plan mode
* `--goal-mode <true|false>` - Enable or disable Codex goal mode
* `--fast-mode <true|false>` - Enable or disable fast mode

### Run an Automation

```bash theme={null}
replicas automation run <id>
```

Manually triggers an automation. Only automations with a cron trigger can be run manually.

### Delete an Automation

```bash theme={null}
replicas automation delete <id>
```

Deletes an automation.

**Options:**

* `-f, --force` - Skip confirmation prompt

### Report a GitHub Check

```bash theme={null}
replicas automation check <checkRunId> --token <token> --conclusion success --title "No duplicated logic"
```

Reports this run's verdict on one of its [GitHub checks](/features/automations#github-checks). Run from inside an automation workspace, which is what identifies the run that owns the check.

**Options:**

* `--token <token>` - Ownership token for this check, copied from the prompt (required)
* `--conclusion <conclusion>` - `success` or `failure` (required)
* `--title <title>` - One-line verdict shown on the check (required)
* `--summary <summary>` - What was checked and why it passed or failed

Prints a notice instead of writing when a newer run of the same automation has taken the check over. That is expected, not an error.

## Workspace Connection

### Connect via SSH

```bash theme={null}
replicas connect <workspace-name>
```

Opens an interactive SSH session to the workspace.

### Open in VS Code

```bash theme={null}
replicas code <workspace-name>
```

Opens the workspace in VS Code via Remote SSH.

### Switch Organization

```bash theme={null}
replicas org        # show the active organization, account, and your role
replicas org switch # change it
```

The active organization is where org-scoped writes land, including credentials saved by [`claude-auth`](/features/coding-agents/claude-code) and [`codex-auth`](/features/coding-agents/codex). It persists until you change it.

<Note>
  `replicas claude-auth` and `replicas codex-auth` save to your personal account unless you pass `--org`, which shares the credentials with every member of the active organization and requires the admin role. Both commands show your account, role, credential, and destination for confirmation before opening your browser, and confirm where the credentials landed on success. Pass `-y, --yes` to skip the confirmation in scripts. Personal credentials take priority over organization defaults.
</Note>

## Configuration

CLI configuration is driven by `replicas.json` or `replicas.yaml` in your repository. Both formats use the same schema — YAML is especially useful for multiline system prompts.

See [Repository Configuration](/features/workspaces/repository-configuration) for the full schema.