Skip to main content
The Replicas CLI covers what the dashboard does: workspaces, chats, pull requests, environments, repositories, plugins, learnings, automations, and media. Scripts, CI, and agents can drive the CLI. Automations, the API, the MCP server, and the CLI are the sanctioned channels for programmatic use of Replicas. Workspaces a script creates through the CLI are billed as API usage.
Coding agents work better with bash commands than with MCP tools, so the CLI is the recommended way for an agent to drive Replicas.

Installation

Requires Node.js 18 or newer.

Authentication

The browser sign-in selects your organization if you belong to one, and asks otherwise. For scripts, CI, and agents, sign in with an API key. Without a value, --api-key prompts for the key, which needs a terminal. The CLI checks the key, prints its organization and identity, and stores it in ~/.replicas/config.json. The key determines the organization, so replicas org switch doesn’t apply. Signing in either way replaces the other credentials, and replicas logout clears them. The coding agent commands below need a browser sign-in. Inside a workspace, the CLI is already authenticated as that workspace and acts with its owner’s access, so replicas login isn’t available there. replicas whoami prints the workspace ID. Admin-only commands (adding repositories, organization-wide plugins) need a signed-in admin or an admin’s personal API key.

Connect a Coding Agent Account

Each command runs the provider’s OAuth flow and saves the credentials to your personal account, which works in every organization you belong to. Admins can pass --org to share one set of credentials with the organization. Pass -y, --yes to skip the confirmation. Run codex-auth or claude-auth again with a different login to add another account. Personal credentials take priority over organization defaults. Cursor uses an API key set in Organization → Coding Agents.

Coding Agent API Keys

Manage API keys and inference providers with replicas credentials. Commands apply to your personal account by default. Pass --org to target the organization; saving needs an admin. Services: anthropic, openai, openrouter, cursor, muse-api-key, opencode-go, aster, ollama, anthropic-compatible, openai-compatible, bedrock, claude-foundry, and codex-foundry. Provider settings are flags, such as --base-url, --models, --aws-access-key-id, --aws-region, --resource, and --model. See replicas credentials set --help. For bedrock, stdin holds the AWS secret access key. Subscriptions connect with the commands above. Personal credentials need a browser sign-in or a personal API key.

Switch Organization

The active organization is where every org-scoped command reads and writes. replicas billing shows its balance and the limit new workspaces are checked against. Admins can run replicas billing usage for cost by day and source.

JSON Output

Add --json to any command, before or after it (replicas --json list or replicas list --json). The command prints one JSON value to stdout: the API response, or { "success": true } for actions that return nothing. Errors go to stderr as { "error": "..." } with a non-zero exit code. JSON mode never prompts, so pass every required option. replicas events prints one JSON object per line.

Workspace Management

Commands take a workspace ID from replicas list.

Chats

Each workspace runs one or more chats. Get chat IDs from replicas chat list <id>. Messages sent while an agent is working steer its running turn, or wait in a queue if you turned on Queue follow-up messages. steer adds a queued message to the running turn; send-now gets it read sooner without cutting off the agent’s current tool call (Claude moves running commands to the background), and stops the current step only for agents that can’t steer:

Pull Requests

Organization policy can block agent merges.

Sharing

Only the workspace owner can change sharing; anyone with access can share an organization-owned workspace.

Canvas

put overwrites an existing Canvas text file.

Previews

Inside a workspace, replicas preview create <port>, list, and delete <port> target the current workspace. --authenticated requires a Replicas login to open the preview; use it for frontends, not for APIs your frontend calls. Use the preview URL, not the workspace’s *.sandbox.tensorlake.ai address, as your app’s public URL and for OAuth redirects, GitHub App callbacks, and webhooks. Those addresses reject requests that don’t come through Replicas. Browser redirects work with --authenticated; webhooks need a preview without it.
A preview without --authenticated makes that port public to anyone with the URL. Verify webhook signatures in your app.

Media

Inside a workspace, upload screenshots, GIFs, recordings, and audio:
--name is required once per file. Paste the printed embeds verbatim into your reply. Images always get a public link; video and audio get a chat-only link unless you pass --access public. Public links are revocable bearer URLs: rotate with replicas media share <mediaId>, revoke with replicas media revoke <mediaId>, delete with replicas media delete <mediaId>. Use the Canvas for workspace files such as plans and reports, and media for captures you share.

Visuals

Inside a workspace, publish a self-contained HTML page as a visual:
--check renders the page without publishing: screenshots in dark and light, its height, console output, and layout warnings. Publishing prints a line to paste into the chat reply and an organization-only Forge link for everywhere else. replicas visualize --help lists the page rules.

Repositories

Repositories and sets accept a name or ID. Adding, changing, and removing them requires an admin.

Environment Management

Manage Environments with replicas env (alias of replicas environment). Commands accept an environment name, ID, or global (the organization’s default environment).

Manage Warm Hooks

save activates without testing, test runs without saving, and save-test saves only if the test passes. Every --file also accepts --content. Save empty content to clear the hook. See Warm Hooks.

Manage Start Hooks

test streams output from an isolated sandbox without saving. Save empty content to clear the hook. See Start Hooks.

Plugins

Plugins connect organization-wide by default. Pass -e <env> to connect them to one environment instead. plugins list --all includes the full catalog, and plugins oauth prints a URL for a person to open.
OAuth must be started by a user or a personal API key.

Learnings

Learnings are organization skills every agent loads.
Inside a workspace, replicas skills suggest SKILL.md --title "…" proposes a learning that is saved only if the user accepts it.

Automation Management

Manage Automations with replicas automation or replicas auto. Without flags, create and edit prompt interactively.

Create an Automation

Inside an automation workspace, report a check verdict with:

Slack Thread Routing

Attaches the current Slack thread to a workspace so replies route there. Both default to REPLICAS_SLACK_CHANNEL_ID and REPLICAS_SLACK_THREAD_TS; override with --channel and --thread-ts. Inside a workspace, attach targets that workspace. Routing to another workspace, or replacing a non-archived destination, requires signing in.

Workspace Identity

Inside a workspace, get short-lived workspace identity tokens. The receiving service verifies aud exactly. See AWS and Google Cloud for credential configuration.

Service Management

Inside a workspace, run dev servers and daemons detached from the agent session so they survive the turn ending and workspace sleep and wake. Starting a service that is already running restarts it.
Each service log keeps only its most recent output, between 5 and 10 MB.

Computer Use

Inside a workspace, drive the Linux desktop. The app’s Desktop tab streams it. Input from several agents is serialized per gesture. Browser actions wait for the page to settle and print what changed, with refs for new elements. Refs reset when the page navigates. With several tabs open, pass --target-id, --title, --url, or --page.

Workspace Connection

tunnel forwards to 127.0.0.1 (--local-port changes the local port). code opens VS Code, or another editor set with config set ide, and prompts for a workspace when none is given. Names with spaces work without quotes.

Repository Configuration

Creates a replicas.json or replicas.yaml. See Repository Configuration.