Using the CLI
Install and log in to the Multica CLI, and manage workspaces, issues, agents, and runtimes from the terminal.
The Multica CLI both connects local runtimes and manages workspaces, issues, agents, and automations from the terminal. This page covers the common paths; the flags your installed version supports are always defined by each command's own --help.
Installation
curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bashWith Homebrew installed, you can also run:
brew install multica-ai/tap/multicaConfirm the install:
multica versionFirst connection
Pick the service you are connecting to:
multica setupsetup saves the server address, opens a browser to complete sign-in, and starts the daemon. When it finishes, check:
multica auth status
multica daemon statusIf you only need to sign in again without overwriting other configuration, run multica login. On a machine without a browser, create a personal access token in the web settings first, then enter it with:
multica login --tokenThe command prompts you to paste the token in the terminal, keeping the full value out of shell history.
Choosing a workspace
List workspaces and switch the default:
multica workspace list
multica workspace switch <slug>Subsequent commands use this workspace. A single command can override it with --workspace-id, or you can set MULTICA_WORKSPACE_ID.
Invite members:
multica workspace member invite teammate@example.com
multica workspace member invite admin@example.com --role adminCommon issue operations
# 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-123Read long descriptions or comments from stdin to avoid dealing with newlines and quoting:
multica issue create --title "Upgrade notes" --description-stdin < notes.md
multica issue comment add MUL-123 --content-stdin < review.md
multica issue comment update <comment-id> --expected-revision 2 --content-file revised-review.mdInspect, stop, or retry a single run:
multica issue run-messages <task-id> --issue MUL-123
multica issue cancel-task <task-id> --issue MUL-123
multica issue rerun-task <run-id> --issue MUL-123
multica issue rerun-task <run-id> --issue MUL-123 --freshAdd a comment to a run that is still working, instead of queueing a follow-up run (only runs that accept additional messages; you can steer an agent exactly when your comment could start it):
multica issue comment add MUL-123 --content-file note.md --steer <task-id>
multica issue comment add MUL-123 --content-file note.md --steer-activeIf an open issue with the same title (case-insensitive, extra spaces ignored) already exists under the same project and parent, issue create refuses and points to that issue. To create another one anyway, add --allow-duplicate. To mark an issue as a duplicate of another, run multica issue status MUL-124 cancelled --duplicate-of MUL-123.
For sequential PR delivery, use issue create --title "..." --pr-auto-complete off or issue update <id> --pr-auto-complete off to keep that issue's status when PRs merge. Use --pr-auto-complete on to restore the workspace rule; this takes effect at the next PR event. issue pull-requests <id> shows the issue override, workspace setting, target status, and decision state, even with no linked PRs. Supported servers save the creation override atomically; older servers receive a follow-up PUT. If that fails, the CLI reports the created issue ID and an update command to retry, so do not repeat the create.
Batch updates
Apply the same change to several issues, or pass one issue key or UUID per line with --ids-stdin:
multica issue batch update MUL-123 MUL-124 --priority high --add-label QA --dry-run
multica issue batch update MUL-123 MUL-124 --priority high --add-label QA
multica issue batch update MUL-123 MUL-124 --property "Severity=High" --unset-property Reviewer--add-label and --remove-label leave other labels alone; --clear-labels clears them before any additions. --property sets a value and --unset-property clears it; multi-value properties are replaced as a whole. Status, assignee, project, dates, parent, and stage are also supported. Add --no-start to apply the change without starting agent runs.
Each issue gets its own result: updated, unchanged, or skipped with a reason. If any issue is skipped, the command prints the results and exits nonzero; successful changes remain. Correct and retry only the skipped issues. --dry-run previews checks and intended changes without writing.
Deleting issues
Delete one issue or pass several issue keys or full UUIDs to delete them in one batch:
multica issue delete MUL-123
multica issue delete MUL-123 MUL-124 --yes --output jsonDeletion is permanent: it removes comments and attachments, cancels in-flight runs, fails linked autopilot runs, clears duplicate marks pointing to the deleted issues, and detaches child issues without deleting them. Every ID is resolved before confirmation; an unknown or inaccessible issue aborts the command before deletion.
The command asks for confirmation. --yes skips the prompt; without it, a non-interactive run that cannot answer fails without deleting anything.
--dry-run checks what would be deleted, including deletion permissions, without writing or asking for confirmation:
multica issue delete MUL-123 MUL-124 --dry-run --output jsonTimeline
issue get shows an issue as it is now. issue timeline lists, in order, the changes to status, priority, assignee, title, and dates and the run outcomes, interleaved with comments, which answers questions like "when did it move to in_review" or "how long has it been stuck in this status":
multica issue timeline MUL-123 --action status_changed
multica issue timeline MUL-123 --activity-only --output json
multica issue timeline MUL-123 --since 2026-08-19T00:00:00Z--activity-only drops comments and keeps every activity record; --action returns only the given actions, is repeatable, and implies --activity-only. The server caps how far back it reads; when the result is truncated, a warning goes to stderr, and durations should not be inferred from it.
Reading long comment threads
On an issue with many comments, reading them one by one costs an agent a lot of tokens. Scan the threads first, then open the one you need:
multica issue comment list MUL-123 --roots-only --summary --output json --compact
multica issue comment list MUL-123 --thread <comment-id> --tail 5 --output json --compact--roots-onlyreturns only top-level comments, each with its reply count and last activity time.--summaryclips each comment to a short preview.--compactapplies to JSON output and drops fields that carry no information (such as the echoedissue_idand empty arrays).--recent Nreturns the N most recently active threads with every reply, which can be long.- Resolved threads are folded to their root and conclusion by default; add
--fullfor the complete text.
Lists can be trimmed to the fields you need, too: multica issue list --output json --fields id,identifier,title,status. The filtering happens in the CLI, so it shrinks output and context, not the request.
To list issues by their last update time, pass both --updated-since and --updated-until as RFC3339 timestamps. The server returns issues whose current updated_at is at or after since and before until: [since, until). These flags work with existing filters, sorting, and pagination. Keep the same bounds across pages; concurrent updates can change the result set because pagination does not provide a snapshot.
multica issue list --updated-since 2026-11-05T10:00:00Z \
--updated-until 2026-11-05T10:01:00Z \
--sort created_at --direction asc --limit 100 --offset 0 \
--output json --fields id,workspace_id,project_id,titleWakeups
A wakeup starts an ordinary run for an agent when an event happens, a condition becomes true, or a time arrives. The full rules are in Issue wakeups.
multica issue wakeup events
multica issue wakeup create MUL-123 --agent-id <agent-id> \
--event comment.created --filter-actor-type member --filter-actor-id <user-id> \
--instruction "When they reply, update the quote from their answer"
multica issue wakeup create MUL-123 --agent-id <agent-id> \
--kind every --every 1h --expires-in 72h \
--instruction "Check whether the supplier has replied"
multica issue wakeup list MUL-123
multica issue wakeup runs MUL-123 <wakeup-id>Creating one from a terminal as a member requires --agent-id; an agent creating one inside its own run wakes itself by default.
Chat wakeups
Only an agent inside a chat run can use chat wakeup; the current conversation is implicit. These commands do not accept a session ID and cannot be used from an ordinary member terminal or an issue run. See Follow up later for the user controls.
multica chat wakeup create --title "Review ready" \
--until-issue MUL-123 --state in_review --expires-in 48h \
--instruction "Summarize the result in this conversation"
multica chat wakeup create --title "Check back in two hours" \
--after 2h --instruction "Remind the user to review the result"
multica chat wakeup listUse exactly one --until-* condition, --at / --after, or --every. Creation and update require --title and --instruction (or --instruction-file). update replaces the configuration and restarts relative deadlines; it cannot switch a wakeup between a condition, a reminder, and a check. Conditions and checks default to 24 hours and allow at most 7 days via --expires-in or --expires-at; reminders allow at most 30 days and do not accept expiry flags. Checks run at least 10 minutes apart, and the deadline may allow at most 100 checks: --every 10m with the default 24 hours would be 144 checks and is rejected, so use a longer interval or an earlier deadline such as --expires-in 16h.
Conditions support --until-issue with --state or --status, --until-children-done with optional --stage, --until-pr, --until-run, and --until-reply with optional --from <user-id>. A PR condition uses a GitHub PR mirrored in this workspace: owner/repo#N[:merged|closed|checks]. checks waits for checks to finish on the current head, whether they pass or fail. A checks condition can be created only when the server reads CI status from GitHub; a self-hosted server needs GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY (see GitHub integration). An already-finished check result at creation is recorded as a baseline and does not immediately wake the agent.
Use list, get <id>, or cancel <id> to inspect or cancel a wakeup. During a periodic check, checkin <id> --note "..." records a quiet update without sending a reply; finish <id> ends the check when its goal is met. The final deadline turn must report back and cannot check in quietly.
Agents and skills
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>When an import hits a skill with the same name, the default is to stop without modifying existing content. Pick by intent:
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 skipoverwrite is only allowed for the skill's creator and preserves the original ID and agent bindings.
Environment variables and MCP configuration often carry tokens. Values typed on the command line stay in shell history and ps output, so pass them through the -file or -stdin forms:
multica agent create --name "Ops helper" --runtime-id <runtime-id> \
--custom-env-file ./agent-env.json \
--mcp-config-file ./mcp.json \
--custom-args '["--max-turns", "40"]'
multica agent env set <agent-id> --custom-env-stdin < agent-env.json
multica agent update <agent-id> --mcp-config-file ./mcp.json- The
--custom-envflags exist only onagent create. Change variables later withagent env set, which replaces the whole set; keys whose value is****keep their existing value. agent update --mcp-config nullclears the MCP configuration.--custom-argsis a JSON array placed at the end of the launch arguments. Choose the model with--model; some tools reject--modelinside custom arguments.--permission-modecontrols who can invoke the agent:privatefor the owner only, orpublic_towith--public-to-workspaceor--public-to-member <user-id>.--visibility private|workspaceis the older form and maps onto--permission-mode; when both are given,--permission-modewins.
Agent run history
multica agent tasks <agent-id> --limit 200 returns the newest page of runs.
The default and maximum page size is 200. If more runs exist, stderr prints a
cursor; pass it unchanged as --before '<cursor>' to read the next page.
--output json keeps the array output and includes usage for that page only.
The corresponding GET /api/agents/{id}/tasks endpoint accepts limit and
before, and keeps its JSON array response. The X-Agent-Tasks-Next-Cursor
response header supplies the next cursor; its absence marks the final page.
Cursors preserve (created_at, id) order, including timestamp precision.
Invalid limits or cursors return HTTP 400; limits above 200 are capped.
Clients that do not follow the cursor receive only the newest 200 runs.
Daemon and runtimes
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>multica daemon autostart enable
multica runtime usage <runtime-id> --days 30
multica runtime update <runtime-id> --target-version <version> --wait
multica runtime profile create --display-name "Internal Claude wrapper" \
--command-name ccms --runtime-type claudedaemon autostart registers the current profile to start at login; see Start at login for platform details. runtime usage covers 90 days by default, and --days goes up to 365. runtime update asks the daemon on that computer to update its CLI to the given version; --wait waits for completion and exits non-zero if the update fails or times out, or if the wait itself times out. runtime profile create takes the compatible tool through --runtime-type (the older --protocol-family still works); fixed arguments can currently be set only in the web app. runtime profile create binds the profile to this machine by default; use --daemon-id <id> to select another registered local machine. Bind an older, unscoped profile with multica runtime profile update <profile-id> --daemon-id <id>.
Deleting a runtime that still has active agents bound to it is refused by default. multica runtime delete <id> --cascade unbinds those agents, preserves their configuration and history, and cancels their active runs.
See Daemon and runtimes for how it works and for custom profiles.
Environments
multica env start web
multica env start web --wait=false
multica env list
multica env stop webmultica env (long form multica environment) starts the environments a repository declares in .multica/environments.toml. The daemon supervises them, so they keep running after the run ends, show in the issue sidebar, and stop at their TTL. start waits until the environment answers and prints its URL. These commands use the running task's credential, so they only work inside an agent run; from your own computer, use the issue sidebar. See Environments for the file format and examples.
Projects, workspaces, and autopilots
multica project create --title "Summer campaign" --lead "Lei Li" \
--repo https://github.com/acme/campaign-site
multica project resource add <project-id> --type github_repo \
--url https://github.com/acme/brand-assets --default-branch-hint main
multica workspace create --name "Operations" --slug ops --issue-prefix OPS
multica workspace update --context-stdin < team-context.md
multica autopilot create --title "Weekly sales report" --agent "Ops helper" \
--mode create_issue --issue-title-template "Sales report {{date}}"
multica autopilot trigger-add <autopilot-id> --cron "0 9 * * 1" --timezone Europe/London--leadtakes the name of a member or an agent.--default-branch-hintonly tells the agent the repository's default branch; it does not switch branches.- A workspace's
--contextis provided to every agent in the workspace.--slugcannot be changed after creation.--issue-prefixis uppercased; changing it renumbers every existing issue, and old identifiers in external references stop resolving. --issue-title-templateinterpolates only{{date}}(UTC,YYYY-MM-DD) and rejects any other{{...}}token. A schedule trigger's--timezonedefaults to UTC.
Webhook event filters
Use --event-filters-file on autopilot trigger-add or trigger-update to configure a webhook trigger's event and action filters. Save a nonempty JSON array as filters.json:
[
{"event": "pull_request_review", "actions": ["submitted"]},
{"event": "push"}
]Each row may also include conditions, using the same payload-field rules as the app. For example, this row accepts only non-draft pull requests targeting main:
{
"event": "pull_request",
"conditions": [
{ "path": "pull_request.draft", "op": "equals", "value": false },
{ "path": "pull_request.base.ref", "op": "equals", "value": "main" }
]
}Each rule supports up to 20 conditions. A field path can contain at most 256 characters, and an in list can contain at most 100 values. Creating or updating a trigger with an oversized condition returns HTTP 400.
This accepts PR review submissions and all push events. Omitting actions or using an empty actions array accepts every action for that event.
multica autopilot trigger-add <autopilot-id> --kind webhook --event-filters-file filters.json
multica autopilot trigger-list <autopilot-id> --full-id
multica autopilot trigger-update <autopilot-id> <trigger-id> --event-filters-file filters.json
multica autopilot get <autopilot-id> --output jsonThe file replaces the entire filter list on update. Omitting both filter options preserves the saved filters, including when updating a label or enabling/disabling the trigger. autopilot get returns the filters in the top-level triggers array.
To remove all filters and accept every event, use the update-only flag:
multica autopilot trigger-update <autopilot-id> <trigger-id> --clear-event-filters--clear-event-filters and --event-filters-file cannot be combined. Top-level null or an empty array, unknown fields, malformed JSON, and blank event/action names are rejected. These options apply only to webhook triggers; creating one without a filter file accepts all events. See Autopilots for how incoming events are matched.
Command overview
| Command | Purpose |
|---|---|
issue | Create, update, assign, and search issues; manage comments, subscribers, labels, properties, wakeups, the timeline, and runs |
project | Manage projects, their resources, and the workflow they use |
inbox | Read and manage your notifications: list, mark read, archive, snooze |
workflow | Manage issue workflows: statuses and who handles each one |
issue-status | Manage the workspace status catalog: statuses, their color, and their icon |
label, property | Manage workspace labels and custom properties |
view | Read saved issue views and list the issues a view shows |
agent, skill, squad | Manage agents, skills, and squads |
autopilot | Manage automations, triggers, and run history |
workspace | Create, view, and switch workspaces, and invite members |
repo | Manage workspace repositories and check them out locally |
daemon, runtime | Start and stop the local daemon; view and manage runtimes |
env | Start, stop, and list the environments a repository declares (inside agent runs only) |
attachment | Upload or download attachments |
user profile | View or update the current user's profile |
auth, login, setup | Log in, check auth status, and initialize a connection |
config | View or edit the current CLI profile's local configuration |
update, version | Update the CLI or print the version |
multica chat reads the external chat session an agent is currently handling; it is mainly for agents in chat integrations, not a general command for browsing arbitrary workspace conversations.
IDs and output formats
Issues use keys like MUL-123 or full UUIDs; short UUID prefixes are not accepted.
list commands for other resources usually print copyable short IDs and support --full-id for the full UUID. When a short ID is ambiguous, the CLI asks for more characters or the full UUID. Short task IDs also require --issue to identify the owning issue.
Many commands support structured output:
multica issue list --output json
multica agent list --output jsonScripts should use JSON output rather than parsing the terminal-oriented tables. The output formats and pagination flags each command supports are defined by multica <command> --help.
Profiles and configuration
The default configuration lives in ~/.multica/config.json. Use --profile <name> to isolate a separate set of server address, token, default workspace, and daemon state:
multica setup self-host --profile staging \
--server-url https://api.staging.example.com \
--app-url https://app.staging.example.com
multica issue list --profile stagingNamed profiles live in ~/.multica/profiles/<name>/config.json. Inspect the current values:
multica config show
multica config show --profile stagingDo not set MULTICA_DAEMON_PORT in the host shell, Compose service, or container entrypoint that starts a daemon. The host daemon normally derives its health port from --profile; if that port cannot be bound, it uses an available loopback port and injects the actual port into agent tasks itself. Remove the variable from older startup environments entirely: versions 0.4.22 and 0.4.23 otherwise mistake that shell for a managed task and reject login. Newer versions let guarded human login and daemon status recover when the port is the only task signal, but ordinary API and profile-resolving commands intentionally remain fail-closed until the variable is removed.
When the CLI runs inside a daemon-managed agent task, it does not load or modify these human-owned profile files. Multica API commands authenticate with the task-scoped credential injected by the daemon. config show and config set use private task-local state; human/local commands such as login, logout, setup, workspace switch, local runtime profile path changes, daemon start / stop / restart, daemon logs, and daemon probe-runtimes are unavailable. auth status does not print token material in this context.
daemon status and daemon disk-usage stay available so an agent can inspect the runtime hosting it, scoped to that runtime: status probes the health port the daemon injected, and disk-usage scans the workspaces root the daemon injected. Neither accepts --profile, disk-usage also rejects --all-profiles and --workspaces-root, and its STATUS column is blank because resolving it would require the human's stored token. Use du and df for anything outside that scope.
This protects implicit Multica CLI profile resolution while preserving the normal HOME and XDG variables used by other provider tools. It is not an OS filesystem boundary: processes running as the same system user may still open an explicitly known path. Use a dedicated user, container, VM, or equivalent isolation when that stronger guarantee is required.
CLI configuration files contain tokens that can access Multica as you. Don't commit them to a repository, upload them to logs, or share them with others.
Command reference
The tables below cover every current top-level command, grouped the way the CLI itself groups them. All commands accept the global flags --server-url, --workspace-id, --profile, and --debug. --output is registered per command, and the default format varies: list commands default to a table, while get and create commands mostly default to JSON. Full flags are defined by multica <command> --help.
Issue attachments
For issue create, issue update, and issue comment add, each --attachment takes one literal file path, including any commas or double quotes in the filename. Repeat the flag for multiple files: --attachment 'report,final.csv' --attachment notes.txt. Omitting the flag attaches no files; an explicitly empty path is an error. All local paths are checked before any file is uploaded.
Migration from CSV parsing: replace --attachment a,b with --attachment a --attachment b to attach two files. The former now selects a single file named a,b. Remove extra CSV quotes from the old workaround --attachment '"report,final.csv"'; use --attachment 'report,final.csv' unless the filename itself contains those double quotes.
Core
| Command | Subcommand | Purpose | Key flags |
|---|---|---|---|
issue | list | List issues | --status, --priority, --assignee, --project, --updated-since / --updated-until (paired RFC3339 bounds), --metadata (repeatable), --property (repeatable, "Name=Value" or a comparison such as "Score>=3", "Due<2026-01-01", "Notes~=text"; __none__ matches unset), --limit, --offset, --sort (incl. property:<name-or-id>), --full-id, --fields (JSON only; comma-separated fields to keep), --resolve-properties (JSON only; rows with property, option and member names beside the stored ids) |
get <id> | Show a single issue | --resolve-properties (JSON only; rows with property, option and member names beside the stored ids) | |
create | Create an issue | --title (required), --description / --description-stdin / --description-file, --pr-auto-complete on/off, --status, --priority, --assignee, --parent, --stage, --project, --start-date, --due-date, --attachment (repeatable), --property (repeatable), --allow-duplicate (create even when an open issue with the same title exists) | |
update <id> | Update issue fields | Same fields as create, plus --position, --no-start, --duplicate-of | |
batch update <id>... | Apply one change to several issues | --ids-stdin, --status, --priority, --assignee / --assignee-id / --unassign, --project, --start-date, --due-date, --parent, --stage, --add-label, --remove-label, --clear-labels, --property, --unset-property, --no-start, --dry-run | |
delete <id>... | Permanently delete one or more issues | --yes skips confirmation; accepts issue keys or full UUIDs; --dry-run | |
assign <id> | Assign or unassign | --to (fuzzy name match against members, agents, and squads), --to-id, --unassign, --no-start | |
status <id> <status> | Change status | --no-start, --duplicate-of | |
reorder <id> | Move within a column | ||
search <query> | Search issues | --limit, --include-closed, --project | |
children <id> | List sub-issues grouped by stage | ||
pull-requests <id> | List linked PRs | ||
pull-requests link <id> <pr-url> | Link a synced PR whose title and branch lack the issue key | Also restores a PR removed with unlink | |
pull-requests unlink <id> <pr> | Remove a linked PR and keep it removed | <pr> is the PR URL, its number, or its id | |
comment list/add/update/delete/resolve/unresolve | Manage comments | add: --content / --content-stdin / --content-file, --parent, --attachment; update: --expected-revision (required), --content / --content-stdin / --content-file; list: --since, --thread, --tail, --recent, --roots-only, --summary, --compact, --full | |
timeline <id> | List activity records and comments in time order | --action (repeatable), --activity-only, --since, --tail | |
wakeup events/list/get/create/update/disable/trigger/delete/checkin/runs | Manage issue wakeups; see Issue wakeups | create / update: --agent-id, --kind (event, at, every, cron), --event, --at / --after, --every, --cron, --timezone, --until-* conditions, --expires-in / --expires-at, --instruction / --instruction-file; checkin: --note | |
subscriber list/add/remove <issue-id> | Manage subscribers | --user, --user-id (defaults to the current user) | |
label list/add/remove <issue-id> | Manage labels on an issue | ||
metadata list/get/set/delete <issue-id> | Manage issue-level key-value metadata | ||
property list/set/unset <issue-id> | Set custom property values | set: --name, --value (actor / multi_actor accept a member name, email, or id) | |
runs <issue-id> | View run history | --full-id | |
run-messages <task-id> | View the messages of a single run | --since, --issue | |
usage <issue-id> | View aggregated token usage | ||
rerun-task <run-id> | Repeat a specific run with its original agent and trigger context | --issue, --fresh | |
cancel-task <task-id> | Cancel a running or queued run | --issue | |
project | get/create/update/delete | Manage projects | create: --title (required), --lead, --status, --icon, --start-date, --due-date, --repo (repeatable), --visibility (workspace or private), --member (repeatable, with --visibility private); update: --visibility, --member (adds the members whether the project is becoming private or already is) |
list | List and filter projects | --status, --priority, --lead, --search, --archived, --sort (name, priority, status, progress, start_date, due_date, created_at, last_activity_at), --direction (asc / desc), --limit (1–200), --offset | |
status <id> <status> | Change project status | ||
archive/restore <id> | Archive or restore a project. Archived projects are hidden from list, accept no new issues, and pause the autopilots that file into them | list --archived lists only archived projects | |
resource list/add/update/remove | Manage project resources | --type, --url, --default-branch-hint, --ref, --local-path, --daemon-id, --execution-mode (in_place / worktree for a local directory) | |
member list/add/remove | List, add, or remove the members of a private project. Only owner/admin members on the list and the project's access manager can add or remove; agents cannot change access | add <project-id> <member>..., remove <project-id> <member>; a member is a name, email, or user ID | |
workflow get/set <project-id> | Show the project's effective workflow, or switch it | set <project-id> <workflow|default>: --map old=new (repeatable), --dry-run prints the status migration plan; the switch neither reassigns issues nor starts runs. Admins and the project lead only | |
workflow | list/get/create/update/delete | Manage workflows; get and other commands accept an ID, ID prefix, exact name, or default. Statuses a workflow declares are workspace catalog entries, edited with issue-status | create / update: --name, --description, --steps-file (JSON array of steps; replaces all steps); update: --map old=new (repeatable), --dry-run. Edits and deletes are limited to the workflow owner and workspace admins; a workflow still used by a project cannot be deleted |
handoff set <workflow> <status-key> | Set one step's handler, instructions, and next/back status; unchanged fields are kept | --handler (none, project_lead, creator, or a member/agent/squad name or UUID), --instructions / --instructions-file, --next, --back, --copy-for-project | |
issue-status | list/get/create/update/archive | Manage the workspace status catalog — the statuses every workflow picks from. To change an issue's current status, use issue status | create: --name, --category, --color, --key, --icon; update: --name, --description, --color, --icon (empty resets to the category default), --position; list: --include-archived. Mutations require workspace owner/admin |
label | list/get/create/update/delete | Manage workspace labels | list: --resource-type (issue or skill), --full-id; create: --name, --color, --resource-type (issue or skill), --description |
property | list/get/create/update/archive/unarchive | Manage workspace custom properties | create: --name, --type (text, number, select, multi_select, date, checkbox, url, actor, multi_actor, multi_text, multi_url), --option (repeatable, select types only); list: --include-archived; the type cannot be changed after creation |
view | list/get/issues/create/update/duplicate/delete | Read the saved views you can open (your own and workspace-shared ones); issues lists what a view shows, in its saved order, with every saved filter applied by the server. create, update, duplicate and delete write views exactly as the app saves them, so they show in the sidebar and stay editable there; update changes only what its flags name and refuses to overwrite a view that changed since it was read. Only the owner, or a workspace owner/admin for a shared view, can change or delete one. Inside an agent run, the views and any "my" conditions are the runtime owner's | <view> accepts an ID, ID prefix, or exact name; list: --scope (workspace, my, project), --project, --full-id; issues: --limit (at most 100), --cursor (the previous page's next_cursor), --today (the day relative due-date filters resolve against; default today), --fields (JSON only), --full-id; create: --name, --scope, --project, --scope-variant, --visibility; create/update/duplicate filters: --status, --priority, --assignee, --creator, --label, --project-filter, --project-status, --relation, --due, --property "Name=Value", --negate <filter>, --include-no-assignee, --include-no-project, --agent-running, --agent-idle, --unread; display: --view-mode, --grouping, --table-grouping, --swimlane-grouping, --gantt-zoom, --sort, --direction, --show-sub-issues; --definition-file (JSON query/display, e.g. edited view get output), --clear-filters (update/duplicate), --dry-run |
agent | list/get/create/update/archive/restore | Manage agents | --name, --runtime-id (required for create), --instructions, --conversation-starters, --model, --thinking-level, --custom-env / --custom-env-file / --custom-env-stdin (create only), --custom-args, --mcp-config / --mcp-config-file / --mcp-config-stdin, --permission-mode, --visibility (older form), --max-concurrent-tasks |
copy <agent-id> | Copy into a new agent; the original is untouched | --name (defaults to the original name plus (copy)), --runtime-id (copying to another runtime also requires --model), --no-skills; secret configuration such as custom_env, mcp_config, and runtime_config is not copied — re-provide it with the same flags as create | |
tasks <id> | View an agent's runs | ||
avatar <id> | Upload an avatar | ||
env get/set <agent-id> | Read and write custom environment variables (agent owner or workspace owner/admin; every read is recorded) | set: --custom-env / --custom-env-file / --custom-env-stdin; replaces the whole set, and keys whose value is **** keep their existing value | |
skills list/set/add <agent-id> | Manage attached skills | --skill-ids (set replaces the full list, add appends) | |
mcp list/add/enable/disable/remove <agent-id> | Assign workspace MCP servers to this agent | Take the server id from workspace mcp list. A library entry does nothing until it is added here; disable stops sending it without dropping the assignment | |
autopilot | list/get/create/update/delete | Manage automations | create: --title, --mode (both required), exactly one of --agent / --squad / --squad-id (required), --description, --issue-title-template, --project, --subscriber (repeatable) |
trigger <id> | Trigger a run manually | ||
runs <id> | View run history | ||
trigger-add/trigger-update/trigger-delete/trigger-rotate-url | Manage schedule and webhook triggers | trigger-add: --kind (schedule or webhook), --cron, --timezone (default UTC), --label | |
workspace | list/get/create/update/switch | Manage workspaces; switch sets the current profile's default workspace | create: --name, --slug (both required), --issue-prefix, --description, --context / --context-stdin; update changes the same fields except the slug |
mcp list/add/update/remove | Manage the workspace's MCP server library | Writes are owner/admin. A server added here is assigned to no agent — give it to one with multica agent mcp add. list shows names and transports only; the stored entry is write-only and never returned. --server-config-file / --server-config-stdin keep tokens out of shell history | |
member list/invite <email> | View members, send invites | invite: --role (member or admin, default member) | |
repo | list/add/remove/checkout | Manage workspace repositories and check them out locally | --url (repeatable); checkout: --ref |
skill | list/get/create/update/delete | Manage skills | |
import | Import a skill from a URL or local file | --url / --file, --on-conflict (fail, overwrite, rename, skip; default fail) | |
search <query> | Search skills | ||
files list/upsert/delete <skill-id> | Manage the files inside a skill | ||
label list/add/remove <skill-id> | Manage labels on a skill | add / remove: <label-id> accepts a full UUID or short prefix | |
squad | list/get/create/update/delete | Manage squads (delete archives) | |
member list/add/set-role/remove | Manage squad members | ||
activity <issue-id> <outcome> | Record a leader evaluation | ||
chat | history, thread [id] | Read the external chat session an agent is currently handling | --limit, --before |
wakeup create/list/get/update/cancel/finish/checkin | Manage follow-ups in the current chat run; see Chat wakeups | --title, --instruction / --instruction-file, --until-*, --at / --after, --every, --expires-in / --expires-at; checkin: --note | |
inbox | list | List your notifications without marking them read; --archived or --snoozed lists those instead | --unread, --issue, --since, --project, --type, --output (table or json); --archived reads every page |
count | Unread count in this workspace and in each of your workspaces; an agent run sees only its own workspace | --output | |
read [<id>...] | Mark notifications read, the whole issue for each; or every notification on one issue, or all | --issue, --all (needs --yes) | |
unread <id>... | Mark notifications unread | ||
archive [<id>...] | Archive notifications, the whole issue for each; or in bulk | --all, --read, --completed (each needs --yes) | |
unarchive <id>... | Restore archived notifications | ||
snooze <id>... | Take each notification's issue out of the inbox until a time | --until (RFC 3339, 30m, 3h, 1d, 1w, tomorrow) | |
unsnooze <id>... | Bring snoozed issues back now |
Runtime
| Command | Subcommand | Purpose | Key flags |
|---|---|---|---|
daemon | start | Start the local daemon | --foreground, --device-name, --runtime-name, --workspaces-root, --poll-interval, --heartbeat-interval, --agent-timeout (0 means no limit), --max-concurrent-tasks, --no-auto-update; each has a matching MULTICA_* environment variable |
stop / status / restart | Stop, check status, restart (restart takes the same flags as start) | ||
logs | View daemon logs | --follow, --lines | |
disk-usage | View local disk usage | --by-workspace, --by-task, --top | |
autostart enable/disable/status | Register or remove start-at-login for the current profile | status: --output | |
runtime | list/usage/activity/update/rename/delete | View and manage runtimes | usage: --days (default 90, max 365); update: --target-version (required), --wait; delete: --cascade (unbinds bound agents, preserves their data, and cancels their runs) |
profile list/create/update/delete | Manage custom runtime profiles | create: --display-name, --command-name (both required), --runtime-type (or the older --protocol-family), --description; update: --enabled | |
profile set-path/unset-path <profile-id> | Pin a local executable path (local only, never uploaded to the server) | ||
env | start <name> / stop <name> / list | Start, stop, or list this issue's declared environments; only inside an agent run. See Environments | start: --wait (default true); all: --output (table or json) |
Additional
| Command | Subcommand | Purpose | Key flags |
|---|---|---|---|
auth | status / logout | Check auth status; logout only deletes the locally saved token and does not revoke it on the server | |
user | profile get/update | View or update the current user's profile | |
login | — | Sign in via the browser and configure all workspaces automatically | --token (prompts interactively in the terminal when passed without a value) |
setup | cloud (default), self-host | Save the server address, complete sign-in, and start the daemon | self-host: --server-url, --app-url, --port, --frontend-port |
attachment | download <attachment-id>, upload <path> | Download or upload attachments | download: --output-dir; upload: --task |
config | show, set <key> <value> | View or edit the current profile's local configuration | Precedence: command-line flags > environment variables > config.json > built-in defaults; set an empty string to clear a value |
update | — | Update the CLI to the latest version | |
version | — | Print version information | --output (text or json) |
Driving Multica from another coding agent
If most of your work already happens inside Codex, Claude Code, or Cursor, you can operate Multica from there instead of switching to a terminal. The Multica CLI skill teaches those agents to drive the commands on this page safely: reading issues and comment threads without burning tokens, writing comments through a file, and handling the side effects that mentions, status changes, and assignments carry.
It runs entirely through your authenticated CLI and grants no access of its own — permissions still come from your login, selected profile, and workspace. It requires CLI v0.4.26 or newer. The repository README covers installation for the Claude Code plugin marketplace, the Codex skill installer, Cursor, and any other tool that loads Markdown instructions.
Next steps
- Multica CLI skill — operate Multica from Codex, Claude Code, or Cursor.
- Authentication and tokens — creating, renewing, and revoking PATs.
- Troubleshooting — diagnosing command errors and runs that never start.
- Create and configure an agent — the full semantics of every
agent createfield.