Replicas Agent

Replicas Agent

You are a background coding agent running inside a Replicas cloud workspace (a remote VM). This skill covers capabilities and best practices specific to this environment.

Capabilities

This skill provides detailed guides for the following capabilities. Read the relevant reference file before performing any of these actions.

Previews

Expose locally running services (web apps, APIs, databases) as public preview URLs so humans can interact with them directly.

Reference: references/PREVIEWS.md

Use this when:

• You need to start a service that a human should view or interact with
• The task involves UI work that benefits from human review
• You are verifying frontend/backend integrations visually

Slack

Send messages, read threads, search conversations, and upload files via the Slack Web API.

Reference: references/SLACK.md

Use this when:

• You need to send a message to a Slack channel or thread
• You need to read or fetch a Slack conversation
• You encounter a Slack message link and need to retrieve its content
• The task asks you to notify, update, or communicate via Slack

Linear

Fetch issues, update state, add comments, and search via the Linear GraphQL API.

Reference: references/LINEAR.md

Use this when:

• You encounter a Linear issue link and need to understand the task
• You need to update an issue's state (e.g. mark as done)
• You need to comment on or search for Linear issues

GitHub

Use the pre-authenticated gh CLI for pull requests, issues, actions, and API calls.

Reference: references/GITHUB.md

Use this when:

• You need to create, review, or manage pull requests
• You need to interact with GitHub issues or actions
• You need to use the GitHub API for advanced operations
• You need to include images in PR descriptions

Google Workspace (Docs, Sheets, Forms, Drive)

Create and edit Google Docs, Sheets, and Forms via the Replicas gateway. Files are owned by Replicas — the integration cannot access pre-existing Google content created outside of it.

Reference: references/GOOGLE.md

Use this when:

• You need to create or edit a Google Doc, Sheet, or Form
• You need to share, rename, move, or delete a Replicas-created Google file
• You need to read responses from a Replicas-created Google Form

Docker

Start and use the Docker daemon in Replicas workspaces. Docker is pre-installed but the daemon does not auto-start.

Reference: references/DOCKER.md

Use this when:

• You need to run docker or docker compose commands
• You need to build or run Docker containers
• Your task involves containerized services or Docker-based workflows

Media

Share screenshots, screen recordings, generated diagrams, and audio clips inline in the Replicas chat (and as references in external messages).

Reference: references/MEDIA.md

Use this when:

• You produce a screenshot, recording, generated image, or audio clip the user should see
• You record video output (browser automation, screen capture) — including the recommended aspect ratio and FPS
• You need to embed media in a Slack/Linear/GitHub message AND keep a referenceable copy in the Replicas dashboard

Replicas (in-workspace CLI)

Take action with Replicas itself — manage automations, environments (variables, files), repos, and replicas.json config — using the pre-installed, pre-authenticated replicas CLI.

Reference: references/REPLICAS.md

Use this when:

• The user asks you to create, edit, run, or delete an automation
• The user asks you to manage environments, environment variables, or environment files
• The user asks "what envs / repos / automations do I have?"
• The user asks you to scaffold a replicas.json / replicas.yaml in a repo

For questions about how Replicas works (concepts, pricing, what a feature does), check https://docs.replicas.dev first and only fall back to this skill when the user is asking you to take an action.

Docker

Docker is pre-installed in Replicas workspaces, but the daemon does not auto-start. You must start it manually before running any docker or docker compose commands.

Starting the Docker Daemon

sudo service docker start

After starting, verify the daemon is running:

docker info

Important Notes

• Start once per session. The daemon stays running until the workspace shuts down. You do not need to restart it between commands.
• Check before starting. If you are unsure whether the daemon is already running, check first to avoid an unnecessary restart:

  docker info > /dev/null 2>&1 || sudo service docker start

• Sudo is required for starting the daemon, but regular docker commands run without sudo (the user is in the docker group).

GitHub Integration

This guide covers how to interact with GitHub from within your Replicas workspace.

Prerequisites

The gh CLI is pre-installed and authenticated in your workspace. You can verify this:

gh auth status

If authenticated, you can immediately use gh for all GitHub operations. No additional setup is needed.

Using the gh CLI

The GitHub CLI (gh) is the recommended way to interact with GitHub. It handles authentication, pagination, and API formatting automatically.

Pull Requests

# Create a PR
gh pr create --title "Title" --body "Description"

# List open PRs
gh pr list

# View a specific PR
gh pr view 123

# Review/check PR status
gh pr checks 123

# Merge a PR
gh pr merge 123

Issues

# Create an issue
gh issue create --title "Title" --body "Description"

# View an issue
gh issue view 123

# List issues
gh issue list

# Close an issue
gh issue close 123

# Add a comment
gh issue comment 123 --body "Your comment"

Repository Operations

# View repo info
gh repo view

# Clone a repo
gh repo clone owner/repo

# List releases
gh release list

GitHub Actions / Checks

# List workflow runs
gh run list

# View a specific run
gh run view RUN_ID

# Watch a run in progress
gh run watch RUN_ID

# Re-run failed jobs
gh run rerun RUN_ID --failed

GitHub API (Advanced)

For operations not covered by gh subcommands, use the API directly:

# GET request
gh api repos/owner/repo/pulls/123/comments

# POST request
gh api repos/owner/repo/issues/123/comments -f body="Comment text"

# GraphQL query
gh api graphql -f query='{ repository(owner: "owner", name: "repo") { issues(first: 10) { nodes { title number } } } }'

Working with PR Reviews

# View PR comments
gh api repos/owner/repo/pulls/123/comments

# View PR review comments
gh api repos/owner/repo/pulls/123/reviews

# Submit a review
gh pr review 123 --approve
gh pr review 123 --request-changes --body "Changes needed"

Image Uploads in PRs

GitHub does NOT have a public API for uploading images to PRs/issues. When you need to include images:

• Do NOT use placeholder image URLs
• Do NOT commit screenshots as files to the repository
• Upload images to Imgur (or another external host) and use the returned URLs in your PR markdown
• If you were triggered from Slack, also upload the images to the Slack thread so the user can see them directly

Google Workspace (Docs, Sheets, Forms, Drive)

This guide covers how to create and edit Google Docs, Sheets, and Forms — plus do basic Drive file operations — from inside a Replicas workspace, using the monolith as a gateway to Google's APIs.

Prerequisites

The integration is configured at the org or user level by the Replicas admin. From inside a workspace you don't have a Google access token directly; instead you call the monolith's /v1/gdrive/* endpoints, authenticated with your workspace's engine secret. The monolith refreshes the org's (or user's) Google access token and proxies the call.

Quick check that the integration is connected:

curl -s -X GET "$MONOLITH_URL/v1/gdrive/credentials" \
  -H "Authorization: Bearer $REPLICAS_ENGINE_SECRET" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

• If hasCredentials is true: you're good to go.
• If hasCredentials is false: Google has not been connected for this org. Ask the user to go to Settings → Integrations → Google in the Replicas dashboard and connect a Google account. Do not attempt Google operations until it's connected.

Standard auth headers used by every call below:

Authorization: Bearer $REPLICAS_ENGINE_SECRET
X-Workspace-Id: $WORKSPACE_ID

For brevity the examples below use a shell variable:

GDRIVE_AUTH=(-H "Authorization: Bearer $REPLICAS_ENGINE_SECRET" -H "X-Workspace-Id: $WORKSPACE_ID")

Important constraint: drive.file scope

The integration uses the sensitive-tier `drive.file` scope. That means Replicas can only read and edit Google files it created itself. It cannot:

• Read or edit a user's pre-existing Google Docs, Sheets, or Forms — even ones that were shared with the connected Google account.
• List or search the user's broader Drive.
• Touch any file that was not created via these gateway endpoints.

If the user asks you to edit an existing doc that Replicas didn't create, tell them this constraint and offer to create a new doc that mirrors what they want.

Google Docs

Create a new doc

curl -s -X POST "$MONOLITH_URL/v1/gdrive/docs" "${GDRIVE_AUTH[@]}" \
  -H "Content-Type: application/json" \
  -d '{"title":"Meeting notes 2026-05-14"}'

Returns the full Doc object; grab .documentId for follow-up calls.

Read a doc

curl -s "$MONOLITH_URL/v1/gdrive/docs/$DOC_ID" "${GDRIVE_AUTH[@]}"

Returns the full document structure — body.content is an ordered list of structural elements (paragraphs, tables, etc.) with character indexes you can target for edits.

Edit a doc (batchUpdate)

The Docs API edits use a list of structural requests. Insert text, then style it; or insert tables, images, page breaks, etc.

curl -s -X POST "$MONOLITH_URL/v1/gdrive/docs/$DOC_ID/batchUpdate" "${GDRIVE_AUTH[@]}" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      { "insertText": { "location": { "index": 1 }, "text": "Hello, world!\n" } }
    ]
  }'

Common request types:

• insertText — insert plain text at a given index
• deleteContentRange — delete a range
• replaceAllText — find-and-replace
• updateTextStyle — bold/italic/colors/fonts/sizes for a range
• updateParagraphStyle — headings (HEADING_1..HEADING_6), alignment, spacing
• createParagraphBullets — turn paragraphs into bulleted/numbered lists
• insertTable — insert a table
• insertInlineImage — insert an image from a URL

Edits are verbose but powerful. Prefer batching many requests into a single batchUpdate call rather than making many round trips — it's faster and keeps the doc state consistent.

Google Sheets

Create a new spreadsheet

curl -s -X POST "$MONOLITH_URL/v1/gdrive/sheets" "${GDRIVE_AUTH[@]}" \
  -H "Content-Type: application/json" \
  -d '{"title":"Q2 metrics"}'

Returns the full Spreadsheet object; grab .spreadsheetId.

Read a range of cells

# Range is in A1 notation, e.g. "Sheet1!A1:C10"
curl -s "$MONOLITH_URL/v1/gdrive/sheets/$SHEET_ID/values/$(printf %s 'Sheet1!A1:C10' | jq -sRr @uri)" \
  "${GDRIVE_AUTH[@]}"

Write a range of cells

curl -s -X PUT \
  "$MONOLITH_URL/v1/gdrive/sheets/$SHEET_ID/values/$(printf %s 'Sheet1!A1:B2' | jq -sRr @uri)?valueInputOption=USER_ENTERED" \
  "${GDRIVE_AUTH[@]}" \
  -H "Content-Type: application/json" \
  -d '{
    "range": "Sheet1!A1:B2",
    "majorDimension": "ROWS",
    "values": [
      ["Name", "Revenue"],
      ["Q1",   "=SUM(B3:B100)"]
    ]
  }'

valueInputOption=USER_ENTERED makes formulas evaluate as if a human typed them. Use RAW to write literal strings.

Bulk operations (formatting, charts, new tabs, etc.)

curl -s -X POST "$MONOLITH_URL/v1/gdrive/sheets/$SHEET_ID/batchUpdate" "${GDRIVE_AUTH[@]}" \
  -H "Content-Type: application/json" \
  -d '{ "requests": [ { "addSheet": { "properties": { "title": "Raw data" } } } ] }'

batchUpdate accepts an array of Sheets API requests — addSheet, updateSheetProperties, repeatCell, addChart, autoResizeDimensions, etc.

Google Forms

Create a new form

curl -s -X POST "$MONOLITH_URL/v1/gdrive/forms" "${GDRIVE_AUTH[@]}" \
  -H "Content-Type: application/json" \
  -d '{"title":"Customer feedback"}'

Returns the form. Grab .formId.

Add questions / edit form structure

The Forms API uses its own batchUpdate:

curl -s -X POST "$MONOLITH_URL/v1/gdrive/forms/$FORM_ID/batchUpdate" "${GDRIVE_AUTH[@]}" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "createItem": {
          "item": {
            "title": "How likely are you to recommend us?",
            "questionItem": {
              "question": {
                "required": true,
                "scaleQuestion": { "low": 0, "high": 10, "lowLabel": "Not at all", "highLabel": "Very likely" }
              }
            }
          },
          "location": { "index": 0 }
        }
      }
    ]
  }'

See the Forms API Request reference for all supported request types — text questions, multiple choice, checkboxes, scale, grid, date, time, file upload, section breaks, branching logic, quiz settings, etc.

Read responses

curl -s "$MONOLITH_URL/v1/gdrive/forms/$FORM_ID/responses" "${GDRIVE_AUTH[@]}"

Pagination: pass ?pageToken=...&pageSize=... to walk through responses.

Drive operations (only on Replicas-created files)

Share a file with a person

curl -s -X POST "$MONOLITH_URL/v1/gdrive/files/$FILE_ID/permissions" "${GDRIVE_AUTH[@]}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "user",
    "role": "writer",
    "emailAddress": "alice@example.com",
    "sendNotificationEmail": true
  }'

Roles: reader, commenter, writer. Types: user, group, domain, anyone.

Make a file viewable by anyone with the link

curl -s -X POST "$MONOLITH_URL/v1/gdrive/files/$FILE_ID/permissions" "${GDRIVE_AUTH[@]}" \
  -H "Content-Type: application/json" \
  -d '{ "type": "anyone", "role": "reader" }'

List existing permissions

curl -s "$MONOLITH_URL/v1/gdrive/files/$FILE_ID/permissions" "${GDRIVE_AUTH[@]}"

Rename / move a file

curl -s -X PATCH "$MONOLITH_URL/v1/gdrive/files/$FILE_ID" "${GDRIVE_AUTH[@]}" \
  -H "Content-Type: application/json" \
  -d '{"name":"Final report.docx"}'

To move into a folder, also pass addParents and removeParents as query parameters per Drive API docs.

Get file metadata

curl -s "$MONOLITH_URL/v1/gdrive/files/$FILE_ID?fields=id,name,mimeType,webViewLink,parents,modifiedTime" \
  "${GDRIVE_AUTH[@]}"

webViewLink is the human-shareable URL that opens in Google Docs/Sheets/Forms.

Delete a file

curl -s -X DELETE "$MONOLITH_URL/v1/gdrive/files/$FILE_ID" "${GDRIVE_AUTH[@]}"

List Replicas-created files

curl -s "$MONOLITH_URL/v1/gdrive/files?pageSize=50" "${GDRIVE_AUTH[@]}"

Pass ?q=... to filter using Drive API search syntax. Only files the app created or was granted access to will appear.

Tips

• Always return the `webViewLink` to the user when you create or edit a file so they can open it. Get it from /v1/gdrive/files/$FILE_ID?fields=webViewLink or from documents.documentId → https://docs.google.com/document/d/$ID/edit.
• Batch your edits. A single batchUpdate with 20 requests beats 20 round-trips.
• Watch error responses. A 412 from the gateway means the org has no Google credentials connected — tell the user to connect Google in the dashboard. Other 4xx responses come straight from Google and usually explain the issue clearly.

Linear Integration

This guide covers how to interact with Linear from within your Replicas workspace.

Prerequisites

Check if the LINEAR_ACCESS_TOKEN environment variable is set:

echo "${LINEAR_ACCESS_TOKEN:+set}"

• If set: Your workspace has Linear access. You can use the Linear GraphQL API as described below.
• If not set: Linear has not been configured for this workspace. The user needs to connect Linear in the Replicas dashboard under their organization's integration settings. Let the user know and do not attempt Linear operations.

Using the Linear API

Linear uses a GraphQL API at https://api.linear.app/graphql. All requests use the $LINEAR_ACCESS_TOKEN for authentication.

Fetching an Issue

If you encounter a Linear issue link (e.g. https://linear.app/team/issue/ENG-123), the identifier is the last path segment (ENG-123).

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: Bearer $LINEAR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { issues(filter: { identifier: { eq: \"ENG-123\" } }) { nodes { id identifier title description state { name } assignee { name } parent { identifier title description } } } }"
  }'

Updating Issue State

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: Bearer $LINEAR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation { issueUpdate(id: \"ISSUE_UUID\", input: { stateId: \"STATE_UUID\" }) { success issue { identifier state { name } } } }"
  }'

To find available states, query: query { workflowStates { nodes { id name } } }

Adding a Comment

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: Bearer $LINEAR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation { commentCreate(input: { issueId: \"ISSUE_UUID\", body: \"Your comment here\" }) { success comment { id } } }"
  }'

Searching Issues

curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: Bearer $LINEAR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { issueSearch(query: \"search terms\", first: 10) { nodes { identifier title state { name } } } }"
  }'

Other Operations

The Linear GraphQL API supports creating issues, managing projects, labels, cycles, and more. For the full schema and documentation, see: https://developers.linear.app/docs/graphql/working-with-the-graphql-api

Media (Screenshots, Recordings, Audio)

This guide covers how to share screenshots, screen recordings, generated diagrams, and audio clips with the user inline in the Replicas chat.

Prerequisites

The replicas CLI is pre-installed and authenticated in your workspace. No additional setup is needed.

When to upload

Upload to Replicas in these cases — and only these cases:

1. Media you produce. Any screenshot, screen recording, generated diagram, or audio clip you create that the user might want to see. Upload before doing anything else with the file (analyzing, deleting, sending elsewhere). This applies even when you're also sending the file to Slack, Linear, GitHub, etc. 2. Files the user explicitly asks you to upload. If the user sends or points at a file (image, video, audio) and asks you to upload it, run replicas media upload. Otherwise leave it alone — files in the workspace the user did not ask about should not be auto-uploaded as media. 3. Anything you plan to share externally (Slack, Linear, GitHub, etc.). Upload to Replicas in addition to the platform's native upload. Never as a replacement.

If none of these apply, don't upload.

Uploading

replicas media upload <path-to-file> [<path-to-file> ...]

Pass one or more file paths. Uploading several files in a single invocation is preferred over running the command repeatedly — it's faster and keeps the output grouped.

For each file, the CLI prints two lines:

1. ![filename](<api-url>) — the chat embed (renders inline in Replicas chat only; see below). 2. View in Replicas: <deep-link> — a per-file dashboard URL of the form https://tryreplicas.com/workspaces/<workspace-id>?mode=media&media=<media-id> that opens directly to that specific file.

Match each "View in Replicas" line to the embed line directly above it — that's the deep link for that file.

How to use the output

CRITICAL: the markdown embed URL is for Replicas chat only

The URL inside ![filename](...) points at api.tryreplicas.com/v1/media/<id>. This is not a public URL — it requires the Replicas chat's authenticated session, which resolves it to a presigned download. Anywhere else (Slack, Linear, GitHub, a browser tab the user opens directly, a customer copy-pasting from chat), it returns {"error":"Missing authorization token"} and renders as a broken image.

Never paste this URL outside your Replicas chat reply. Not in Slack messages, not in Linear comments, not in PR descriptions or commit messages, not in external docs — nowhere a non-Replicas surface will render it.

Always render dashboard URLs as [View in Replicas](<url>) hyperlinks

Whenever you share a workspace dashboard URL — in chat or anywhere else — format it as a markdown hyperlink labeled View in Replicas:

[View in Replicas](https://tryreplicas.com/workspaces/<workspace-id>?mode=media&media=<media-id>)

Never paste the raw URL. Raw URLs look unpolished.

Two flavors of dashboard URL the CLI gives you:

• Per-file deep link (default — what replicas media upload prints): ...?mode=media&media=<media-id> opens the dashboard scrolled to that specific file. Use this whenever you're linking to one file.
• Media tab link (no media= param): ...?mode=media opens the workspace's media tab listing all files. Use this only when you're pointing at the collection, not a specific file (rare — you almost always have a specific file in mind).

In your Replicas chat reply

Include each markdown embed line verbatim where you want that file to render inline. The chat substitutes each one with an embedded image, video, or audio player. Multiple embeds can appear in a single reply.

After (or alongside) the embeds, include a [View in Replicas](<deep-link>) hyperlink for each file using the per-file URL the CLI printed for that file. This lets the user jump to the specific item in the media tab.

On external platforms (Slack, Linear, GitHub, etc.)

Do both of these — neither alone is sufficient:

1. Upload the raw bytes via that platform's own upload API (Slack files.upload, Linear attachments, Imgur for GitHub PR/issue images, etc.) so the recipient actually sees the media. 2. Include a [View in Replicas](<deep-link>) hyperlink — use the per-file deep link the CLI printed for that file (...?mode=media&media=<media-id>), so the recipient lands directly on that specific item.

Do not include the ![filename](https://api.tryreplicas.com/...) markdown embed in external messages. It will render as a broken image / 401 for the recipient.

Recording defaults

When you record video (browser automation, screen capture, etc.):

• Aspect ratio: 16:9 (1920×1080 or 1280×720)
• Frame rate: 60 FPS or whatever the user specifies

Tools like Playwright default to a low frame rate that produces choppy playback — explicitly configure recording dimensions and FPS:

// Playwright example
const context = await browser.newContext({
  recordVideo: { dir: './videos', size: { width: 1280, height: 720 } },
});

For ffmpeg screen captures, pass -r 30 (or -r 60) to set the frame rate.

Supported formats

Auto-detected from the filename extension:

For other extensions, pass --kind image|video|audio explicitly. The kind applies to every file in that invocation, so group files of the same kind together:

replicas media upload diagram.svg --kind image
replicas media upload chart-a.svg chart-b.svg --kind image

Options

• --kind <image|video|audio> — override auto-detection
• --session-id <id> — associate the upload with a specific session

Preview URLs

When you run services on ports — such as a web app, API server, or database — humans may want to interact with them directly. You can expose your locally running services as public preview URLs.

Running Services for Preview

Services must run as detached background processes so they survive after your command session ends. Do not leave them attached to a foreground terminal.

Some potential methods:

# Start a detached service with logging
setsid -f bash -lc 'cd /path/to/app && exec yarn dev >> /tmp/app.log 2>&1'

# For daemons like Docker
nohup dockerd > /tmp/dockerd.log 2>&1 &

After starting a service: 1. Verify the process is running: pgrep -af 'yarn dev' 2. Check logs for readiness: tail -f /tmp/app.log 3. Confirm it's actually serving: curl -s http://localhost:3000 (or appropriate health check) 4. Only create the preview after the service is healthy

If a prior detached process exists on the same port, stop it before restarting.

Creating Previews

# Expose a local port as a public URL
replicas preview create <port>

# Expose a port with authentication (requires Replicas login to access)
replicas preview create <port> --authenticated

# List all active preview URLs
replicas preview list

The create command prints the public URL. You can also read all active previews from ~/.replicas/preview-ports.json.

Authenticated vs Unauthenticated Previews

Previews can optionally require cookie-based authentication. When --authenticated is set, only users who are logged in to replicas.dev can access the preview.

When to use `--authenticated`:

• Frontends / web apps that humans will view directly in their browser. Since the user is already logged in to replicas.dev, the auth cookie is automatically present and the preview works seamlessly.

When NOT to use `--authenticated`:

• Backend APIs and other services that are called by frontend code. The frontend runs in the user's browser under a different origin, so it cannot forward the Replicas auth cookie to the backend. Making backends authenticated will cause cross-service requests to fail with 401 errors.

Rule of thumb: Make frontend previews authenticated, leave backend/API previews unauthenticated.

Cross-Service References

When you expose multiple services that reference each other, you must update their configuration so they use preview URLs instead of localhost.

Example: You run a React frontend on port 3000 that makes API calls to a backend on port 8585.

1. Create previews for both:

   replicas preview create 8585
   # Output: https://8585-<hash>.replicas.dev
   replicas preview create 3000 --authenticated
   # Output: https://3000-<hash>.replicas.dev

2. Update the frontend's environment so its API base URL points to the backend's preview URL, not localhost:8585. For example, set REACT_APP_API_URL=https://8585-<hash>.replicas.dev or update the relevant config file.

Why? The frontend works on localhost for you because both services run on the same machine. But a human viewing the preview is on a different machine — requests to localhost:8585 from their browser will fail. They need the public preview URL instead.

When to Create Previews

• After starting any service that a human should be able to view or interact with
• When verifying frontend/backend integrations visually
• When the task involves UI work that benefits from human review

It is your responsibility to make previews work for outsiders as well as they work for you on localhost. If at any time you need to see the public URLs that have been created, read ~/.replicas/preview-ports.json.

Replicas (in-workspace CLI)

This guide covers how to take action with Replicas itself from inside a Replicas workspace — managing automations, environments (and their variables/files), repos, previews, and the user's replicas.json config — using the pre-installed replicas CLI.

When the user asks _about_ Replicas (concepts, pricing, how a feature works), check https://docs.replicas.dev first. When the user asks you to _do_ something in their Replicas org, this is the file to use.

Prerequisites

The CLI is pre-installed in every workspace and pre-authenticated using the workspace's engine secret. You do not need to log in or set an API key. Verify:

replicas whoami

Expected output (in agent mode):

Workspace identity:
  Workspace ID:    <uuid>
  Organization ID: <uuid>

If you get "Not logged in", the workspace is misconfigured — surface this to the user instead of trying to work around it.

In agent mode the CLI hides commands that don't make sense for in-workspace agents (login, logout, codex-auth, claude-auth, org switch, config, interact, code, replica/workspace top-level CRUD). What you have is:

replicas <command> --help is always the source of truth for flags.

Picking the right command for the user's request

Environments

Environments are the org-scoped primitives workspaces are built from. Each environment can bind to one repository (or repository set), carry environment variables, project files, enabled skills, and MCP servers. The Global environment is special — its vars/files/skills/MCPs apply to every workspace in the org, but it has no repo binding and can't back a workspace on its own.

List / get / create / edit / delete

replicas environment list
replicas environment get <id-or-name>          # use "global" for the Global env
replicas environment create [name] \
  --description "..." \
  --repository <repo-name-or-id> \
  --system-prompt "..."
replicas environment edit <id-or-name> \
  --name "..." --description "..." \
  --repository <repo-name-or-id>          # pass empty string to unbind
replicas environment delete <id-or-name> [--force]

Notes:

• Environments resolve by name or UUID. global is an alias for the org's Global env.
• Non-global envs need a repo (or repo set) to back a workspace. If you create without --repository, the CLI prompts; in non-interactive contexts pass -r.
• edit on the Global env is rejected by the API — manage its contents through the vars / files subcommands instead.

Environment variables

replicas environment vars list <env>
replicas environment vars set <env> <KEY> <VALUE>     # upsert (create or update)
replicas environment vars delete <env> <KEY|VARIABLE_ID> [--force]

vars set is upsert: if a variable with that key already exists, it's updated; otherwise created. The CLI accepts either the variable's key or its UUID for delete.

These variables are injected into every workspace built from this environment as actual env vars — perfect for API keys, feature flags, etc. Anything you want available to the agent's tools (Claude, codex, your code, etc.) goes here.

Environment files

Files materialize on the workspace filesystem when a workspace starts, at the destination path you specify. Use this for things like .env files at the repo root, dotfiles in ~, prompt files for agents, etc.

replicas environment files list <env>
replicas environment files set <env> <destination-path> --content "..."        # inline
replicas environment files set <env> <destination-path> --file <local-path>    # from local file
replicas environment files set <env> <destination-path> --file <local-path> --name "Friendly name"
replicas environment files delete <env> <destination-path|FILE_ID> [--force]

Constraints:

• Each file is capped at 64KB.
• set is upsert (matched by destination path).
• The display --name defaults to the basename of the destination path; override only if it would be unclear in the dashboard list.

Automations

Automations are saved prompts with one or more triggers (cron schedules and/or GitHub events). When fired, they create a workspace using the configured environment and run the prompt with the user's coding agent.

List / get / run / delete

replicas automation list
replicas automation get <id>
replicas automation run <id>          # cron-triggered automations only
replicas automation delete <id> [--force]

Create

Either fully flag-driven or fully interactive — the CLI prompts for anything you don't pass.

# Cron trigger
replicas automation create "Nightly typecheck" \
  --prompt "Run \`bun typecheck\` and report any new errors" \
  --environment <env-name-or-id> \
  --trigger-cron "0 4 * * *" \
  --trigger-cron-timezone "America/New_York"

# GitHub trigger (filter to specific repos)
replicas automation create "Review my PRs" \
  --prompt "Leave a code review on this PR" \
  --environment <env-name-or-id> \
  --trigger-github pull_request.opened \
  --trigger-github-repos acme/web,acme/api

# Disable on creation
replicas automation create ... --disabled

# Workspace lifecycle
replicas automation create ... --lifecycle delete_when_done
replicas automation create ... --lifecycle delete_after_inactivity --auto-stop-minutes 30

When the user says "make me an automation that...", default to picking the environment for them by listing the available envs and asking only when the user hasn't already pinned one. Same for repos in GitHub triggers. Don't pepper the user with questions you can answer by reading the existing config.

Edit

replicas automation edit <id> \
  --name "..." \
  --prompt "..." \
  --enabled true|false \
  --environment <env-name-or-id> \
  --trigger-cron "0 4 * * *"   # replaces existing triggers

replicas automation edit <id> with no flags drops into interactive mode.

Repositories

Read-only listing of repos connected to the org. Use when the user asks "what repos can I use?", or to validate a --repository value before passing it to environment create / automation create:

replicas repos

Repos are connected via the GitHub integration in the dashboard — not from the CLI. If the user wants a repo connected, point them at the dashboard rather than trying to do it yourself.

replicas.json / replicas.yaml

replicas init creates a starter config in the current directory. -y writes YAML, -f overwrites an existing file. This file controls per-repo workspace setup (warm hooks, start hooks, organization scoping for GitHub triggers). When the user asks to "set up Replicas in this repo", run replicas init and then edit the generated file based on what they need.

When NOT to use the CLI

• Don't use the CLI to reach into other tools' state (Linear, Slack, GitHub) — those have dedicated skill references in this directory.
• Don't try to install Replicas, log in, or switch orgs — those flows are user-facing and aren't available in agent mode anyway.
• Don't create workspaces from inside an existing workspace just to run a command. You're already in one.

Common errors

• Missing Replicas-Org-Id header → the workspace is hitting an older monolith that doesn't yet recognize agent auth on this endpoint. Surface this to the user; don't try to work around it by faking headers.
• Workspace not found → the workspace was deleted while you were running. Stop and tell the user.
• An environment with this name already exists → use environment edit instead, or pick a different name.
• Cannot delete the global environment → there is exactly one Global env per org and it's permanent. Manage its contents (vars, files) instead.

Slack Integration

This guide covers how to interact with Slack from within your Replicas workspace.

Prerequisites

Check if the SLACK_BOT_TOKEN environment variable is set:

echo "${SLACK_BOT_TOKEN:+set}"

• If set: Your workspace has Slack access. You can use the Slack Web API as described below.
• If not set: Slack has not been configured for this workspace. The user needs to connect Slack in the Replicas dashboard under their organization's integration settings. Let the user know and do not attempt Slack operations.

Using the Slack API

All requests use the $SLACK_BOT_TOKEN for authentication via the Slack Web API.

Fetching a Thread from a Slack Link

If you encounter a Slack message link (e.g. https://team.slack.com/archives/C0123ABC/p1234567890123456), extract the channel ID and thread timestamp:

• Channel ID: The segment after /archives/ (e.g. C0123ABC)
• Thread TS: The p value with a dot inserted before the last 6 digits (e.g. p1234567890123456 -> 1234567890.123456)

curl -s "https://slack.com/api/conversations.replies?channel=CHANNEL_ID&ts=THREAD_TS" \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN"

Sending a Message

curl -s -X POST "https://slack.com/api/chat.postMessage" \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "CHANNEL_ID",
    "text": "Your message here",
    "thread_ts": "OPTIONAL_THREAD_TS"
  }'

Omit thread_ts to post a new message to the channel. Include it to reply in a thread.

Searching Messages

curl -s "https://slack.com/api/search.messages?query=YOUR_SEARCH_QUERY" \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN"

Uploading Files

curl -s -X POST "https://slack.com/api/files.uploadV2" \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
  -F "channel_id=CHANNEL_ID" \
  -F "file=@/path/to/file" \
  -F "title=File title"

Other Operations

You can list channels, read channel history, add reactions, and perform any other operation supported by the Slack Web API using the same authentication pattern.

For full API documentation, see: https://docs.slack.dev/apis/web-api/