CLI Reference

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

multica login

Opens your browser for OAuth authentication, creates a 90-day personal access token, and auto-configures your workspaces.

multica login --token

Authenticate by pasting a personal access token directly. Useful for headless environments.

Check Status

multica auth status

Shows your current server, user, and token validity.

Logout

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

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

multica daemon start --foreground

Stop

multica daemon stop

Status

multica daemon status
multica daemon status --output json

Shows PID, uptime, detected agents, and watched workspaces.

Logs

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	`claude`	Anthropic's coding agent
Codex	`codex`	OpenAI's coding agent
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

You need at least one installed. The daemon registers each detected CLI as an available runtime.

How It Works

On start, the daemon detects installed agent CLIs and registers a runtime for each agent in each watched workspace
It polls the server at a configurable interval (default: 3s) for claimed tasks
When a task arrives, it creates an isolated workspace directory, spawns the agent CLI, and streams results back
Heartbeats are sent periodically (default: 15s) so the server knows the daemon is alive
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`	`2h`
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

Self-Hosted Server

When connecting to a self-hosted Multica instance, point the CLI to your server before logging in:

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:

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.

# 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

multica workspace list

Watched workspaces are marked with *. The daemon only processes tasks for watched workspaces.

Watch / Unwatch

multica workspace watch <workspace-id>
multica workspace unwatch <workspace-id>

Get Details

multica workspace get <workspace-id>
multica workspace get <workspace-id> --output json

List Members

multica workspace members <workspace-id>

Issues

List Issues

multica issue list
multica issue list --status in_progress
multica issue list --priority urgent --assignee "Agent Name"
multica issue list --limit 20 --output json

Available filters: --status, --priority, --assignee, --project, --limit.

Get Issue

multica issue get <id>
multica issue get <id> --output json

Create Issue

multica issue create --title "Fix login bug" --description "..." --priority high --assignee "Lambda"

Flags: --title (required), --description, --status, --priority, --assignee, --parent, --project, --due-date.

Update Issue

multica issue update <id> --title "New title" --priority urgent

Assign Issue

multica issue assign <id> --to "Lambda"
multica issue assign <id> --unassign

Change Status

multica issue status <id> in_progress

Valid statuses: backlog, todo, in_progress, in_review, done, blocked, cancelled.

Comments

# 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

# List all execution runs for an issue
multica issue runs <issue-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 <task-id> --output json

# Incremental fetch (only messages after a given sequence number)
multica issue run-messages <task-id> --since 42 --output json

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

multica project list
multica project list --status in_progress
multica project list --output json

Available filters: --status.

Get Project

multica project get <id>
multica project get <id> --output json

Create Project

multica project create --title "2026 Week 16 Sprint" --icon "🏃" --lead "Lambda"

Flags: --title (required), --description, --status, --icon, --lead.

Update Project

multica project update <id> --title "New title" --status in_progress
multica project update <id> --lead "Lambda"

Flags: --title, --description, --status, --icon, --lead.

Change Status

multica project status <id> in_progress

Valid statuses: planned, in_progress, paused, completed, cancelled.

Delete Project

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:

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

multica config show

Shows config file path, server URL, app URL, and default workspace.

Set Values

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

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)

multica issue list --output json
multica daemon status --output json

本页目录