CLI - Replicas Docs

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

For Coding Agents: If you’re using coding agents like Claude Code, Codex, Cursor, or Opencode, 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 through familiar command-line operations.

Installation

curl -fsSL https://tryreplicas.com/install.sh | bash

Authentication

replicas login

Opens a browser to authenticate with your Replicas account.

Connect a Coding Agent Account

To use Codex or Claude Code inside Replicas workspaces, link the relevant OAuth account to your organization. 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 Coding Agents settings.

replicas codex-auth
replicas claude-auth

Pass --user to attach the credentials to your personal account instead of the organization:

replicas codex-auth --user
replicas claude-auth --user

Replica Management

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

List Replicas

replicas list

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

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

Get Replica Details

replicas get <id>

Shows detailed information about a specific replica including:

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

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

Create a Replica

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).
-a, --agent <agent> - Coding agent: claude, codex, cursor, or opencode

CLI-created workspaces inherit the org’s sandbox tier. Per-workspace small/large sizing is only available via the Replica API and Automations. Example:

replicas create my-feature \
  -e frontend \
  -m "Add user authentication with OAuth" \
  -a claude

Send Message to Replica

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, or opencode

Delete a Replica

replicas delete <id>

Deletes a replica workspace. Options:

-f, --force - Skip confirmation prompt

Read Replica History

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, it will be woken and you’ll be prompted to retry in 30-90 seconds.

List Repositories

replicas repos

Lists all repositories available in your organization.

Environment Management

Manage Environments from the CLI. Use replicas environment or the shorter replicas env alias.

List Environments

replicas env list

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

Get Environment Details

replicas env get <name|id|global>

Shows one environment by name, UUID, or global.

Create an Environment

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:

replicas env create frontend \
  --repository replicas-web \
  --system-prompt "Use pnpm and run frontend tests before finishing."

Edit an Environment

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

replicas env delete <name|id>

Deletes an environment after confirmation. Options:

-f, --force - Skip confirmation prompt

Manage Environment Variables

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

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

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 for the execution model.

get - show the active start hook
save - persist and activate a new version
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

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

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

replicas preview list

Lists active preview URLs for the current workspace in agent mode. In human mode, pass the workspace ID:

replicas preview list <workspaceId>

Delete a Preview

replicas preview delete <port>

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

Add a Preview

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

replicas preview remove <workspaceId> --port <port>

Unregisters a preview port from a workspace in human mode. Options:

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

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 is always available without any agent action. Available in agent mode only.

Get the Viewer URL

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.

Session Status

replicas computer status

Shows which desktop services are running and the active preview URL.

Screenshot

replicas computer screenshot <path>

Captures the desktop to a PNG with Replicas branding (gradient background, rounded corners, drop shadow). Pair with replicas media upload to share it.

Mouse Input

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>

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

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

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/.

Screen Recording

replicas computer record start <path>    # writes 1080p MP4
replicas computer record stop

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

End-to-End Example

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
sleep 5
replicas computer scroll down --amount 5
replicas computer screenshot /tmp/state.png
replicas computer record stop
replicas media upload /tmp/demo.mp4

Canvas vs `replicas media upload`

Two related surfaces share the workspace VM:

The 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.

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

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, or Opencode). 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`	Delete workspace (press twice to confirm)
Sidebar	`w`	Wake sleeping 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 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 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

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

Get Automation Details

replicas automation get <id>

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

Create an Automation

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)
--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-gitlab <event> - GitLab event trigger (e.g. merge_request.opened)
--trigger-gitlab-repos <repos> - Comma-separated project names to filter GitLab triggers
--pr-followups - Allow follow-up actions on matching PRs
--agent-provider <provider> - Coding agent to use: claude, codex, cursor, or opencode (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, max (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:

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"

Edit an Automation

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-gitlab <event> - Replace triggers with a GitLab event trigger
--trigger-gitlab-repos <repos> - Comma-separated project names to filter GitLab triggers
--environment <name|id> - Move the automation to a different environment
--pr-followups <true|false> - Toggle whether matching PRs can receive follow-up actions
--agent-provider <provider> - Coding agent to use: claude, codex, cursor, or opencode (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, max (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

replicas automation run <id>

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

Delete an Automation

replicas automation delete <id>

Deletes an automation. Options:

-f, --force - Skip confirmation prompt

Workspace Connection

Connect via SSH

replicas connect <workspace-name>

Opens an interactive SSH session to the workspace.

Open in VS Code

replicas code <workspace-name>

Opens the workspace in VS Code via Remote SSH.

Switch Organization

replicas org switch

Switch between organizations if you belong to multiple.

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 for the full schema.

​Installation

​Authentication

​Connect a Coding Agent Account

​Replica Management

​List Replicas

​Get Replica Details

​Create a Replica

​Send Message to Replica

​Delete a Replica

​Read Replica History

​List Repositories

​Environment Management

​List Environments

​Get Environment Details

​Create an Environment

​Edit an Environment

​Delete an Environment

​Manage Environment Variables

​Manage Environment Files

​Manage Start Hooks

​Preview Management

​Create a Preview

​List Previews

​Delete a Preview

​Add a Preview

​Remove a Preview

​Computer Use

​Get the Viewer URL

​Session Status

​Screenshot

​Mouse Input

​Keyboard Input

​Launch an App

​Screen Recording

​End-to-End Example

​Canvas vs replicas media upload

​Interactive Mode

​Layout

​Keyboard Shortcuts

​Chat

​Plan and Build Modes

​Diff Viewer

​Automation Management

​List Automations

​Get Automation Details

​Create an Automation

​Edit an Automation

​Run an Automation

​Delete an Automation

​Workspace Connection

​Connect via SSH

​Open in VS Code

​Switch Organization

​Configuration

Installation

Authentication

Connect a Coding Agent Account

Replica Management

List Replicas

Get Replica Details

Create a Replica

Send Message to Replica

Delete a Replica

Read Replica History

List Repositories

Environment Management

List Environments

Get Environment Details

Create an Environment

Edit an Environment

Delete an Environment

Manage Environment Variables

Manage Environment Files

Manage Start Hooks

Preview Management

Create a Preview

List Previews

Delete a Preview

Add a Preview

Remove a Preview

Computer Use

Get the Viewer URL

Session Status

Screenshot

Mouse Input

Keyboard Input

Launch an App

Screen Recording

End-to-End Example

Canvas vs `replicas media upload`

Interactive Mode

Layout

Keyboard Shortcuts

Chat

Plan and Build Modes

Diff Viewer

Automation Management

List Automations

Get Automation Details

Create an Automation

Edit an Automation

Run an Automation

Delete an Automation

Workspace Connection

Connect via SSH

Open in VS Code

Switch Organization

Configuration