### Connect to Multica Cloud

Source: https://multica.ai/docs/cli

Starts the first connection to Multica Cloud. The `setup` command saves the server address, opens a browser for sign-in, and starts the daemon.

```bash
multica setup
```

--------------------------------

### Install and setup Multica on Windows PowerShell

Source: https://multica.ai/docs/cloud-quickstart

Run these two commands in PowerShell on the target computer to install Multica and complete sign-in. The setup command opens a browser for authentication and leaves the daemon running in the background.

```powershell
irm https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.ps1 | iex
multica setup
```

--------------------------------

### Install and setup Multica on macOS/Linux

Source: https://multica.ai/docs/cloud-quickstart

Run these two commands in a terminal on the target computer to install Multica and complete sign-in. The setup command opens a browser for authentication and leaves the daemon running in the background.

```bash
curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash
multica setup
```

--------------------------------

### Clone and start Multica with make dev

Source: https://multica.ai/docs/developers/contributing

Clones the Multica repository and starts the development environment. `make dev` prepares the environment, database, and migrations, then starts Web and API.

```bash
git clone https://github.com/multica-ai/multica.git
cd multica
make dev
```

--------------------------------

### Start worktree again

Source: https://multica.ai/docs/developers/contributing

Starts Web and API for the current worktree after it has been set up.

```bash
make start-worktree
```

--------------------------------

### Full Workflow: make commands for environment management

Source: https://multica.ai/docs/developers/contributing

Commands to start, check, list, stop, destroy, garbage-collect, develop, verify, and build the project environment. `make up` allocates ports and database under a lock, verifies via DATABASE_URL and GET /health, and `make destroy` removes database, CLI profile, daemon workspaces, Desktop userData, and registry entry.

```makefile
make up               # Start this checkout's environment (C=api,web,daemon,desktop)
make status           # Show what is running and prove it is this environment
make list             # List every environment on this machine
make down             # Stop the processes, keep the database
make destroy          # Stop, then drop the database and free the slot
make gc               # Collect expired or directory-less environments
make dev              # Prepare and start the current checkout in the foreground
make check            # Run the complete local verification workflow
make build            # Build the server, CLI, and migrate binaries
```

--------------------------------

### Example agent instructions

Source: https://multica.ai/docs/agents-create

Example instructions for an agent that reviews frontend pull requests. Use as a template for defining an agent's responsibilities, checks, and delivery rules.

```text
You review frontend pull requests.

Read the diff and related tests first, and check only:
- React and TypeScript correctness
- Accessibility
- Consistency with existing component patterns

Do not modify code directly. Post findings in an issue comment,
ordered by severity; when nothing blocks, state clearly that the change can merge.
```

--------------------------------

### Clone and start Multica with make selfhost

Source: https://multica.ai/docs/self-host-quickstart

Clone the Multica repository and run `make selfhost` to start the service. On first run, it creates `.env`, generates secrets, pulls images, and starts containers. Re-running reuses existing `.env` and volumes.

```bash
git clone --depth 1 https://github.com/multica-ai/multica.git
cd multica
make selfhost
```

--------------------------------

### Install Multica CLI with Homebrew

Source: https://multica.ai/docs/cli

Alternative installation method for macOS/Linux when Homebrew is installed.

```bash
brew install multica-ai/tap/multica
```

--------------------------------

### Start the Multica daemon

Source: https://multica.ai/docs/daemon-runtimes

Starts the Multica daemon in the background. Required on web, remote, or headless environments after installing the Multica CLI.

```bash
multica daemon start
```

--------------------------------

### Install Multica CLI on macOS/Linux

Source: https://multica.ai/docs/self-host-quickstart

Installs the Multica CLI using the official install script. Run on the computer that runs your AI coding tools.

```bash
curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash
```

--------------------------------

### Clone repository and install dependencies

Source: https://multica.ai/docs/mobile-app

Clone the Multica repository and install dependencies with pnpm. Requires Node.js, pnpm, and Git.

```bash
git clone https://github.com/multica-ai/multica.git
cd multica
pnpm install
```

--------------------------------

### Full desktop.json configuration with explicit appUrl and wsUrl

Source: https://multica.ai/docs/desktop-app

Override derived URLs when the default derivation doesn't match your deployment. The example includes optional appUrl and wsUrl fields.

```json
{
  "schemaVersion": 1,
  "apiUrl": "https://api.example.com",
  "appUrl": "https://app.example.com",
  "wsUrl": "wss://ws.example.com/socket"
}
```

--------------------------------

### Run daemon in foreground

Source: https://multica.ai/docs/troubleshooting

Run the daemon in the foreground to observe its startup directly. Stop the daemon first, then start it with --foreground.

```bash
multica daemon stop
multica daemon start --foreground
```

--------------------------------

### Frontend: pnpm commands for web and desktop

Source: https://multica.ai/docs/developers/contributing

Install dependencies and run development, build, typecheck, lint, and test scripts for the frontend. Root commands exclude Mobile by default; Mobile has separate scripts and CI.

```bash
pnpm install
pnpm dev:web
pnpm dev:desktop
pnpm build
pnpm typecheck
pnpm lint
pnpm test
```

--------------------------------

### Restart the daemon with CLI

Source: https://multica.ai/docs/install-agent-runtime

Use this command to restart the daemon after installing a new tool. This is needed if the daemon is already running.

```bash
multica daemon restart
```

--------------------------------

### Check Docker and Compose availability

Source: https://multica.ai/docs/self-host-quickstart

Run these commands to confirm Docker Engine or Docker Desktop is installed and that `docker compose` (Compose v2) is available. The legacy `docker-compose` v1 is not supported.

```bash
docker info
docker compose version
```

--------------------------------

### Confirm Multica CLI installation

Source: https://multica.ai/docs/cli

Verifies that the Multica CLI is installed and displays its version.

```bash
multica version
```

--------------------------------

### Install Multica CLI on Windows PowerShell

Source: https://multica.ai/docs/self-host-quickstart

Installs the Multica CLI using the official PowerShell script. Run on the computer that runs your AI coding tools.

```powershell
irm https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.ps1 | iex
```

--------------------------------

### Skill file structure

Source: https://multica.ai/docs/skills

Example of a skill's supporting file layout. The main file is always `SKILL.md`; additional files like references, templates, and scripts are delivered to the agent alongside it. `SKILL.md` is a reserved path and cannot be used for supporting files.

```text
SKILL.md
references/api-conventions.md
templates/review-report.md
scripts/check.sh
```

--------------------------------

### Check Multica authentication and daemon status

Source: https://multica.ai/docs/cli

After `multica setup` finishes, verify the authentication and daemon status with these two commands.

```bash
multica auth status
multica daemon status
```

--------------------------------

### Run CLI command from source: make cli

Source: https://multica.ai/docs/developers/contributing

Run a CLI command from source by passing arguments via ARGS. Example shows running `issue list`.

```makefile
make cli ARGS="issue list"
```

--------------------------------

### Build and install Release version on iPhone

Source: https://multica.ai/docs/mobile-app

Builds a Release version with no Metro dependency and installs it on the connected iPhone. The first build downloads iOS dependencies and compiles React Native; later builds reuse Xcode's cache.

```bash
pnpm ios:mobile:device:prod:release
```

--------------------------------

### Reset development database

Source: https://multica.ai/docs/developers/contributing

Run these commands to stop services, reset the database, and start again. The database name is taken from the current checkout's environment file.

```bash
make stop
```

```bash
make db-reset
```

```bash
make start
```

--------------------------------

### Show current profile configuration

Source: https://multica.ai/docs/troubleshooting

Check the current profile's server_url to verify the daemon is connected to the correct Multica service. To change the address, rerun multica setup self-host.

```bash
multica config show
```

--------------------------------

### Setup Multica when service runs on another machine

Source: https://multica.ai/docs/self-host-quickstart

Run this command on the computer that runs your AI coding tools when the Multica service runs on another machine. Pass the server and app URLs you configured earlier.

```bash
multica setup self-host \
  --server-url https://api.example.com \
  --app-url https://app.example.com
```

--------------------------------

### Example of MULTICA_CLAUDE_PATH and MULTICA_CLAUDE_ARGS

Source: https://multica.ai/docs/environment-variables

Shows how to set the command path and default arguments for Claude Code using environment variables. The path variable overrides the command location, and the args variable provides machine-wide default arguments.

```bash
MULTICA_CLAUDE_PATH=/opt/bin/claude
MULTICA_CLAUDE_ARGS=--max-turns 40
```

--------------------------------

### Default addresses for Web and API

Source: https://multica.ai/docs/developers/contributing

Shows the default local addresses for the Web and API services after starting the development environment.

```text
Web: http://localhost:3000
API: http://localhost:8080
```

--------------------------------

### Example verification code log output

Source: https://multica.ai/docs/self-host-quickstart

Shows the expected log line containing the verification code for the user's email. The code is a six-digit number.

```text
[DEV] Verification code for you@example.com: 123456
```

--------------------------------

### Setup Multica when service runs on same computer

Source: https://multica.ai/docs/self-host-quickstart

Run this command on the computer that runs your AI coding tools when the Multica service runs on the same machine. It checks the server health and opens a browser for login.

```bash
multica setup self-host
```

--------------------------------

### Daemon and runtime commands

Source: https://multica.ai/docs/cli

Commands to control the local daemon (start, stop, restart, status, logs) and to manage runtimes (list, rename, usage, activity). The status command supports --output json, and logs supports --follow.

```bash
multica daemon start
multica daemon stop
multica daemon restart
multica daemon status --output json
multica daemon logs --follow

multica runtime list
multica runtime rename <runtime-id> "Office Mac"
multica runtime usage <runtime-id>
multica runtime activity <runtime-id>
```

--------------------------------

### Check sandbox mode in daemon logs

Source: https://multica.ai/docs/security-model

Use this command to see the effective sandbox mode warning when a run starts unsandboxed. The daemon logs at warn level.

```bash
multica daemon logs --lines 200 | grep "codex sandbox"
```

--------------------------------

### Create an issue with /issue

Source: https://multica.ai/docs/slack-bot-integration

Type /issue followed by a description in a channel or DM. No @-mention is needed. The agent creates the issue and you get a notification in your Multica inbox.

```plaintext
/issue Safari stays on the login page after a successful sign-in
```

--------------------------------

### Verify CLI command in Windows PowerShell

Source: https://multica.ai/docs/install-agent-runtime

Run these commands in Windows PowerShell to confirm the CLI tool is installed and accessible. Replace <command> with the actual command name. The first command prints the executable path.

```powershell
Get-Command <command>
<command> --version
```

--------------------------------

### Verify CLI command on macOS, Linux, or WSL

Source: https://multica.ai/docs/install-agent-runtime

Run these commands in a terminal on macOS, Linux, or WSL to confirm the CLI tool is installed and accessible. Replace <command> with the actual command name (e.g., claude, codex, cursor-agent). The first command prints the executable path.

```bash
command -v <command>
<command> --version
```

--------------------------------

### Issue description for building the site

Source: https://multica.ai/docs/tutorial

Use this as the issue description when creating a new issue in Multica. It instructs the Engineer agent to work in the personal-website repository, start from a template using the shadcn init command, and build a photography portfolio with sections for introduction, work, contact, and pricing. The description specifies constraints, content requirements, and leaves design decisions open. After the agent finishes, it should open a pull request.

```text
Work in the personal-website repository registered in this workspace.

Start from a template instead of scaffolding from scratch:

pnpm dlx shadcn@latest init --preset b5rR41Mtnc --template next --pointer

Run the command, commit the template as-is, then build on top of it.

The site is for a photographer. It needs:

- Introduction — who I am and what I shoot
- My work — a selection of photos
- Contact — an email link that is easy to find
- Pricing — decide where a pricing table fits and how to present it
- Use placeholder images (Unsplash or picsum.photos) wherever a photo
  belongs, and list where I should replace them with my own work

Design:

- Pick a style that fits a photography portfolio. It should feel
  refined and understated; express that through layout, typography
  and spacing, and never use words like "premium" or "high-end"
  in the copy.
- Choose the fonts.

Open a pull request when it is ready.
```

--------------------------------

### Set MULTICA_TELEGRAM_SECRET_KEY environment variable

Source: https://multica.ai/docs/telegram-bot-integration

Set a stable 32-byte encryption key before starting the API server. Generate one with `openssl rand -base64 32`. Keep it long-term; losing or rotating it makes existing Bot tokens unreadable and requires reconnecting each Bot.

```bash
MULTICA_TELEGRAM_SECRET_KEY=<base64-encoded 32-byte key>
```

--------------------------------

### Interpolation with `{{var}}` in English and Simplified Chinese

Source: https://multica.ai/docs/developers/conventions

Shows how to use `{{var}}` interpolation in translations, demonstrating that Chinese may reorder words for natural flow. For example, `Welcome back, {{name}}!` becomes '欢迎回来，{{name}}！'.

```json
// en
{ "welcome_message": "Welcome back, {{name}}!" }

// zh-Hans
{ "welcome_message": "欢迎回来，{{name}}！" }
```

--------------------------------

### Run backfill_task_usage_hourly command

Source: https://multica.ai/docs/troubleshooting

Manually backfill historical usage data when the backend fails to start with 'refusing to drop legacy daily rollups'. Use --dry-run to preview without writing and --sleep-between-slices to reduce read pressure. The command is idempotent, holds an advisory lock, and is mutually exclusive with the server's scheduled rollup.

```bash
cd server
DATABASE_URL='postgres://...' go run ./cmd/backfill_task_usage_hourly
```

--------------------------------

### Multica autopilot CLI commands

Source: https://multica.ai/docs/autopilots

Commands to retrieve autopilot details, trigger an autopilot, list runs, and rotate a webhook trigger URL. The get command returns has_webhook_token and webhook_token_hint instead of live secrets by default; use --show-secrets to expose the live credential, which prints a warning to stderr.

```bash
multica autopilot get <autopilot-id> --output json
multica autopilot trigger <autopilot-id>
multica autopilot runs <autopilot-id>
multica autopilot trigger-rotate-url <autopilot-id> <trigger-id>
```

--------------------------------

### List issues and agents with JSON output

Source: https://multica.ai/docs/cli

Use multica issue list --output json and multica agent list --output json to get structured output for scripting. Avoid parsing the terminal-oriented tables. Each command's output formats and pagination flags are shown in multica <command> --help.

```shell
multica issue list --output json
multica agent list --output json
```

--------------------------------

### Assign, update status, and unassign issues with Multica CLI

Source: https://multica.ai/docs/assigning-issues

Use these CLI commands to assign an issue to an agent by name or ID, update its status, and unassign it. The --no-start flag records ownership without starting a new run, and --to-id avoids name ambiguity. The same flag is available on issue update and issue status.

```bash
multica issue assign MUL-42 --to "Agent name"
multica issue assign MUL-42 --to-id <agent-uuid> --no-start
multica issue status MUL-42 in_progress --no-start
multica issue assign MUL-42 --unassign
```

--------------------------------

### Check backend readiness with curl /readyz

Source: https://multica.ai/docs/self-host-quickstart

Run this command to confirm the backend, database, and migrations are ready. The expected response is {"status":"ok","checks":{"db":"ok","migrations":"ok"}}.

```bash
curl -fsS http://localhost:8080/readyz
```

--------------------------------

### Set up self-hosted profile and list issues with it

Source: https://multica.ai/docs/cli

Creates an isolated profile named 'staging' with custom server and app URLs, then uses that profile to list issues. Named profiles live under ~/.multica/profiles/<name>/config.json and keep separate server address, token, default workspace, and daemon state.

```shell
multica setup self-host --profile staging \
  --server-url https://api.staging.example.com \
  --app-url https://app.staging.example.com

multica issue list --profile staging
```

--------------------------------

### Rerun issue from CLI: multica issue rerun

Source: https://multica.ai/docs/tasks

Reruns the current issue from the CLI. Unlike the manual retry button, this command does not target a specific past run, so it uses the issue's current agent assignee and starts with a fresh session and working directory.

```bash
multica issue rerun <issue-id>
```

--------------------------------

### Set up a worktree for Multica development

Source: https://multica.ai/docs/developers/contributing

Creates a new worktree and sets up the environment for it. `make setup-worktree` generates `.env.worktree` with database name and ports derived from the path.

```bash
git worktree add ../multica-feature -b feat/my-change main
cd ../multica-feature
make setup-worktree
make start-worktree
```

--------------------------------

### Verify migrations with /readyz

Source: https://multica.ai/docs/self-host-quickstart

Check that the database and migrations are healthy after an upgrade. Expect HTTP 200 with both checks 'ok'. Anything else means the new version did not finish migrating.

```bash
curl -s localhost:8080/readyz
# {"status":"ok","checks":{"db":"ok","migrations":"ok"}}
```

--------------------------------

### Minimal desktop.json configuration for self-hosted instance

Source: https://multica.ai/docs/desktop-app

Minimal required configuration: schemaVersion 1 and apiUrl. apiUrl is required and must use http or https. Other URLs are derived automatically. Save in the default locations (see table) and restart Desktop.

```json
{
  "schemaVersion": 1,
  "apiUrl": "https://api.example.com"
}
```

--------------------------------

### Back up Postgres before upgrade (pg_dump to file)

Source: https://multica.ai/docs/self-host-quickstart

Take a dump of the Postgres database before upgrading. Redirects pg_dump output to a file first so its exit status is checked, then compresses with gzip. Use your own POSTGRES_USER/POSTGRES_DB if changed.

```bash
docker compose -f docker-compose.selfhost.yml exec -T postgres \
  pg_dump -U multica multica > multica-backup.sql && gzip multica-backup.sql
```

--------------------------------

### Watch migrations run on backend startup

Source: https://multica.ai/docs/self-host-quickstart

Tail the backend logs to watch migrations run automatically on startup. Migrations run before serving traffic; no separate upgrade command is needed.

```bash
docker compose -f docker-compose.selfhost.yml logs -f backend
```

--------------------------------

### Backend: make commands for server, daemon, tests, migrations, and sqlc

Source: https://multica.ai/docs/developers/contributing

Run the backend server, daemon, tests, database migrations, and generate SQL code. These commands are used for backend development and verification.

```makefile
make server
make daemon
make test
make migrate-up
make migrate-down
make sqlc
```

--------------------------------

### Run backend tests

Source: https://multica.ai/docs/developers/contributing

Run this command for backend changes to execute the Go test suite.

```bash
make test
```

--------------------------------

### Set and show daemon configuration

Source: https://multica.ai/docs/environment-variables

Use 'multica config set' to persist a configuration key and 'multica config show' to display the current configuration. Settings are stored in ~/.multica/config.json or per-profile files.

```bash
multica config set poll_interval 10s
multica config show
```

--------------------------------

### Create agent with multica agent create

Source: https://multica.ai/docs/agents-create

Creates a new agent with a name, runtime, description, instructions, and conversation starters. Avoid putting secrets in arguments as they appear in shell history; use stdin or permission-restricted files instead.

```bash
multica agent create \
  --name "Frontend Reviewer" \
  --runtime-id <runtime-id> \
  --description "Reviews frontend pull requests" \
  --instructions "Read the diff and tests first; post review conclusions only as issue comments." \
  --conversation-starters '[{"label":"Review a PR","prompt":"Review the most relevant open pull request."}]'
```

--------------------------------

### Architecture diagram: Web/Desktop/Mobile/CLI to Go API to daemon

Source: https://multica.ai/docs/developers/architecture

ASCII diagram showing the flow from clients through the Go API to PostgreSQL and the daemon, which invokes local AI coding tools. Use to understand the high-level system architecture.

```text
Web / Desktop / Mobile / CLI
             │
       HTTP + WebSocket
             │
      Go API ───────── PostgreSQL
             │
      daemon WebSocket
             │
     local daemon ─── AI coding tools
```

--------------------------------

### Run database migrations

Source: https://multica.ai/docs/github-integration

Run this command when upgrading an existing deployment to apply regular database migrations before restarting the API server.

```bash
make migrate-up
```

--------------------------------

### Signup allowlist configuration

Source: https://multica.ai/docs/auth-setup

Common configurations for restricting signup by email domain and allowing an external collaborator. Both allowlists also work as an explicit exception list when ALLOW_SIGNUP=false.

```plaintext
# Company domain only
ALLOW_SIGNUP=false
ALLOWED_EMAIL_DOMAINS=company.com

# Also admit one external collaborator
ALLOWED_EMAILS=partner@example.net
```

--------------------------------

### Upgrade via make selfhost (equivalent to manual commands)

Source: https://multica.ai/docs/self-host-quickstart

Alternative upgrade method that runs the same docker compose pull and up -d, and additionally creates .env when missing and waits on /health. Produces the same result as the manual commands.

```bash
cd multica
git pull
make selfhost
```

--------------------------------

### Upgrade to latest images (git pull + docker compose pull)

Source: https://multica.ai/docs/self-host-quickstart

Use this to upgrade to the latest published images. Pulls the latest images and recreates containers, then verifies readiness with /readyz.

```bash
git pull --ff-only
docker compose -f docker-compose.selfhost.yml pull
docker compose -f docker-compose.selfhost.yml up -d
curl -fsS http://localhost:8080/readyz
```

--------------------------------

### PowerShell command to safely create desktop.json

Source: https://multica.ai/docs/desktop-app

Creates desktop.json in one step to avoid Notepad appending .txt and PowerShell writing UTF-16/BOM. Requires restarting Desktop after saving.

```powershell
$dir = "$env:USERPROFILE\.multica"
New-Item -ItemType Directory -Force $dir | Out-Null
$json = @'
{
  "schemaVersion": 1,
  "apiUrl": "https://api.example.com"
}
'@
[System.IO.File]::WriteAllText("$dir\desktop.json", $json)
```

--------------------------------

### Expected /readyz response

Source: https://multica.ai/docs/self-host-quickstart

This is the expected JSON response from the /readyz endpoint, indicating the database and migrations are ok.

```json
{"status":"ok","checks":{"db":"ok","migrations":"ok"}}
```

--------------------------------

### List and switch workspaces

Source: https://multica.ai/docs/cli

Lists available workspaces and switches the default workspace. Subsequent commands use the selected workspace unless overridden with --workspace-id or the MULTICA_WORKSPACE_ID environment variable.

```bash
multica workspace list
multica workspace switch <slug>
```

--------------------------------

### Check self-hosted service health endpoints

Source: https://multica.ai/docs/troubleshooting

For self-hosted instances, check the service directly. /health only indicates the API process is responding, while /readyz also checks the database and migrations.

```bash
curl -i https://api.example.com/health
curl -i https://api.example.com/readyz
```

--------------------------------

### Recreate containers and verify remote access

Source: https://multica.ai/docs/self-host-quickstart

After editing .env, run these commands to recreate containers so the new configuration takes effect, then verify the API and daemon server URL.

```bash
docker compose -f docker-compose.selfhost.yml up -d
curl -fsS https://api.example.com/readyz
curl -fsS https://app.example.com/api/config | grep -o '"daemon_server_url":"[^"]*"'
```

--------------------------------

### Upgrade via manual docker compose commands (equivalent to make selfhost)

Source: https://multica.ai/docs/self-host-quickstart

Manual upgrade method that produces the same result as make selfhost. Pulls the latest images and recreates containers.

```bash
cd multica
git pull
docker compose -f docker-compose.selfhost.yml pull
docker compose -f docker-compose.selfhost.yml up -d
```

--------------------------------

### Check daemon connection status and logs

Source: https://multica.ai/docs/troubleshooting

Run these first when the daemon fails to connect. They check authentication, daemon status in JSON, and the last 100 lines of daemon logs.

```bash
multica auth status
multica daemon status --output json
multica daemon logs --lines 100
```

--------------------------------

### Checkout matching release tag

Source: https://multica.ai/docs/self-host-quickstart

Fetch tags and check out the newest release tag so built binaries and running containers stay on the same version. Needed when building from the checkout, e.g., the CLI or via `make selfhost-build`.

```bash
git fetch --tags --depth 1
git checkout $(git tag -l 'v*' --sort=-v:refname | head -1)
```

--------------------------------

### Manage agents and skills

Source: https://multica.ai/docs/cli

Lists, retrieves, creates, updates, and imports agents and skills. Includes adding skills to an agent.

```bash
multica agent list
multica agent get <agent-id>
multica agent create --help
multica agent update <agent-id> --help

multica skill list
multica skill get <skill-id>
multica skill import --url <skill-url>
multica agent skills add <agent-id> --skill-ids <skill-id>
```

--------------------------------

### Typecheck Docs-only changes

Source: https://multica.ai/docs/developers/contributing

Run this command for documentation-only changes to verify the docs package typechecks.

```bash
pnpm --filter @multica/docs typecheck
```

--------------------------------

### Common admin commands (docker compose -f docker-compose.selfhost.yml)

Source: https://multica.ai/docs/self-host-quickstart

Run these from the multica repository directory to check status, tail backend logs, apply .env changes, or stop services while keeping volumes.

```bash
# Check status
docker compose -f docker-compose.selfhost.yml ps

# Tail backend logs
docker compose -f docker-compose.selfhost.yml logs -f backend

# Apply .env changes
docker compose -f docker-compose.selfhost.yml up -d

# Stop the services, keeping the volumes
docker compose -f docker-compose.selfhost.yml down
```

--------------------------------

### Show current profile configuration

Source: https://multica.ai/docs/cli

Prints the active configuration values, or those of a named profile when --profile staging is given. Useful for inspecting the configured server address, token, default workspace, and daemon state.

```shell
multica config show
multica config show --profile staging
```

--------------------------------

### Typecheck and test shared frontend changes

Source: https://multica.ai/docs/developers/contributing

Run these commands for changes to shared frontend code to typecheck and run unit tests.

```bash
pnpm typecheck
```

```bash
pnpm test
```

--------------------------------

### Multica CLI login with token prompt

Source: https://multica.ai/docs/auth-tokens

Use this command on a machine without a browser. The CLI prompts for a PAT created on the web.

```bash
multica login --token
```

--------------------------------

### Check container status with docker compose ps

Source: https://multica.ai/docs/self-host-quickstart

Run this command to verify the self-hosted services are up. `postgres` should show `healthy`, and `backend` and `frontend` should be running.

```bash
docker compose -f docker-compose.selfhost.yml ps
```

--------------------------------

### Import a skill from the CLI: multica skill import

Source: https://multica.ai/docs/skills

Use this command to import a skill archive from the command line. The archive format matches the one used by the app. If a skill with the same name already exists, the import can stop, overwrite, save under a new name, or skip; overwriting via import is limited to the skill's creator.

```bash
multica skill import --file ./review-helper.skill
```

--------------------------------

### Set GitHub App ID and private key environment variables

Source: https://multica.ai/docs/github-integration

Required for the PR card to show CI status and mergeability. Without them, the integration degrades gracefully but the PR card shows no CI or merge state.

```bash
GITHUB_APP_ID=<the GitHub App's numeric ID>
GITHUB_APP_PRIVATE_KEY=<full PEM private key, keeping the BEGIN/END lines and newlines>
```

--------------------------------

### Agent Instructions for Multica Helper

Source: https://multica.ai/docs/tutorial

Instructions provided to the agent on every run. States responsibilities and constraints: handle member requests in issues and chat, keep replies short, summarize actions, and avoid touching code or repositories. Ask for clarification if a request is ambiguous.

```text
You are the helper of this workspace.

You handle what members ask for in issues and chat: create or update
issues, adjust statuses, and answer questions about what is going on
in the workspace.

Keep replies short. After finishing something, reply with a one-line
summary of what you did. Do not touch code or repositories. If a
request is ambiguous, ask before acting.
```

--------------------------------

### Check Multica version, auth, daemon status, and logs

Source: https://multica.ai/docs/troubleshooting

Run these commands to surface the first meaningful error when diagnosing connection, execution, realtime, email, or self-hosted issues. The daemon status command outputs JSON, and the logs command shows the last 100 lines.

```bash
multica version
multica auth status
multica daemon status --output json
multica daemon logs --lines 100
```

--------------------------------

### Enable VCS integration

Source: https://multica.ai/docs/vcs-integration

Set this environment variable to enable the VCS integration feature. It is off by default, so the section remains hidden until set.

```plaintext
MULTICA_VCS_INTEGRATION_ENABLED=true
```

--------------------------------

### Set MULTICA_*_SECRET_KEY environment variables

Source: https://multica.ai/docs/channels

Configure a 32-byte base64-encoded encryption key for each platform (Lark, Slack, DingTalk, WeCom, Telegram) before Multica opens its connection entry point. These keys encrypt stored Bot credentials.

```bash
MULTICA_LARK_SECRET_KEY=<base64-encoded 32-byte key>
MULTICA_SLACK_SECRET_KEY=<base64-encoded 32-byte key>
MULTICA_DINGTALK_SECRET_KEY=<base64-encoded 32-byte key>
MULTICA_WECOM_SECRET_KEY=<base64-encoded 32-byte key>
MULTICA_TELEGRAM_SECRET_KEY=<base64-encoded 32-byte key>
```

--------------------------------

### Create an issue with /issue command

Source: https://multica.ai/docs/lark-bot-integration

Send this message to the Bot to create an issue. The first line becomes the title and the rest becomes the description. Sending /issue alone creates nothing; the Bot replies with the required format instead.

```plaintext
/issue Fix the redirect after login
Safari stays on the login page after a successful sign-in.
```

--------------------------------

### Configure self-hosted instance API URL

Source: https://multica.ai/docs/mobile-app

Edit apps/mobile/.env.production to set the API address. EXPO_PUBLIC_API_URL is required; EXPO_PUBLIC_WEB_URL is optional and powers 'Copy link' and 'Open on web' menu items.

```bash
EXPO_PUBLIC_API_URL=https://api.example.com
EXPO_PUBLIC_WEB_URL=https://app.example.com
```

--------------------------------

### Create Slack app from manifest (YAML)

Source: https://multica.ai/docs/slack-bot-integration

Paste this YAML manifest into Slack API Apps when creating a new app from a manifest. Replace both occurrences of 'Multica' with the agent's name before creating. Do not remove scopes or events, or DMs, channel mentions, replies, /issue, /new, or /clear may stop working. The app uses Socket Mode, so no public Request URL or OAuth Redirect URL is needed.

```yaml
display_information:
  name: Multica
features:
  app_home:
    home_tab_enabled: false
    messages_tab_enabled: true
    messages_tab_read_only_enabled: false
  bot_user:
    display_name: Multica
    always_online: true
  slash_commands:
    - command: /issue
      description: Create a Multica issue
      usage_hint: "[description]"
    - command: /new
      description: Start a new Multica chat
      usage_hint: "[message]"
    - command: /clear
      description: Clear the current Multica chat context
      usage_hint: "[message]"
oauth_config:
  scopes:
    bot:
      - app_mentions:read
      - channels:history
      - files:read
      - groups:history
      - im:history
      - mpim:history
      - chat:write
      - reactions:write
      - users:read
      - commands
settings:
  event_subscriptions:
    bot_events:
      - app_mention
      - message.im
      - message.channels
      - message.groups
      - message.mpim
  interactivity:
    is_enabled: false
  org_deploy_enabled: false
  socket_mode_enabled: true
  token_rotation_enabled: false
```

--------------------------------

### Argument ordering template

Source: https://multica.ai/docs/daemon-runtimes

Shows the order of arguments in a custom runtime command: your command, your fixed arguments, Multica's protocol arguments, then the agent's custom arguments. This order is what enables subcommand-style wrappers.

```text
<your command> <your fixed arguments> <Multica's protocol arguments> <the agent's custom arguments>
```

--------------------------------

### Multica CLI config file paths

Source: https://multica.ai/docs/auth-tokens

The CLI saves the PAT to the current profile's config file. The paths shown are for the global config and per-profile config.

```text
~/.multica/config.json
~/.multica/profiles/<name>/config.json
```

--------------------------------

### Multica CLI commands for managing project resources

Source: https://multica.ai/docs/project-resources

Commands to link repositories and local directories, update execution modes, and remove resources. Resource changes affect runs created afterwards, not existing runs.

```bash
# Link a repository when creating a project
multica project create \
  --title "Agent UX" \
  --repo https://github.com/multica-ai/multica

# List and add resources
multica project resource list <project-id>
multica project resource add <project-id> \
  --type github_repo \
  --url https://github.com/multica-ai/multica \
  --ref main

# Link a local directory on a specific daemon
multica project resource add <project-id> \
  --type local_directory \
  --local-path /absolute/path/to/repo \
  --daemon-id <daemon-id>

# Link a local git repo and let runs execute concurrently in their own worktrees
multica project resource add <project-id> \
  --type local_directory \
  --local-path /absolute/path/to/repo \
  --daemon-id <daemon-id> \
  --execution-mode worktree

# Switch an existing local directory between modes
multica project resource update <project-id> <resource-id> --execution-mode worktree
multica project resource update <project-id> <resource-id> --execution-mode in_place

# Remove a resource
multica project resource remove <project-id> <resource-id>
```

--------------------------------

### Common issue operations

Source: https://multica.ai/docs/cli

Covers viewing, searching, creating, updating, assigning, commenting, and running issues. Includes commands for listing comments, adding comments, updating comments with expected revision, and viewing runs.

```bash
# View and search
multica issue list
multica issue get MUL-123
multica issue search "login failure"

# Create and update
multica issue create --title "Fix login failure"
multica issue status MUL-123 in_progress
multica issue assign MUL-123 --to "Backend Agent"

# Comments and runs
multica issue comment list MUL-123
multica issue comment add MUL-123 --content "Check the regression tests first"
multica issue comment update <comment-id> --expected-revision 2 --content "Check the regression tests and release notes"
multica issue runs MUL-123
```

--------------------------------

### Verify checksum with Get-FileHash

Source: https://multica.ai/docs/desktop-app

Command to compute the SHA256 hash of the downloaded CLI archive for comparison with the published checksums.txt. Use this to verify the file's integrity before adding exclusions.

```powershell
Get-FileHash .\multica-cli-<version>-windows-amd64.zip -Algorithm SHA256
```

--------------------------------

### Sign in and restart the daemon

Source: https://multica.ai/docs/troubleshooting

After checking status and logs, sign in again and restart the daemon to resolve connection issues caused by expired tokens or stale daemon state.

```bash
multica login
multica daemon restart
```

--------------------------------

### Diagnose empty Usage page with SQL queries

Source: https://multica.ai/docs/troubleshooting

Check raw usage data, the hourly rollup table, and scheduler execution history to diagnose why the Usage page shows zero. If task_usage has rows but task_usage_hourly is empty and the scheduler shows failures, the rollup is not running.

```sql
SELECT count(*) FROM task_usage;
SELECT count(*) FROM task_usage_hourly;

SELECT plan_time, status, error_code, error_msg
FROM sys_cron_executions
WHERE job_name = 'rollup_task_usage_hourly'
ORDER BY plan_time DESC
LIMIT 20;
```

--------------------------------

### Create squad and add member via multica CLI

Source: https://multica.ai/docs/squads

CLI commands to create a squad and add a member. The create command specifies a squad name and leader; the add command requires a squad ID, member ID, type, and role. Full command details are in the 'Using the CLI' section.

```bash
multica squad create --name "Product Delivery" --leader delivery-lead
multica squad member add <squad-id> \
  --member-id <agent-or-member-id> \
  --type agent \
  --role "Owns frontend implementation"
```

--------------------------------

### Recreate containers after .env changes

Source: https://multica.ai/docs/troubleshooting

Recreate self-hosted containers after changing .env, since containers read .env only at creation time.

```bash
docker compose -f docker-compose.selfhost.yml up -d
```

--------------------------------

### Set bundle identifier for signing failures

Source: https://multica.ai/docs/mobile-app

If Xcode reports 'No matching provisioning profiles found', set a reverse-domain name you control and rebuild. The value only needs to be available in your Apple Developer team.

```bash
export EXPO_BUNDLE_IDENTIFIER_PROD=com.yourname.multica
pnpm ios:mobile:device:prod:release
```

--------------------------------

### Set path override with 'multica runtime profile set-path'

Source: https://multica.ai/docs/daemon-runtimes

Sets an absolute path for a profile on the current computer, useful when a Desktop-launched daemon cannot find a command your terminal can run. Replace <profile-id> and the path with your values.

```bash
multica runtime profile set-path <profile-id> --path /absolute/path/to/command
```

--------------------------------

### Run full check before submitting

Source: https://multica.ai/docs/developers/contributing

Run this command before submitting to execute all checks: TypeScript typechecking, unit tests, Go tests, and Playwright E2E.

```bash
make check
```

--------------------------------

### Caddy reverse proxy for separate app and API domains

Source: https://multica.ai/docs/self-host-quickstart

Use this Caddyfile to proxy the app and API domains. It routes WebSockets and daemon connections to the backend, and everything else to the frontend.

```caddyfile
app.example.com {
    # Hand browser WebSockets straight to the backend
    @ws path /ws /ws/*
    handle @ws {
        reverse_proxy 127.0.0.1:8080 {
            flush_interval -1
        }
    }

    # Everything else goes to the frontend, which forwards API and login requests
    handle {
        reverse_proxy 127.0.0.1:3000
    }
}

api.example.com {
    reverse_proxy 127.0.0.1:8080 {
        flush_interval -1
    }
}
```

--------------------------------

### Caddy reverse proxy for single origin

Source: https://multica.ai/docs/self-host-quickstart

Use this Caddyfile to serve everything on a single origin. It explicitly routes /health, /ws, and /api/daemon/ws to the backend, and everything else to the frontend.

```caddyfile
multica.example.com {
    # CLI reachability probe: `multica setup` GETs <server-url>/health and
    # needs a 200 — older web releases don't forward it, so route it directly
    handle /health {
        reverse_proxy 127.0.0.1:8080
    }

    # Browser realtime WebSocket — the web image cannot proxy WS upgrades
    handle /ws {
        reverse_proxy 127.0.0.1:8080 {
            flush_interval -1
        }
    }

    # Daemon long-connection WebSocket: daemons dial {server-url}/api/daemon/ws
    # (not /ws). Without this route the handshake fails and the daemon silently
    # falls back to polling
    handle /api/daemon/ws {
        reverse_proxy 127.0.0.1:8080 {
            flush_interval -1
        }
    }

    # Everything else goes to the frontend, which forwards API and login requests
    handle {
        reverse_proxy 127.0.0.1:3000
    }
}
```

--------------------------------

### Check Multica daemon status

Source: https://multica.ai/docs/self-host-quickstart

Confirms the daemon is running and lists agents and workspaces. The output should show 'Daemon: running', agents, and workspaces greater than 0.

```bash
multica daemon status
```

--------------------------------

### Quarantined file path

Source: https://multica.ai/docs/desktop-app

The path to the bundled CLI that Windows Defender may flag and quarantine. The path is typically `C:\Users\<you>\AppData\Local\Programs\@multicadesktop\resources\app.asar.unpacked\resources\bin\multica.exe`.

```text
C:\Users\<you>\AppData\Local\Programs\@multicadesktop\resources\app.asar.unpacked\resources\bin\multica.exe
```

--------------------------------

### Handle skill import conflicts

Source: https://multica.ai/docs/cli

When importing a skill with a name that already exists, the default is to stop without modifying existing content. Use --on-conflict to choose overwrite, rename, or skip. Overwrite is only allowed for the skill's creator and preserves the original ID and agent bindings.

```bash
multica skill import --url <skill-url> --on-conflict overwrite
multica skill import --url <skill-url> --on-conflict rename
multica skill import --url <skill-url> --on-conflict skip
```

--------------------------------

### Request flow: router to PostgreSQL

Source: https://multica.ai/docs/developers/architecture

Shows the typical request flow through the backend layers, from the router through middleware, handler, service, and sqlc query to PostgreSQL.

```text
router → middleware → handler → service → sqlc query → PostgreSQL
```

--------------------------------

### Check email service mode in backend logs

Source: https://multica.ai/docs/troubleshooting

Inspect the backend startup log to see which email mode is active (SMTP relay, Resend API, or DEV mode). In DEV mode, no email is sent; codes and links are only written to the log.

```bash
docker compose -f docker-compose.selfhost.yml logs backend \
  | grep "EmailService:"
```

--------------------------------

### Refresh a skill via CLI

Source: https://multica.ai/docs/skills

Use the `multica skill refresh` command to update a skill from its hosted source. This re-downloads the skill, preserving identity (agent assignments, labels, creator, creation date) while replacing name, description, SKILL.md, and supporting files. Local edits are overwritten.

```bash
multica skill refresh <skill-id>
```

--------------------------------

### Read verification code from backend logs

Source: https://multica.ai/docs/self-host-quickstart

When no email service is configured, retrieve the verification code from the backend logs after requesting a code. The command greps the logs for 'Verification code'.

```bash
docker compose -f docker-compose.selfhost.yml logs backend \
  | grep "Verification code"
```

--------------------------------

### Set GitHub App environment variables

Source: https://multica.ai/docs/github-integration

Required environment variables for the GitHub App slug, webhook secret, and frontend origin. Missing slug or webhook secret disables the connect button and webhook processing.

```bash
GITHUB_APP_SLUG=multica-acme
GITHUB_WEBHOOK_SECRET=<the webhook secret you entered when creating the App>
FRONTEND_ORIGIN=https://multica.example.com
```

--------------------------------

### Minimum production configuration environment variables

Source: https://multica.ai/docs/environment-variables

Required environment variables for a production Multica deployment. DATABASE_URL, JWT_SECRET, APP_ENV, FRONTEND_ORIGIN, MULTICA_APP_URL, and MULTICA_PUBLIC_URL must be set. JWT_SECRET is mandatory in production; the backend refuses to boot if it is empty or a known placeholder. Generate one with `openssl rand -hex 32`. Do not set MULTICA_DEV_VERIFICATION_CODE.

```plaintext
DATABASE_URL=postgres://user:password@postgres:5432/multica?sslmode=require
JWT_SECRET=<long-random-secret>
APP_ENV=production
FRONTEND_ORIGIN=https://multica.example.com
MULTICA_APP_URL=https://multica.example.com
MULTICA_PUBLIC_URL=https://api.multica.example.com

```

--------------------------------

### Invite workspace members

Source: https://multica.ai/docs/cli

Invites members to the current workspace. Use --role admin to grant the admin role; the default role is not specified.

```bash
multica workspace member invite teammate@example.com
multica workspace member invite admin@example.com --role admin
```

--------------------------------

### SMTP email configuration

Source: https://multica.ai/docs/auth-setup

Minimum SMTP configuration for sending verification codes. SMTP_PORT=587 enables STARTTLS by default when supported; SMTP_FROM_EMAIL falls back to RESEND_FROM_EMAIL if unset.

```plaintext
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=multica
SMTP_PASSWORD=<password>
SMTP_FROM_EMAIL=noreply@example.com
```

--------------------------------

### Generate encryption key with openssl

Source: https://multica.ai/docs/dingtalk-bot-integration

Generate a base64-encoded 32-byte key using openssl rand. Use the output as the value for MULTICA_DINGTALK_SECRET_KEY.

```bash
openssl rand -base64 32
```

--------------------------------

### Set VCS secret key

Source: https://multica.ai/docs/vcs-integration

Set this environment variable to the base64-encoded 32-byte key generated with the openssl command. Without it, the connect form is disabled.

```plaintext
MULTICA_VCS_SECRET_KEY=<base64 32-byte key>
```