mirror of
https://github.com/multica-ai/multica.git
synced 2026-06-17 03:38:32 +02:00
3708fb0f07
Active long-running sessions are no longer killed by a fixed wall-clock deadline. Liveness is delegated to the idle watchdog (MULTICA_AGENT_IDLE_WATCHDOG, default 30m) with a larger in-flight-tool budget (MULTICA_AGENT_TOOL_WATCHDOG, default 2h). MULTICA_AGENT_TIMEOUT is an opt-in absolute cap (default 0 = no cap). The server-side 2.5h sweeper is unchanged as a coarse backstop. Fixes #3745.
432 lines
13 KiB
Plaintext
432 lines
13 KiB
Plaintext
---
|
||
title: CLI Reference
|
||
description: Complete command reference for the Multica CLI and agent daemon.
|
||
---
|
||
|
||
The `multica` CLI connects your local machine to Multica. It handles authentication, workspace management, issue tracking, and runs the agent daemon that executes AI tasks locally.
|
||
|
||
## Authentication
|
||
|
||
### Browser Login
|
||
|
||
```bash
|
||
multica login
|
||
```
|
||
|
||
Opens your browser for OAuth authentication, creates a 90-day personal access token, and auto-configures your workspaces.
|
||
|
||
### Token Login
|
||
|
||
```bash
|
||
multica login --token <mul_...>
|
||
```
|
||
|
||
Authenticate using a personal access token directly. Useful for headless environments. Pass `--token=` with an empty value to be prompted interactively (so the token never lands in shell history).
|
||
|
||
### Check Status
|
||
|
||
```bash
|
||
multica auth status
|
||
```
|
||
|
||
Shows your current server, user, and token validity.
|
||
|
||
### Logout
|
||
|
||
```bash
|
||
multica auth logout
|
||
```
|
||
|
||
Removes the stored authentication token.
|
||
|
||
## Agent Daemon
|
||
|
||
The daemon is the local agent runtime. It detects available AI CLIs on your machine, registers them with the Multica server, and executes tasks when agents are assigned work.
|
||
|
||
### Start
|
||
|
||
```bash
|
||
multica daemon start
|
||
```
|
||
|
||
By default, the daemon runs in the background and logs to `~/.multica/daemon.log`.
|
||
|
||
To run in the foreground (useful for debugging):
|
||
|
||
```bash
|
||
multica daemon start --foreground
|
||
```
|
||
|
||
### Stop
|
||
|
||
```bash
|
||
multica daemon stop
|
||
```
|
||
|
||
### Status
|
||
|
||
```bash
|
||
multica daemon status
|
||
multica daemon status --output json
|
||
```
|
||
|
||
Shows PID, uptime, detected agents, and watched workspaces.
|
||
|
||
### Logs
|
||
|
||
```bash
|
||
multica daemon logs # Last 50 lines
|
||
multica daemon logs -f # Follow (tail -f)
|
||
multica daemon logs -n 100 # Last 100 lines
|
||
```
|
||
|
||
### Supported Agents
|
||
|
||
The daemon auto-detects these AI CLIs on your PATH:
|
||
|
||
| CLI | Command | Description |
|
||
|-----|---------|-------------|
|
||
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `claude` | Anthropic's coding agent |
|
||
| [Codex](https://github.com/openai/codex) | `codex` | OpenAI's coding agent |
|
||
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `gemini` | Google's coding agent |
|
||
| OpenCode | `opencode` | Open-source coding agent |
|
||
| OpenClaw | `openclaw` | Open-source coding agent |
|
||
| Hermes | `hermes` | Nous Research coding agent |
|
||
| Kimi | `kimi` | Moonshot coding agent |
|
||
| Kiro CLI | `kiro-cli` | Kiro ACP coding agent |
|
||
| Pi | `pi` | Inflection coding agent |
|
||
| Cursor Agent | `cursor-agent` | Cursor coding agent |
|
||
|
||
You need at least one installed. The daemon registers each detected CLI as an available runtime.
|
||
|
||
### How It Works
|
||
|
||
1. On start, the daemon detects installed agent CLIs and registers a runtime for each agent in each watched workspace
|
||
2. It polls the server at a configurable interval (default: 3s) for claimed tasks
|
||
3. When a task arrives, it creates an isolated workspace directory, spawns the agent CLI, and streams results back
|
||
4. Heartbeats are sent periodically (default: 15s) so the server knows the daemon is alive
|
||
5. On shutdown, all runtimes are deregistered
|
||
|
||
### Configuration
|
||
|
||
Daemon behavior is configured via flags or environment variables:
|
||
|
||
| Setting | Flag | Env Variable | Default |
|
||
|---------|------|--------------|---------|
|
||
| Poll interval | `--poll-interval` | `MULTICA_DAEMON_POLL_INTERVAL` | `3s` |
|
||
| Heartbeat interval | `--heartbeat-interval` | `MULTICA_DAEMON_HEARTBEAT_INTERVAL` | `15s` |
|
||
| Agent timeout | `--agent-timeout` | `MULTICA_AGENT_TIMEOUT` | `0`（不限制，由看门狗兜底）|
|
||
| Max concurrent tasks | `--max-concurrent-tasks` | `MULTICA_DAEMON_MAX_CONCURRENT_TASKS` | `20` |
|
||
| Daemon ID | `--daemon-id` | `MULTICA_DAEMON_ID` | hostname |
|
||
| Device name | `--device-name` | `MULTICA_DAEMON_DEVICE_NAME` | hostname |
|
||
| Runtime name | `--runtime-name` | `MULTICA_AGENT_RUNTIME_NAME` | `Local Agent` |
|
||
| Workspaces root | — | `MULTICA_WORKSPACES_ROOT` | `~/multica_workspaces` |
|
||
|
||
Agent-specific overrides:
|
||
|
||
| Variable | Description |
|
||
|----------|-------------|
|
||
| `MULTICA_CLAUDE_PATH` | Custom path to the `claude` binary |
|
||
| `MULTICA_CLAUDE_MODEL` | Override the Claude model used |
|
||
| `MULTICA_CODEX_PATH` | Custom path to the `codex` binary |
|
||
| `MULTICA_CODEX_MODEL` | Override the Codex model used |
|
||
| `MULTICA_OPENCODE_PATH` | Custom path to the `opencode` binary |
|
||
| `MULTICA_OPENCODE_MODEL` | Override the OpenCode model used |
|
||
| `MULTICA_OPENCLAW_PATH` | Custom path to the `openclaw` binary |
|
||
| `MULTICA_OPENCLAW_MODEL` | Override the OpenClaw model used |
|
||
| `MULTICA_HERMES_PATH` | Custom path to the `hermes` binary |
|
||
| `MULTICA_HERMES_MODEL` | Override the Hermes model used |
|
||
| `MULTICA_GEMINI_PATH` | Custom path to the `gemini` binary |
|
||
| `MULTICA_GEMINI_MODEL` | Override the Gemini model used |
|
||
| `MULTICA_PI_PATH` | Custom path to the `pi` binary |
|
||
| `MULTICA_PI_MODEL` | Override the Pi model used |
|
||
| `MULTICA_CURSOR_PATH` | Custom path to the `cursor-agent` binary |
|
||
| `MULTICA_CURSOR_MODEL` | Override the Cursor model used |
|
||
| `MULTICA_KIMI_PATH` | Custom path to the `kimi` binary |
|
||
| `MULTICA_KIMI_MODEL` | Override the Kimi model used |
|
||
| `MULTICA_KIRO_PATH` | Custom path to the `kiro-cli` binary |
|
||
| `MULTICA_KIRO_MODEL` | Override the Kiro model used |
|
||
|
||
### Self-Hosted Server
|
||
|
||
When connecting to a self-hosted Multica instance, point the CLI to your server before logging in:
|
||
|
||
```bash
|
||
export MULTICA_APP_URL=https://app.example.com
|
||
export MULTICA_SERVER_URL=wss://api.example.com/ws
|
||
|
||
multica login
|
||
multica daemon start
|
||
```
|
||
|
||
Or set them persistently:
|
||
|
||
```bash
|
||
multica config set app_url https://app.example.com
|
||
multica config set server_url wss://api.example.com/ws
|
||
```
|
||
|
||
### Profiles
|
||
|
||
Profiles let you run multiple daemons on the same machine — for example, one for production and one for a staging server.
|
||
|
||
```bash
|
||
# Set up a staging profile
|
||
multica setup self-host --profile staging --server-url https://api-staging.example.com --app-url https://staging.example.com
|
||
|
||
# Start its daemon
|
||
multica daemon start --profile staging
|
||
|
||
# Default profile runs separately
|
||
multica daemon start
|
||
```
|
||
|
||
Each profile gets its own config directory (`~/.multica/profiles/<name>/`), daemon state, health port, and workspace root.
|
||
|
||
## Workspaces
|
||
|
||
### List Workspaces
|
||
|
||
```bash
|
||
multica workspace list
|
||
```
|
||
|
||
Watched workspaces are marked with `*`. The daemon only processes tasks for watched workspaces.
|
||
|
||
### Watch / Unwatch
|
||
|
||
```bash
|
||
multica workspace watch <workspace-id>
|
||
multica workspace unwatch <workspace-id>
|
||
```
|
||
|
||
### Get Details
|
||
|
||
```bash
|
||
multica workspace get <workspace-id>
|
||
multica workspace get <workspace-id> --output json
|
||
```
|
||
|
||
### List Members
|
||
|
||
```bash
|
||
multica workspace member list <workspace-id>
|
||
```
|
||
|
||
### Update Workspace
|
||
|
||
需要 admin 或 owner 权限。所有字段都是部分更新（PATCH 语义）：未传的字段保持不变。
|
||
|
||
```bash
|
||
multica workspace update <workspace-id> --name "Acme Eng"
|
||
multica workspace update <workspace-id> \
|
||
--description "Engineering team workspace" \
|
||
--issue-prefix ENG
|
||
```
|
||
|
||
长文本走 stdin（保留换行/反斜杠）：
|
||
|
||
```bash
|
||
cat <<'CTX' | multica workspace update <workspace-id> --context-stdin
|
||
我们是一支 5 人 AI-native 团队。
|
||
工作语言：中文 + 英文混合。
|
||
CTX
|
||
```
|
||
|
||
可编辑字段：`--name`、`--description` / `--description-stdin`、`--context` / `--context-stdin`、`--issue-prefix`。`slug` 创建后只读，不暴露在 CLI。`--description` 与 `--description-stdin`（以及 `context` 同名对）互斥。未传任何字段 flag 时命令拒绝执行，避免空 PATCH 触发无意义的 workspace 更新事件。`--issue-prefix ""` 也会被拒绝：当前后端在 prefix 为空时静默跳过该字段，CLI 在本地拦下避免“看似成功的 no-op”。
|
||
|
||
## Issues
|
||
|
||
### List Issues
|
||
|
||
```bash
|
||
multica issue list
|
||
multica issue list --status in_progress
|
||
multica issue list --priority urgent --assignee "Agent Name"
|
||
multica issue list --assignee-id 5fb87ac7-23b5-4a7a-81fa-ed295a54545d
|
||
multica issue list --full-id
|
||
multica issue list --limit 20 --output json
|
||
```
|
||
|
||
表格输出默认显示可直接复制到后续命令的 issue `KEY`（例如 `MUL-123`）；需要完整 UUID 时使用 `--full-id`。Available filters: `--status`, `--priority`, `--assignee` / `--assignee-id`, `--project`, `--limit`. 在重名 workspace 下用 `--assignee-id <uuid>` 可以精确锁定一个成员或 agent。
|
||
|
||
### Get Issue
|
||
|
||
```bash
|
||
multica issue get MUL-123
|
||
multica issue get <uuid>
|
||
multica issue get <id> --output json
|
||
```
|
||
|
||
`<id>` 同时接受 issue key（`multica issue list` 表格里直接显示，例如 `MUL-123`）和完整 UUID（给 `list` 加 `--full-id` 可显示）。同样的规则适用于下面 `update` / `assign` / `status` / `comment` / `subscriber` / `runs` 等接受 `<id>` 的命令。
|
||
|
||
### Create Issue
|
||
|
||
```bash
|
||
multica issue create --title "Fix login bug" --description "..." --priority high --assignee "Lambda"
|
||
multica issue create --title "Fix login bug" --assignee-id 5fb87ac7-23b5-4a7a-81fa-ed295a54545d
|
||
```
|
||
|
||
Flags: `--title` (required), `--description`, `--status`, `--priority`, `--assignee` / `--assignee-id`, `--parent`, `--project`, `--due-date`. 脚本里如果已经拿到了 UUID（例如来自 `multica workspace member list --output json`），传 `--assignee-id <uuid>`（与 `--assignee` 互斥）以精确锁定。
|
||
|
||
### Update Issue
|
||
|
||
```bash
|
||
multica issue update <id> --title "New title" --priority urgent
|
||
```
|
||
|
||
### Assign Issue
|
||
|
||
```bash
|
||
multica issue assign <id> --to "Lambda"
|
||
multica issue assign <id> --to-id 5fb87ac7-23b5-4a7a-81fa-ed295a54545d
|
||
multica issue assign <id> --unassign
|
||
```
|
||
|
||
`--to-id <uuid>`（与 `--to` 互斥）按 UUID 精确分配；适合重名 workspace 下脚本化场景。
|
||
|
||
### Change Status
|
||
|
||
```bash
|
||
multica issue status <id> in_progress
|
||
```
|
||
|
||
Valid statuses: `backlog`, `todo`, `in_progress`, `in_review`, `done`, `blocked`, `cancelled`.
|
||
|
||
### Comments
|
||
|
||
```bash
|
||
# List comments
|
||
multica issue comment list <issue-id>
|
||
|
||
# Add a comment
|
||
multica issue comment add <issue-id> --content "Looks good, merging now"
|
||
|
||
# Reply to a specific comment
|
||
multica issue comment add <issue-id> --parent <comment-id> --content "Thanks!"
|
||
|
||
# Delete a comment
|
||
multica issue comment delete <comment-id>
|
||
```
|
||
|
||
### Execution History
|
||
|
||
```bash
|
||
# List all execution runs for an issue
|
||
multica issue runs <issue-id>
|
||
multica issue runs <issue-id> --full-id
|
||
multica issue runs <issue-id> --output json
|
||
|
||
# View messages for a specific execution run
|
||
multica issue run-messages <task-id>
|
||
multica issue run-messages <short-task-id> --issue <issue-id>
|
||
multica issue run-messages <task-id> --output json
|
||
|
||
# Incremental fetch (only messages after a given sequence number)
|
||
multica issue run-messages <task-id> --since 42 --output json
|
||
```
|
||
|
||
`runs` 的表格输出默认显示 task UUID 短前缀；需要完整 task UUID 时使用 `--full-id`。`run-messages` 可直接接受完整 task UUID；从 `runs` 表格复制短前缀时需要同时传 `--issue <issue-id>`，CLI 只会在该 issue 的 runs 内解析。
|
||
|
||
## Projects
|
||
|
||
Projects group related issues (e.g. a sprint, an epic, a workstream). Every project
|
||
belongs to a workspace and can optionally have a lead (member or agent).
|
||
|
||
### List Projects
|
||
|
||
```bash
|
||
multica project list
|
||
multica project list --status in_progress
|
||
multica project list --output json
|
||
```
|
||
|
||
Available filters: `--status`.
|
||
|
||
### Get Project
|
||
|
||
```bash
|
||
multica project get <id>
|
||
multica project get <id> --output json
|
||
```
|
||
|
||
### Create Project
|
||
|
||
```bash
|
||
multica project create --title "2026 Week 16 Sprint" --icon "🏃" --lead "Lambda"
|
||
```
|
||
|
||
Flags: `--title` (required), `--description`, `--status`, `--icon`, `--lead`.
|
||
|
||
### Update Project
|
||
|
||
```bash
|
||
multica project update <id> --title "New title" --status in_progress
|
||
multica project update <id> --lead "Lambda"
|
||
```
|
||
|
||
Flags: `--title`, `--description`, `--status`, `--icon`, `--lead`.
|
||
|
||
### Change Status
|
||
|
||
```bash
|
||
multica project status <id> in_progress
|
||
```
|
||
|
||
Valid statuses: `planned`, `in_progress`, `paused`, `completed`, `cancelled`.
|
||
|
||
### Delete Project
|
||
|
||
```bash
|
||
multica project delete <id>
|
||
```
|
||
|
||
### Associating Issues with Projects
|
||
|
||
Use the `--project` flag on `issue create` / `issue update` to attach an issue to a
|
||
project, or on `issue list` to filter issues by project:
|
||
|
||
```bash
|
||
multica issue create --title "Login bug" --project <project-id>
|
||
multica issue update <issue-id> --project <project-id>
|
||
multica issue list --project <project-id>
|
||
```
|
||
|
||
## Configuration
|
||
|
||
### View Config
|
||
|
||
```bash
|
||
multica config show
|
||
```
|
||
|
||
Shows config file path, server URL, app URL, and default workspace.
|
||
|
||
### Set Values
|
||
|
||
```bash
|
||
multica config set server_url wss://api.example.com/ws
|
||
multica config set app_url https://app.example.com
|
||
multica config set workspace_id <workspace-id>
|
||
```
|
||
|
||
## Other Commands
|
||
|
||
```bash
|
||
multica version # Show CLI version and commit hash
|
||
multica update # Update to latest version
|
||
multica agent list # List agents in the current workspace
|
||
```
|
||
|
||
## Output Formats
|
||
|
||
Most commands support `--output` with two formats:
|
||
|
||
- `table` — human-readable table (default for list commands)
|
||
- `json` — structured JSON (useful for scripting and automation)
|
||
|
||
```bash
|
||
multica issue list --output json
|
||
multica daemon status --output json
|
||
```
|