replicas-agent

어떤 스킬인가요?

Replicas 클라우드 워크스페이스 내에서 실행되는 백그라운드 코딩 에이전트 사용 안내서

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

---
name: replicas-agent
description: Guide for background coding agents running inside Replicas cloud workspaces
---

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

name: Validate Skill

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install skill
        run: npx skills add . --all --global -y

# 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

```bash
sudo service docker start
```

After starting, verify the daemon is running:

```bash
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:
  ```bash
  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).

# 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:
```bash
# 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

```bash
# 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:
   ```bash
   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`.

# 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:

```bash
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](https://replicas.dev) 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:

```bash
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

```bash
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

```bash
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](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/request). Insert text, then style it; or insert tables, images, page breaks, etc.

```bash
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

```bash
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

```bash
# 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

```bash
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.)

```bash
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](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/request) — addSheet, updateSheetProperties, repeatCell, addChart, autoResizeDimensions, etc.

## Google Forms

### Create a new form

```bash
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`:

```bash
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](https://developers.google.com/workspace/forms/api/reference/rest/v1/forms/request) 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

```bash
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

```bash
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

```bash
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

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

### Rename / move a file

```bash
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](https://developers.google.com/workspace/drive/api/reference/rest/v3/files/update).

### Get file metadata

```bash
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

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

### List Replicas-created files

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

Pass `?q=...` to filter using [Drive API search syntax](https://developers.google.com/workspace/drive/api/guides/search-files). 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:

```bash
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](https://replicas.dev) 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`).

```bash
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

```bash
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

```bash
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

```bash
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

# 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:

```bash
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

```bash
# 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

```bash
# 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

```bash
# View repo info
gh repo view

# Clone a repo
gh repo clone owner/repo

# List releases
gh release list
```

### GitHub Actions / Checks

```bash
# 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:

```bash
# 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

```bash
# 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

# 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:

```bash
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:

| Command | What it does |
| --- | --- |
| `replicas whoami` | Print the workspace + org identity |
| `replicas init` | Create a `replicas.json` / `replicas.yaml` in the current directory |
| `replicas connect <name>` | SSH into another workspace (requires user creds — usually only useful when scripting locally) |
| `replicas repos` | List repos connected to the org |
| `replicas environment ...` | Manage environments, env vars, env files |
| `replicas automation ...` | Manage automations (cron + GitHub event triggers) |
| `replicas preview ...` | Register / list preview URLs (covered in `PREVIEWS.md`) |
| `replicas media ...` | Upload screenshots, videos, audio (covered in `MEDIA.md`) |

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

## Picking the right command for the user's request

| User says... | Run |
| --- | --- |
| "What environments do I have?" | `replicas environment list` |
| "Add API key X to my staging env" | `replicas environment vars set <env> <KEY> <VALUE>` |
| "Make me a `.env` file in the workspace with these vars" | `replicas environment files set <env> .env --content "..."` |
| "Create a new env for my `acme/web` repo" | `replicas environment create <name> -r acme/web` |
| "What automations do I have?" | `replicas automation list` |
| "Run my nightly automation now" | `replicas automation run <id>` |
| "Make an automation that runs every weekday at 9am" | `replicas automation create` (interactive) or `--trigger-cron "0 9 * * 1-5"` |
| "Make an automation that runs when a PR opens on `acme/web`" | `replicas automation create ... --trigger-github pull_request.opened --trigger-github-repos acme/web` |
| "What repos are connected?" | `replicas repos` |
| "Set up a `replicas.json` in this repo" | `replicas init` (`-y` for YAML) |

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

```bash
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

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

```bash
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

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

```bash
# 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

```bash
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`:

```bash
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:

```bash
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](https://replicas.dev) 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`)

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

### Sending a Message

```bash
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

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

### Uploading Files

```bash
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/

# 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

```bash
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**:

```markdown
[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:

```ts
// 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:

| Extension | Kind |
|---|---|
| `png`, `jpg`, `jpeg`, `webp` | image |
| `mp4`, `webm` | video |
| `mp3`, `wav` | audio |

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:

```bash
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