mirror of
https://github.com/multica-ai/multica.git
synced 2026-07-12 12:18:55 +02:00
e4ec9dc425
* feat(skills): structured conflict + overwrite path for local skill re-import
Local-skill re-import previously failed (or silently skipped) on a same-name
collision and, on delete+reimport, changed the skill UUID and dropped agent
bindings. This adds a structured conflict result and a creator-only overwrite
write path so a re-import can update the existing skill in place.
- New terminal import status `conflict` carrying { existing_skill_id,
existing_created_by, can_overwrite }; can_overwrite = requester is the
skill creator (canOverwriteSkillByLocalImport — intentionally narrower than
canManageSkill: admins edit in-app, not via re-import).
- Conflict is detected at daemon-report time (the effective name is only known
once the bundle arrives) via GetSkillByWorkspaceAndName, with the unique
constraint as a race backstop.
- Import requests carry action=overwrite + target_skill_id, persisted through
both the in-memory and Redis LocalSkillImportStore (the heartbeat → daemon
payload is unchanged; overwrite is resolved server-side).
- overwriteSkillWithFiles updates by target_skill_id in one tx: re-checks
existence (workspace-scoped) and creator permission, then replaces
description/content/config and fully replaces files (pruning files absent
from the new bundle). Preserves id, created_by, created_at, name, and
agent_skill bindings. Publishes skill:updated (not skill:created).
- Boundaries: target deleted or permission lost → failed (no fallback to
create-by-name); any mid-write error rolls back the tx, leaving the original
skill untouched. Retrying a terminal request is a no-op.
Tests cover: creator/non-creator conflict (can_overwrite), overwrite preserves
UUID + agent binding + prunes removed files, non-creator overwrite fails,
deleted target fails without create fallback, retry idempotency, and Redis
round-trip of the new fields.
Backend half of MUL-2701. Contract change: same-name local imports now return
status `conflict` instead of `failed` — the Desktop/core client must be updated
to consume it (sibling task).
MUL-2800
Co-authored-by: multica-agent <github@multica.ai>
* fix(skills): gate structured conflict behind client opt-in; guard overwrite target name
Addresses review feedback on PR #3498 (MUL-2800).
Backward compatibility: a same-name local import now returns the new `conflict`
status only when the initiating client opts in via `supports_conflict` (an
overwrite request implies it). Older clients — already-installed Desktop builds
whose poll loop only understands `failed`/`timeout` — keep the legacy `failed`
+ "a skill with this name already exists" behavior, so upgrading the backend
ahead of the client no longer regresses the import UX. This is the installed-app
API-compat boundary the repo's CLAUDE.md calls out.
Also: the overwrite write path now verifies the incoming effective name matches
the target skill's current name (errSkillOverwriteNameMismatch -> failed),
preventing a stale/wrong target_skill_id from writing one skill's content onto
another. Creator-only + workspace scoping already prevent privilege escalation;
this narrows the API so it can't be misused.
Refactored LocalSkillImportStore.Create to a LocalSkillImportRequestInput params
struct (the signature had grown to 8 positional args; the opt-in flag pushed it
over). supports_conflict is persisted in both the in-memory and Redis stores.
Tests: conflict tests now opt in; added a legacy-client test (no flag ->
failed + legacy message) and an overwrite name-mismatch test.
MUL-2800
Co-authored-by: multica-agent <github@multica.ai>
* feat(skills): resolve local import conflicts in desktop
Co-authored-by: multica-agent <github@multica.ai>
* fix(skills): preserve bulk flow after conflict resolution
Co-authored-by: multica-agent <github@multica.ai>
* feat(cli): add skill import conflict strategies
Co-authored-by: multica-agent <github@multica.ai>
* fix(i18n): sync skill import locale keys
Co-authored-by: multica-agent <github@multica.ai>
* docs: explain skill import conflict handling
Co-authored-by: multica-agent <github@multica.ai>
* docs: refresh skill import source map anchors
Co-authored-by: multica-agent <github@multica.ai>
---------
Co-authored-by: J <j@multica.ai>
Co-authored-by: multica-agent <github@multica.ai>
167 lines
7.6 KiB
Plaintext
167 lines
7.6 KiB
Plaintext
---
|
|
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> --agent <slug>` | Assign to an agent (triggers a task immediately) |
|
|
| `multica issue status <id> --set <status>` | Shortcut to change status |
|
|
| `multica issue search <query>` | Keyword search |
|
|
| `multica issue runs <id>` | Show agent runs on an issue |
|
|
| `multica issue rerun <id>` | Re-enqueue a fresh task for the issue's current agent assignee |
|
|
| `multica issue comment <id> ...` | Nested: view / post comments |
|
|
| `multica issue subscriber <id> ...` | Nested: subscribe / unsubscribe |
|
|
| `multica project list/get/create/update/delete/status` | Project 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 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 |
|
|
|
|
## 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> ...` | Update a runtime's configuration |
|
|
|
|
## 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`
|