The Replicas CLI provides SSH access, VS Code integration, and workspace configuration.
For Coding Agents: If you’re using coding agents like Claude Code, Codex, Cursor, Opencode, or Pi, the CLI is the recommended way to work with Replicas from inside a workspace. Coding agents tend to perform better with bash commands than MCP integrations.
Installation
Authentication
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.
Credentials attach to your personal account by default, which works in every organization you belong to:
Organization admins can pass --org to share one set of credentials with every member instead:
Replica Management
Logged-in CLI sessions use a user JWT, which is not accepted by /v1/replica. Use the Replica API with an organization or personal API key to list, create, inspect, message, read, or delete replicas.
Environment Management
Manage Environments from the CLI. Use replicas environment or the shorter replicas env alias.
List Environments
Shows every environment in your organization, including the Global environment, with attached variable, file, skill, and MCP counts.
Get Environment Details
Shows one environment by name, UUID, or global.
Create an Environment
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:
Edit an Environment
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
Deletes an environment after confirmation.
Options:
-f, --force - Skip confirmation prompt
Manage Environment Variables
Values are masked by default when listed. Pass --reveal to show full values.
Manage Environment Files
Files are written into new workspaces at the configured destination path.
Manage Start Hooks
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, 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, 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.
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.
Find the target workspace ID in its dashboard URL before switching.
Both commands default to REPLICAS_SLACK_CHANNEL_ID and REPLICAS_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
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
Lists active preview URLs for the current workspace in agent mode.
In human mode, pass the workspace ID:
Delete a Preview
Unregisters a preview port from the current workspace. This command is available in agent mode.
Add a Preview
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
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 is still running after the workspace wakes. Available in agent mode only.
Start a Service
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
Lists registered services with pid and running/stopped status.
Service Logs
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
Stops the service and its whole process group.
Computer Use
Drives the workspace’s Linux desktop through the replicas-computer daemon. The live H.264 and Opus stream 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.
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
Prints the live desktop viewer URL (https://6080-<hash>.tryreplicas.com/). Use this when you want to share the stream out-of-band; the dashboard already points at the same authenticated URL.
Session Status
Checks and repairs the desktop bridge, then shows which desktop services are running and the active preview URL.
Screenshot
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
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
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
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
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
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>.
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
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 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)
Type options: --delay <ms> (default 12, ~80 wpm)
Launch an App
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
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
Two related surfaces share the workspace VM:
- The Canvas at
~/.replicas/canvas/ accepts files up to 25MB, including chat attachments. Inline previews and downloads are capped at 5MB.
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 <page.html> --name "<name>" --access organization prints a stable Forge link for pull requests. It opens in a dedicated sandboxed viewer, requires Replicas sign-in and organization membership, and returns signed-out members to the page after authentication.
- HTML pages only support organization access.
--access public creates a revocable bearer URL for image, video, or audio assets that must render without Replicas authentication. Anyone with the URL can view it. --share remains an alias for public access; 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 inside the workspace (a plan, a report, a small rendered page), use Canvas. If it is captured media or an HTML page that must be shared outside the workspace, use replicas media upload.
Interactive Mode
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:
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
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 an automation reports on are listed too, so you can see which ones are already configured.
Get Automation Details
Shows detailed information about a specific automation including triggers, prompt, environment, cron schedule, and lifecycle policy.
Create an Automation
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-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 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:
To ignore bot or user activity on code-host triggers:
Edit an Automation
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 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
Manually triggers an automation. Only automations with a cron trigger can be run manually.
Delete an Automation
Deletes an automation.
Options:
-f, --force - Skip confirmation prompt
Report a GitHub Check
Reports this run’s verdict on one of its 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
Opens an interactive SSH session to the workspace.
Open in VS Code
Opens the workspace in VS Code via Remote SSH.
Switch Organization
The active organization is where org-scoped writes land, including credentials saved by claude-auth and codex-auth. It persists until you change it.
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.
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.