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

---
title: CLI 사용
description: Multica CLI를 설치하고 로그인해 터미널에서 워크스페이스, 태스크, 에이전트, 런타임을 관리합니다.
---

import { Callout } from "fumadocs-ui/components/callout";
import { Tab, Tabs } from "fumadocs-ui/components/tabs";

Multica CLI는 로컬 런타임을 연결할 뿐 아니라 터미널에서 워크스페이스, 태스크, 에이전트, 자동화를 관리할 수 있습니다. 이 페이지에서는 자주 사용하는 경로를 설명합니다. 현재 버전에서 지원하는 인수는 항상 명령 자체의 `--help`를 기준으로 확인하세요.

## 설치

<Tabs groupId="os" persist items={["macOS / Linux", "Windows"]}>
<Tab value="macOS / Linux">

```bash
curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash
```

Homebrew가 설치되어 있다면 다음 명령도 사용할 수 있습니다.

```bash
brew install multica-ai/tap/multica
```

</Tab>
<Tab value="Windows">

PowerShell에서 실행합니다.

```powershell
irm https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.ps1 | iex
```

</Tab>
</Tabs>

설치 성공 여부를 확인합니다.

```bash
multica version
```

## 처음 연결

연결할 서비스를 선택합니다.

<Tabs items={["Multica Cloud", "자체 호스팅 인스턴스"]}>
<Tab value="Multica Cloud">

```bash
multica setup
```

</Tab>
<Tab value="자체 호스팅 인스턴스">

```bash
multica setup self-host \
  --server-url https://api.example.com \
  --app-url https://app.example.com
```

</Tab>
</Tabs>

`setup`은 서비스 주소를 저장하고 브라우저를 열어 로그인을 완료한 뒤 데몬을 시작합니다. 완료 후 다음을 확인하세요.

```bash
multica auth status
multica daemon status
```

다른 설정을 덮어쓰지 않고 로그인만 다시 하려면 `multica login`을 실행합니다. 브라우저가 없는 환경에서는 Web 설정에서 개인 액세스 토큰을 먼저 만든 뒤 다음을 입력합니다.

```bash
multica login --token
```

명령이 터미널에서 token 붙여넣기를 요청하므로 전체 값이 shell history에 남지 않습니다.

## 워크스페이스 선택

기본 워크스페이스를 나열하고 전환합니다.

```bash
multica workspace list
multica workspace switch <slug>
```

이후 명령은 이 워크스페이스를 사용합니다. 한 번의 명령에서 `--workspace-id`로 임시 덮어쓸 수 있고 `MULTICA_WORKSPACE_ID`를 설정할 수도 있습니다.

멤버 초대:

```bash
multica workspace member invite [email protected]
multica workspace member invite [email protected] --role admin
```

## 자주 사용하는 태스크 작업

```bash
# 확인 및 검색
multica issue list
multica issue get MUL-123
multica issue search "로그인 실패"

# 생성 및 수정
multica issue create --title "로그인 실패 수정"
multica issue status MUL-123 in_progress
multica issue assign MUL-123 --to "Backend Agent"

# 댓글 및 실행 기록
multica issue comment list MUL-123
multica issue comment add MUL-123 --content "회귀 테스트를 먼저 확인해 주세요"
multica issue comment update <comment-id> --expected-revision 2 --content "회귀 테스트와 릴리스 노트를 확인해 주세요"
multica issue runs MUL-123
```

긴 설명이나 댓글은 stdin에서 읽어 줄바꿈과 따옴표 처리를 피할 수 있습니다.

```bash
multica issue create --title "업그레이드 안내" --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.md
```

특정 실행의 메시지를 확인하거나 실행을 중지 또는 재시도합니다.

```bash
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 --fresh
```

같은 프로젝트, 같은 상위 태스크 아래에 제목이 같은(대소문자와 여분의 공백은 구분하지 않음) 닫히지 않은 태스크가 이미 있으면 `issue create`는 생성을 거부하고 그 태스크를 알려 줍니다. 그래도 만들려면 `--allow-duplicate`를 붙이세요. 한 태스크를 다른 태스크의 중복으로 표시하려면 `multica issue status MUL-124 cancelled --duplicate-of MUL-123`을 실행합니다.

### 타임라인

`issue get`은 태스크의 현재 상태를 보여 줍니다. `issue timeline`은 상태, 우선순위, 담당자, 제목, 날짜 변경과 실행 결과를 시간순으로 나열하고 댓글도 섞어 보여 줍니다. "언제 in_review로 바뀌었나", "지금 상태에 얼마나 머물러 있나"를 확인할 때 씁니다.

```bash
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`는 댓글을 빼고 모든 활동 기록을 남깁니다. `--action`은 지정한 동작만 반환하며 반복해서 쓸 수 있고 `--activity-only`를 포함합니다. 서버가 읽는 기록에는 한도가 있어 잘린 경우 stderr에 경고가 출력됩니다. 이때는 그 결과로 머문 시간을 추정하지 마세요.

### 긴 댓글 스레드 읽기

댓글이 많은 태스크를 하나씩 읽으면 에이전트가 토큰을 많이 씁니다. 먼저 스레드를 훑어보고 필요한 스레드만 펼치세요.

```bash
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-only`는 최상위 댓글만 반환하며 각 댓글에 답글 수와 마지막 활동 시각이 붙습니다.
- `--summary`는 각 댓글을 짧은 미리보기로 자릅니다.
- `--compact`는 JSON 출력에만 적용되며 정보가 없는 필드(반복되는 `issue_id`, 빈 배열 등)를 뺍니다.
- `--recent N`은 최근 활동이 있었던 스레드 N개를 모든 답글과 함께 반환하므로 답글이 많으면 출력이 길어집니다.
- 해결된 스레드는 기본적으로 첫 댓글과 결론으로 접힙니다. 전체 내용이 필요하면 `--full`을 붙이세요.

목록도 필요한 필드만 받을 수 있습니다: `multica issue list --output json --fields id,identifier,title,status`. 필터링은 CLI에서 이루어지므로 줄어드는 것은 출력과 컨텍스트이고 요청량은 그대로입니다.

### 깨우기

깨우기는 이벤트가 생기거나 조건이 충족되거나 지정한 시각이 되면 에이전트의 일반 실행을 시작합니다. 전체 규칙은 [태스크 깨우기](/issue-wakeups)를 참고하세요.

```bash
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 "답장이 오면 그 내용으로 견적서를 업데이트"
multica issue wakeup create MUL-123 --agent-id <agent-id> \
  --kind every --every 1h --expires-in 72h \
  --instruction "공급업체가 회신했는지 확인"
multica issue wakeup list MUL-123
multica issue wakeup runs MUL-123 <wakeup-id>
```

터미널에서 멤버로 만들 때는 `--agent-id`가 필요합니다. 에이전트가 자기 실행 안에서 만들면 기본적으로 자기 자신을 깨웁니다.

## 에이전트와 스킬

```bash
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>
```

가져올 때 같은 이름의 스킬이 있으면 기본적으로 중지하고 기존 내용을 수정하지 않습니다. 의도에 맞는 방식을 선택하세요.

```bash
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 skip
```

`overwrite`는 스킬 생성자만 사용할 수 있으며 기존 ID와 에이전트 연결을 유지합니다.

환경 변수와 MCP 설정에는 토큰이 들어 있는 경우가 많습니다. 명령줄에 값을 직접 쓰면 셸 기록과 `ps` 출력에 남으므로 `-file` 또는 `-stdin` 형태로 전달하세요.

```bash
multica agent create --name "운영 도우미" --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
```

- `--custom-env` 계열 플래그는 `agent create`에만 있습니다. 나중에 바꿀 때는 `agent env set`을 쓰며, 전체를 교체하고 값이 `****`인 키는 기존 값을 유지합니다.
- `agent update --mcp-config null`은 MCP 설정을 지웁니다.
- `--custom-args`는 JSON 배열이며 실행 인수의 맨 끝에 붙습니다. 모델은 `--model`로 고르세요. 사용자 지정 인수 안의 `--model`을 거부하는 도구도 있습니다.
- 에이전트를 호출할 수 있는 사람은 `--permission-mode`로 정합니다. `private`은 소유자만, `public_to`는 `--public-to-workspace` 또는 `--public-to-member <user-id>`와 함께 씁니다. `--visibility private|workspace`는 예전 방식이며 `--permission-mode`로 변환됩니다. 둘 다 지정하면 `--permission-mode`가 우선합니다.

## 데몬과 런타임

```bash
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>
```

```bash
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 "사내 Claude 래퍼" \
  --command-name ccms --runtime-type claude
```

`daemon autostart`는 현재 profile이 로그인할 때 시작되도록 등록합니다. 플랫폼별 차이는 [로그인 시 자동 시작](/daemon-runtimes#autostart)을 참고하세요. `runtime usage`는 기본적으로 90일을 집계하며 `--days`는 최대 365입니다. `runtime update`는 해당 컴퓨터의 데몬이 CLI를 지정한 버전으로 업데이트하게 하고, `--wait`를 붙이면 업데이트가 끝날 때까지 기다립니다. `runtime profile create`는 호환 도구를 `--runtime-type`으로 지정합니다(예전 `--protocol-family`도 쓸 수 있음). 고정 인수는 현재 웹 앱에서만 설정할 수 있습니다.

활성 에이전트가 계속 연결된 런타임을 삭제하면 명령이 기본적으로 거부됩니다. `multica runtime delete <id> --cascade`는 에이전트의 런타임 연결을 해제하고 설정과 기록을 보존하며 활성 실행을 취소합니다.

실행 메커니즘과 사용자 지정 profile은 [데몬과 런타임](/daemon-runtimes)을 참고하세요.

## 프로젝트, 워크스페이스, 오토파일럿

```bash
multica project create --title "여름 캠페인" --lead "리레이" \
  --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 "운영팀" --slug ops --issue-prefix OPS
multica workspace update --context-stdin < team-context.md

multica autopilot create --title "주간 매출 보고" --agent "운영 도우미" \
  --mode create_issue --issue-title-template "매출 보고 {{date}}"
multica autopilot trigger-add <autopilot-id> --cron "0 9 * * 1" --timezone Asia/Seoul
```

- `--lead`에는 멤버나 에이전트의 이름을 씁니다. `--default-branch-hint`는 저장소의 기본 브랜치를 에이전트에게 알려 줄 뿐 브랜치를 바꾸지는 않습니다.
- 워크스페이스의 `--context`는 워크스페이스의 모든 에이전트에게 제공됩니다. `--slug`는 만든 뒤 바꿀 수 없습니다. `--issue-prefix`는 대문자로 바뀌며, 변경하면 기존 태스크 번호가 모두 다시 매겨져 외부에서 참조하던 예전 번호는 더 이상 연결되지 않습니다.
- `--issue-title-template`은 `{{date}}`(UTC, `YYYY-MM-DD`)만 치환하며 다른 `{{...}}`는 거부합니다. 일정 트리거의 `--timezone` 기본값은 UTC입니다.

## 명령 개요

| 명령 | 용도 |
| --- | --- |
| `issue` | 태스크 생성, 업데이트, 할당, 검색. 댓글, 구독, 라벨, 속성, 깨우기, 타임라인, 실행 기록 관리 |
| `project` | 프로젝트와 프로젝트 리소스 관리 |
| `label`, `property` | 워크스페이스 라벨과 사용자 지정 속성 관리 |
| `agent`, `skill`, `squad` | 에이전트, 스킬, 스쿼드 관리 |
| `autopilot` | 자동화, 트리거, 실행 기록 관리 |
| `workspace` | 워크스페이스 생성, 확인, 전환 및 멤버 초대 |
| `repo` | 워크스페이스 저장소 관리 및 로컬 checkout |
| `daemon`, `runtime` | 로컬 데몬 시작 및 중지, 런타임 확인 및 관리 |
| `attachment` | 첨부 파일 업로드 또는 다운로드 |
| `user profile` | 현재 사용자 profile 확인 또는 업데이트 |
| `auth`, `login`, `setup` | 로그인, 인증 상태 확인, 연결 초기화 |
| `config` | 현재 CLI profile의 로컬 설정 확인 또는 변경 |
| `update`, `version` | CLI 업데이트 또는 버전 확인 |

`multica chat`은 **에이전트가 현재 처리 중인 외부 채팅 대화**를 읽으며 주로 채팅 연동의 에이전트가 사용합니다. 워크스페이스의 임의 대화를 탐색하는 일반 명령이 아닙니다.

## ID와 출력 형식

태스크에는 `MUL-123` 같은 key 또는 전체 UUID를 사용하며 UUID 짧은 접두사는 허용하지 않습니다.

다른 리소스의 `list` 명령은 일반적으로 복사 가능한 짧은 ID를 표시하고 `--full-id`로 전체 UUID를 출력할 수 있습니다. 짧은 ID가 고유하지 않으면 CLI가 더 많은 글자를 입력하거나 전체 UUID를 사용하도록 요청합니다. 실행의 짧은 ID에는 `--issue`로 소속 태스크도 지정해야 합니다.

많은 명령이 구조화 출력을 지원합니다.

```bash
multica issue list --output json
multica agent list --output json
```

스크립트에서는 터미널용 표를 parsing하지 말고 JSON 출력을 사용하세요. 각 명령이 지원하는 출력 형식과 pagination 인수는 `multica <command> --help`를 기준으로 확인합니다.

## Profile과 설정

기본 설정은 `~/.multica/config.json`에 저장됩니다. `--profile <name>`을 사용하면 별도의 서비스 주소, token, 기본 워크스페이스, 데몬 상태를 격리할 수 있습니다.

```bash
multica setup self-host --profile staging \
  --server-url https://api.staging.example.com \
  --app-url https://app.staging.example.com

multica issue list --profile staging
```

이름 있는 profile은 `~/.multica/profiles/<name>/config.json`에 저장됩니다. 현재 값을 확인합니다.

```bash
multica config show
multica config show --profile staging
```

<Callout type="warning">
CLI 설정 파일에는 사용자를 대신해 Multica에 접근할 수 있는 token이 들어 있습니다. 저장소에 commit하거나 로그에 올리거나 다른 사람과 공유하지 마세요.
</Callout>

## 명령 참조

다음 표는 현재의 모든 최상위 명령을 CLI 자체 그룹 순서로 정리합니다. 모든 명령은 전역 flag `--server-url`, `--workspace-id`, `--profile`, `--debug`를 허용합니다. `--output`은 명령별로 등록되는 flag이며 기본 형식은 명령에 따라 다릅니다. `list` 계열은 기본적으로 표를 사용하고 `get`, `create` 계열은 주로 JSON을 사용합니다. 전체 인수는 `multica <command> --help`를 기준으로 확인하세요.

### Core

| 명령 | 하위 명령 | 용도 | 주요 flag |
| --- | --- | --- | --- |
| `issue` | `list` | 태스크 목록 | `--status`, `--priority`, `--assignee`, `--project`, `--metadata`(반복 가능), `--property`(반복 가능, `"이름=값"` 또는 `"Score>=3"`, `"Due<2026-01-01"`, `"Notes~=text"` 같은 비교; `__none__`은 미설정과 일치), `--limit`, `--offset`, `--sort`(`property:<이름 또는 id>` 지원), `--full-id`, `--resolve-properties`(JSON 전용; 저장된 id와 함께 속성, 옵션, 멤버 이름을 반환), `--fields`(JSON 전용. 남길 필드를 쉼표로 구분) |
| | `get <id>` | 태스크 하나 확인 | `--resolve-properties`(JSON 전용; 저장된 id와 함께 속성, 옵션, 멤버 이름을 반환) |
| | `create` | 태스크 생성 | `--title`(필수), `--description` / `--description-stdin` / `--description-file`, `--status`, `--priority`, `--assignee`, `--parent`, `--stage`, `--project`, `--start-date`, `--due-date`, `--attachment`(반복 가능), `--property`(반복 가능), `--allow-duplicate`(같은 제목의 닫히지 않은 태스크가 있어도 생성) |
| | `update <id>` | 태스크 필드 업데이트 | `create`와 같은 종류의 필드에 `--position`, `--no-start`, `--duplicate-of` 추가 |
| | `assign <id>` | 할당 또는 할당 해제 | `--to`(이름으로 멤버, 에이전트, 스쿼드 fuzzy match), `--to-id`, `--unassign`, `--no-start` |
| | `status <id> <status>` | 상태 변경 | `--no-start`, `--duplicate-of` |
| | `reorder <id>` | 열 안에서 이동 | |
| | `search <query>` | 태스크 검색 | `--limit`, `--include-closed` |
| | `children <id>` | 단계별로 묶은 하위 태스크 목록 | |
| | `pull-requests <id>` | 연결된 PR 목록 | |
| | `comment list/add/update/delete/resolve/unresolve` | 댓글 관리 | `add`: `--content` / `--content-stdin` / `--content-file`, `--parent`, `--attachment`. `update`: `--expected-revision`(필수), `--content` / `--content-stdin` / `--content-file`. `list`: `--since`, `--thread`, `--tail`, `--recent`, `--roots-only`, `--summary`, `--compact`, `--full` |
| | `timeline <id>` | 활동 기록과 댓글을 시간순으로 표시 | `--action`(반복 가능), `--activity-only`, `--since`, `--tail` |
| | `wakeup events/list/get/create/update/disable/trigger/delete/checkin/runs` | 태스크 깨우기 관리. 자세한 내용은 [태스크 깨우기](/issue-wakeups) | `create` / `update`: `--agent-id`, `--kind`(`event`, `at`, `every`, `cron`), `--event`, `--at` / `--after`, `--every`, `--cron`, `--timezone`, `--until-*` 조건, `--expires-in` / `--expires-at`, `--instruction` / `--instruction-file`. `checkin`: `--note` |
| | `subscriber list/add/remove <issue-id>` | 구독자 관리 | `--user`, `--user-id`(생략하면 현재 사용자) |
| | `label list/add/remove <issue-id>` | 태스크 라벨 관리 | |
| | `metadata list/get/set/delete <issue-id>` | 태스크 수준 key-value metadata 관리 | |
| | `property list/set/unset <issue-id>` | 사용자 지정 속성 값 설정 | `set`: `--name`, `--value`(`actor` / `multi_actor`는 멤버의 이름, 이메일, id를 받습니다) |
| | `runs <issue-id>` | 실행 기록 확인 | `--full-id` |
| | `run-messages <task-id>` | 단일 실행 메시지 확인 | `--since`, `--issue` |
| | `usage <issue-id>` | 집계 token 사용량 확인 | |
| | `rerun-task <run-id>` | 원래 에이전트와 트리거 컨텍스트로 지정한 실행을 재시도 | `--issue`, `--fresh` |
| | `cancel-task <task-id>` | 진행 중 또는 큐 대기 중인 실행 취소 | `--issue` |
| `project` | `list/get/create/update/delete` | 프로젝트 관리 | `create`: `--title`(필수), `--lead`, `--status`, `--icon`, `--start-date`, `--due-date`, `--repo`(반복 가능) |
| | `status <id> <status>` | 프로젝트 상태 변경 | |
| | `resource list/add/update/remove` | 프로젝트 추가 리소스 관리 | `--type`, `--url`, `--default-branch-hint`, `--ref`, `--local-path`, `--daemon-id`, `--execution-mode`(로컬 디렉터리의 `in_place` / `worktree`) |
| `label` | `list/get/create/update/delete` | 워크스페이스 라벨 관리 | `list`: `--resource-type`(`issue` 또는 `skill`), `--full-id`; `create`: `--name`, `--color`, `--resource-type`(`issue` 또는 `skill`), `--description` |
| `property` | `list/get/create/update/archive/unarchive` | 워크스페이스 사용자 지정 속성 관리 | `create`: `--name`, `--type`(`text`, `number`, `select`, `multi_select`, `date`, `checkbox`, `url`, `actor`, `multi_actor`, `multi_text`, `multi_url`), `--option`(반복 가능, select 유형만). `list`: `--include-archived`. 유형은 생성 후 변경 불가 |
| `agent` | `list/get/create/update/archive/restore` | 에이전트 관리 | `--name`, `--runtime-id`(`create`에서 필수), `--instructions`, `--conversation-starters`, `--model`, `--thinking-level`, `--custom-env` / `--custom-env-file` / `--custom-env-stdin`(`create` 전용), `--custom-args`, `--mcp-config` / `--mcp-config-file` / `--mcp-config-stdin`, `--permission-mode`, `--visibility`(예전 방식), `--max-concurrent-tasks` |
| | `copy <agent-id>` | 원래 에이전트에 영향 없이 새 에이전트로 복사 | `--name`(기본값은 원래 이름 + ` (copy)`), `--runtime-id`(다른 런타임으로 복사할 때 `--model`도 필수), `--no-skills`. `custom_env`, `mcp_config`, `runtime_config` 같은 기밀 설정은 복사되지 않으며 `create`와 같은 flag로 다시 제공해야 함 |
| | `tasks <id>` | 에이전트 실행 확인 | |
| | `avatar <id>` | 아바타 업로드 | |
| | `env get/set <agent-id>` | 사용자 지정 환경 변수 읽기/쓰기(에이전트 소유자 또는 워크스페이스 owner/admin. 읽을 때마다 기록됨) | `set`: `--custom-env` / `--custom-env-file` / `--custom-env-stdin`. 전체를 교체하며 값이 `****`인 키는 기존 값 유지 |
| | `skills list/set/add <agent-id>` | 연결된 스킬 관리 | `--skill-ids`(`set`은 전체 교체, `add`는 증분 추가) |
| | `mcp list/add/enable/disable/remove <agent-id>` | 워크스페이스 MCP 서버를 이 에이전트에 할당 | server id는 `workspace mcp list`에서 확인. 라이브러리 항목은 여기서 추가하기 전까지 동작하지 않으며, `disable`은 할당을 유지한 채 전달만 중단합니다 |
| `autopilot` | `list/get/create/update/delete` | 자동화 관리 | `create`: `--title`, `--agent`, `--mode`(모두 필수), `--description`, `--issue-title-template`, `--project`, `--subscriber`(반복 가능) |
| | `trigger <id>` | 수동으로 한 번 트리거 | |
| | `runs <id>` | 실행 기록 확인 | |
| | `trigger-add/trigger-update/trigger-delete/trigger-rotate-url` | 일정 및 webhook 트리거 관리 | `trigger-add`: `--kind`(`schedule` 또는 `webhook`), `--cron`, `--timezone`(기본값 UTC), `--label` |
| `workspace` | `list/get/create/update/switch` | 워크스페이스 관리. `switch`는 현재 profile의 기본 워크스페이스 설정 | `create`: `--name`, `--slug`(모두 필수), `--issue-prefix`, `--description`, `--context` / `--context-stdin`. `update`는 slug를 제외한 같은 항목 변경 |
| | `mcp list/add/update/remove` | 워크스페이스의 MCP 서버 라이브러리를 관리 | 쓰기는 owner/admin 전용. 여기에 추가한 서버는 어떤 에이전트에도 할당되지 않으며 `multica agent mcp add`로 할당합니다. `list`는 이름과 transport만 표시하고, 저장된 항목은 쓰기 전용이라 어떤 역할에도 반환되지 않습니다. `--server-config-file` / `--server-config-stdin`은 토큰이 셸 기록에 남지 않게 합니다 |
| | `member list/invite <email>` | 멤버 확인 및 초대 전송 | `invite`: `--role`(member 또는 admin, 기본 member) |
| `repo` | `list/add/remove/checkout` | 워크스페이스 저장소 관리 및 로컬 checkout | `--url`(반복 가능). `checkout`: `--ref` |
| `skill` | `list/get/create/update/delete` | 스킬 관리 | |
| | `import` | URL 또는 로컬 파일에서 스킬 가져오기 | `--url` / `--file`, `--on-conflict`(`fail`, `overwrite`, `rename`, `skip`, 기본 `fail`) |
| | `search <query>` | 스킬 검색 | |
| | `files list/upsert/delete <skill-id>` | 스킬 내부 파일 관리 | |
| | `label list/add/remove <skill-id>` | 스킬 라벨 관리 | `add` / `remove`: `<label-id>`에 전체 UUID 또는 짧은 접두사 사용 가능 |
| `squad` | `list/get/create/update/delete` | 스쿼드 관리(`delete`는 보관) | |
| | `member list/add/set-role/remove` | 스쿼드 멤버 관리 | |
| | `activity <issue-id> <outcome>` | 리더 평가 기록 | |
| `chat` | `history`, `thread [id]` | 에이전트가 현재 처리 중인 외부 채팅 대화 읽기 | `--limit`, `--before` |

### Runtime

| 명령 | 하위 명령 | 용도 | 주요 flag |
| --- | --- | --- | --- |
| `daemon` | `start` | 로컬 데몬 시작 | `--foreground`, `--device-name`, `--runtime-name`, `--workspaces-root`, `--poll-interval`, `--heartbeat-interval`, `--agent-timeout`(`0`은 상한 없음), `--max-concurrent-tasks`, `--no-auto-update`. 모두 대응하는 `MULTICA_*` 환경 변수가 있음 |
| | `stop` / `status` / `restart` | 중지, 상태 확인, 다시 시작(`restart`와 `start`의 flag가 같음) | |
| | `logs` | 데몬 로그 확인 | `--follow`, `--lines` |
| | `disk-usage` | 로컬 디스크 사용량 확인 | `--by-workspace`, `--by-task`, `--top` |
| | `autostart enable/disable/status` | 현재 profile의 로그인 시 자동 시작 등록 또는 해제 | `status`: `--output` |
| `runtime` | `list/usage/activity/update/rename/delete` | 런타임 확인 및 관리 | `usage`: `--days`(기본값 90, 최대 365). `update`: `--target-version`(필수), `--wait`. `delete`: `--cascade`(연결된 에이전트의 런타임을 해제하고 데이터를 보존하며 실행 취소) |
| | `profile list/create/update/delete` | 사용자 지정 런타임 profile 관리 | `create`: `--display-name`, `--command-name`(모두 필수), `--runtime-type`(또는 예전 `--protocol-family`), `--description`. `update`: `--enabled` |
| | `profile set-path/unset-path <profile-id>` | 로컬 실행 파일 경로 고정(로컬에만 적용되고 서버에 업로드되지 않음) | |

### Additional

| 명령 | 하위 명령 | 용도 | 주요 flag |
| --- | --- | --- | --- |
| `auth` | `status` / `logout` | 인증 상태 확인. `logout`은 로컬에 저장된 token만 삭제하고 서버 token은 취소하지 않음 | |
| `user` | `profile get/update` | 현재 사용자 profile 확인 또는 업데이트 | |
| `login` | — | 브라우저에서 로그인하고 모든 워크스페이스 자동 설정 | `--token`(값을 함께 쓰지 않으면 터미널에서 대화형 입력) |
| `setup` | `cloud`(기본), `self-host` | 서비스 주소 저장, 로그인 완료, 데몬 시작 | `self-host`: `--server-url`, `--app-url`, `--port`, `--frontend-port` |
| `attachment` | `download <attachment-id>`, `upload <path>` | 첨부 파일 다운로드 또는 업로드 | `download`: `--output-dir`. `upload`: `--task` |
| `config` | `show`, `set <key> <value>` | 현재 profile의 로컬 설정 확인 또는 변경 | 우선순위: 명령줄 flag > 환경 변수 > `config.json` > 내장 기본값. 빈 문자열로 설정하면 삭제 |
| `update` | — | CLI를 최신 버전으로 업데이트 | |
| `version` | — | 버전 정보 확인 | `--output`(`text` 또는 `json`) |

## 다른 코딩 에이전트에서 Multica 조작하기

작업 대부분이 Codex, Claude Code, Cursor 안에서 이루어진다면 터미널로 전환하지 않고 그곳에서 바로 Multica를 조작할 수 있습니다. [Multica CLI skill](https://github.com/multica-ai/multica-cli)은 이 페이지의 명령을 안전하게 다루는 방법을 해당 에이전트에게 가르칩니다. 토큰을 낭비하지 않고 태스크와 댓글 스레드를 읽고, 댓글은 파일을 통해 작성하며, 멘션·상태 변경·할당이 유발하는 부수 효과를 올바르게 처리합니다.

인증된 CLI를 통해서만 동작하며 그 자체로는 어떤 접근 권한도 부여하지 않습니다. 권한은 여전히 로그인, 선택한 profile, workspace에서 나옵니다. CLI v0.4.26 이상이 필요합니다. Claude Code 플러그인 마켓플레이스, Codex skill 설치 도구, Cursor를 비롯해 Markdown 지침을 읽어들이는 다른 도구의 설치 방법은 저장소 README를 참고하세요.

## 다음 단계

- [Multica CLI skill](https://github.com/multica-ai/multica-cli) — Codex, Claude Code, Cursor에서 Multica를 조작합니다.
- [인증과 토큰](/auth-tokens) — PAT 생성, 갱신, 취소를 알아봅니다.
- [문제 해결](/troubleshooting) — 명령 오류와 실행이 시작되지 않는 문제를 해결합니다.
- [에이전트 생성 및 설정](/agents-create) — `agent create` 각 필드의 전체 의미를 알아봅니다.