Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.replicas.dev/llms.txt

Use this file to discover all available pages before exploring further.

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

​
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)
  • 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 or codex
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 or codex

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

​
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

​
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 or Codex). Supports multiple chat tabs when a workspace has both 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:
PanelShortcutAction
Sidebarj / kNavigate up/down
SidebarEnterSelect workspace or toggle group
SidebaraCreate workspace (when on ”+ New workspace” row)
SidebardDelete workspace (press twice to confirm)
SidebarwWake sleeping workspace
Chat tabs← / → / TabSwitch between agent tabs
Chat historyj / kScroll messages
Chat inputEnterSend message
Chat inputShift+EnterInsert new line
Chat inputTabToggle plan/build mode
Diff viewerj / kNavigate file list
Diff viewerTabSwitch between file list and diff content
Info panelj / kNavigate items
Info panelg / GJump to first/last item
Info panelEnterOpen selected item
Info paneloOpen workspace in web dashboard
Info panelwWake sleeping workspace
Any1 / 2Switch between chat and diff view
AnyShift+TabCycle focus between panels
AnyEscInterrupt agent processing
AnyCtrl+CQuit

​
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

​
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)
  • --enabled - Whether the automation starts enabled (default: true)
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
  • --environment <name|id> - Move the automation to a different environment

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