multica/apps/docs/content/docs/cli.mdx

---
title: CLI command reference
description: One-page overview of every top-level Multica CLI command. For full usage, run `multica <command> --help`.
---

import { Callout } from "fumadocs-ui/components/callout";

The Multica CLI mirrors almost everything the Web UI can do (create [issues](/issues), assign [agents](/agents), start the [daemon](/daemon-runtimes), and more). This page lists every top-level command with a one-line description. For the full set of flags and examples, run `multica <command> --help`.

## Getting authenticated

Run this the first time you use the CLI to obtain a **personal access token (PAT)**:

```bash
multica login
```

Your browser opens automatically. After you approve in the web app, the CLI saves the PAT (prefixed with `mul_`) to `~/.multica/config.json`. Every subsequent command authenticates with that PAT.

<Callout type="tip">
For CI or headless environments, skip the browser flow: create a PAT in the web app under **Settings → Personal Access Tokens**, then run `multica login --token <mul_...>` to supply it directly.
</Callout>

For the difference between token types, see [Authentication and tokens](/auth-tokens).

## Auth and setup

| Command | Purpose |
|---|---|
| `multica login` | Log in and save a PAT |
| `multica auth status` | Show current login status, user, and workspace |
| `multica auth logout` | Clear the local PAT |
| `multica setup cloud` | One-shot setup for Multica Cloud (login + install daemon) |
| `multica setup self-host` | One-shot setup for a self-hosted backend |

## Workspaces and members

| Command | Purpose |
|---|---|
| `multica workspace list` | List every workspace you can access |
| `multica workspace get <slug>` | Show details for one workspace |
| `multica workspace member list` | List members of the current workspace |
| `multica workspace update <id> --name "..." [--description "..."] [--context "..."] [--issue-prefix "..."]` | Update workspace metadata (admin/owner). Long fields accept `--description-stdin` / `--context-stdin`. |

## Issues and projects

<Callout type="info">
`list` commands (`multica issue list`, `autopilot list`, `project list`, etc.) print short, copy-paste-ready IDs by default — issue keys like `MUL-123` for issues, short UUID prefixes for the rest. The `<id>` argument on the follow-up commands below accepts either the short ID or the full UUID, so the typical flow is `multica issue list` → copy the key → `multica issue get MUL-123`. Pass `--full-id` to a list command when you need the canonical UUID.
</Callout>

| Command | Purpose |
|---|---|
| `multica issue list` | List issues (prints copy-paste-ready issue keys) |
| `multica issue get <id>` | Show a single issue (accepts an issue key or a UUID) |
| `multica issue create --title "..."` | Create a new issue |
| `multica issue update <id> ...` | Update an issue (status, priority, assignee, etc.) |
| `multica issue assign <id> --to <name>` | Assign to a member, agent, or squad (assigning to an agent triggers a run) |
| `multica issue status <id> <status>` | Shortcut to change status |
| `multica issue search <query>` | Keyword search |
| `multica issue children <id>` | List sub-issues grouped by stage |
| `multica issue pull-requests <id>` | List linked pull requests and their status |
| `multica issue runs <id>` | Show agent runs on an issue |
| `multica issue run-messages <task-id>` | Show messages for one execution |
| `multica issue usage <id>` | Show aggregated token usage for an issue |
| `multica issue rerun <id>` | Re-enqueue a fresh task for the issue's current agent assignee |
| `multica issue cancel-task <task-id>` | Cancel a queued or running task |
| `multica issue comment <id> ...` | Nested: view / post comments |
| `multica issue comment resolve/unresolve <comment-id>` | Mark a comment thread resolved or unresolved |
| `multica issue subscriber <id> ...` | Nested: subscribe / unsubscribe |
| `multica issue metadata <id> ...` | Nested: read / write issue metadata |
| `multica issue label <id> ...` | Nested: manage labels on an issue |
| `multica project list/get/create/update/delete/status` | Project CRUD |
| `multica label list/create/update/delete` | Workspace label CRUD |

## Agents and skills

| Command | Purpose |
|---|---|
| `multica agent list` | List the workspace's agents |
| `multica agent get <slug>` | Show an agent's configuration |
| `multica agent create ...` | Create an agent |
| `multica agent update <slug> ...` | Update an agent |
| `multica agent archive <slug>` | Archive |
| `multica agent restore <slug>` | Restore an archived agent |
| `multica agent tasks <slug>` | Show an agent's task history |
| `multica agent avatar <slug>` | Upload an agent avatar |
| `multica agent env <slug> ...` | Read or replace an agent's custom environment variables |
| `multica agent skills ...` | Nested: attach / detach skills |
| `multica skill list/get/create/update/delete` | Skill CRUD |
| `multica skill import ...` | Import a skill from GitHub, ClawHub, or the local machine |
| `multica skill files ...` | Nested: manage a skill's files |

### Skill import conflicts

`multica skill import --url <url>` defaults to `--on-conflict fail`. If a skill
with the same name already exists, the command exits with a structured
`conflict` result and does not change the workspace.

Use `--on-conflict overwrite` when you created the existing skill and want to
replace its content while preserving its ID and agent bindings. Use
`--on-conflict rename` to import a copy with an automatic suffix such as `-2`.
Use `--on-conflict skip` to leave the existing skill untouched and report
`skipped`.

```bash
multica skill import --url https://skills.sh/acme/repo/review-helper
multica skill import --url https://skills.sh/acme/repo/review-helper --on-conflict overwrite
multica skill import --url https://skills.sh/acme/repo/review-helper --on-conflict rename
multica skill import --url https://skills.sh/acme/repo/review-helper --on-conflict skip
```

## Squads

| Command | Purpose |
|---|---|
| `multica squad list` | List squads in the workspace |
| `multica squad get <id>` | Show a single squad |
| `multica squad create --name "..." --leader <agent>` | Create a squad (owner / admin) |
| `multica squad update <id> ...` | Update name, description, instructions, leader, or avatar |
| `multica squad delete <id>` | Archive (soft-delete) — transfers assigned issues to the leader |
| `multica squad member list/add/remove/set-role <squad-id>` | Manage squad members and update roles in place |
| `multica squad activity <issue-id> <action\|no_action\|failed> --reason "..."` | Used by squad leader agents to record an evaluation per turn |

See [Squads](/squads) for the full model.

## Autopilots

| Command | Purpose |
|---|---|
| `multica autopilot list` | List every autopilot in the workspace |
| `multica autopilot get <id>` | Show a single autopilot |
| `multica autopilot create ...` | Create an autopilot |
| `multica autopilot update <id> ...` | Update |
| `multica autopilot delete <id>` | Delete |
| `multica autopilot runs <id>` | Show run history |
| `multica autopilot trigger <id>` | Trigger a run manually |
| `multica autopilot trigger-add/update/delete <id>` | Manage schedule or webhook triggers |
| `multica autopilot trigger-rotate-url <id> <trigger-id>` | Rotate a webhook trigger URL |

`multica autopilot create/update` also accepts `--subscriber` to set default
subscribers for issues created by a `create_issue` autopilot; update accepts
`--clear-subscribers` to remove them.

## Daemon and runtimes

| Command | Purpose |
|---|---|
| `multica daemon start` | Start the daemon (background by default; add `--foreground` to run in the foreground) |
| `multica daemon stop` | Stop the daemon |
| `multica daemon restart` | Restart the daemon |
| `multica daemon status` | Check whether the daemon is online and its concurrency |
| `multica daemon logs` | View daemon logs |
| `multica runtime list` | List runtimes in the current workspace |
| `multica runtime usage` | Show resource usage |
| `multica runtime activity` | Recent activity log |
| `multica runtime update <id> ...` | Initiate a CLI update on a runtime |
| `multica runtime delete <id> [--cascade]` | Delete a runtime, optionally archiving bound agents |
| `multica runtime profile ...` | Manage custom runtime profiles and local path overrides |

## Miscellaneous

| Command | Purpose |
|---|---|
| `multica repo checkout <url>` | Clone a repo locally for agents to use |
| `multica config` | View or edit local CLI configuration |
| `multica version` | Print the CLI version |
| `multica update` | Upgrade the CLI to the latest release |
| `multica attachment download <id>` | Download an attachment from an issue or comment |

## Getting full flags

Every command supports `--help`:

```bash
multica issue create --help
multica agent update --help
```

v2 will ship a dedicated detailed reference page for each command.

## Next steps

- [Authentication and tokens](/auth-tokens) — PAT vs. JWT vs. daemon token
- [Daemon and runtimes](/daemon-runtimes) — how the `daemon` commands work under the hood
- [Creating and configuring agents](/agents-create) — all options for `multica agent create`