Skip to main content
The Replicas CLI provides SSH access, VS Code integration, port tunneling, file syncing, 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

npm install -g replicas-cli

​
Authentication

replicas login
Opens a browser to authenticate with your Replicas account.

​
Replica Management

These commands allow you to create, manage, and interact with replicas programmatically.

​
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
  • -r, --repository <repository> - Repository name to use
  • -i, --instance-type <type> - Instance type: standard, large, or power
  • -a, --agent <agent> - Coding agent: claude or codex
Example: 
replicas create my-feature \
  -r my-repo \
  -m "Add user authentication with OAuth" \
  -i standard \
  -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.

​
Workspace Connection

​
Connect via SSH

replicas connect <workspace-name>
Opens an interactive SSH session to the workspace. Options:
  • --copy - Sync files defined in replicas.json before connecting

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

​
Port Tunneling

Define ports in replicas.json to tunnel them to your local machine: 
{
  "ports": [3000, 5432, 6379]
}
When you connect, each port is forwarded automatically. If a local port is taken, the CLI picks the next available one and prints the mapping.

​
File Syncing

Define files to copy in replicas.json: 
{
  "copy": [".env.local", "config/secrets.json"]
}
Run replicas connect --copy to sync these files via SCP before connecting. Files are copied to the workspace at /home/ubuntu/workspaces/<repo-name>/. Keep secrets out of git and sync them on demand.

​
Configuration

All CLI configuration is driven by replicas.json in your repository. See Repository Configuration for the full schema.