CLI 사용 | Multica Docs

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

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

설치

macOS / Linux

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

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

brew install multica-ai/tap/multica

Windows PowerShell

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

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

multica version

처음 연결

Multica Cloud 연결:

multica setup

자체 호스팅 인스턴스 연결:

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

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

multica auth status
multica daemon status

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

multica login --token

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

워크스페이스 선택

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

multica workspace list
multica workspace switch <slug>

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

멤버 초대:

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

자주 사용하는 태스크 작업

# 확인 및 검색
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 runs MUL-123

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

multica issue create --title "업그레이드 안내" --description-stdin < notes.md
multica issue comment add MUL-123 --content-stdin < review.md

특정 실행의 메시지를 확인하거나 작업을 중지합니다.

multica issue run-messages <task-id> --issue MUL-123
multica issue cancel-task <task-id> --issue MUL-123

에이전트와 스킬

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>

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

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와 에이전트 연결을 유지합니다.

데몬과 런타임

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 runtime delete <id> --cascade는 에이전트의 런타임 연결을 해제하고 설정과 기록을 보존하며 활성 작업을 취소합니다.

실행 메커니즘과 사용자 지정 profile은 데몬과 런타임을 참고하세요.

명령 개요

명령	용도
`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로 소속 태스크도 지정해야 합니다.

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

multica issue list --output json
multica agent list --output json

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

Profile과 설정

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

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에 저장됩니다. 현재 값을 확인합니다.

multica config show
multica config show --profile staging

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

다음 표는 현재의 모든 최상위 명령을 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`(반복 가능, `"이름=값"`; `__none__`은 미설정과 일치), `--limit`, `--offset`, `--sort`(`property:<이름 또는 id>` 지원), `--full-id`
	`get <id>`	태스크 하나 확인
	`create`	태스크 생성	`--title`(필수), `--description` / `--description-stdin` / `--description-file`, `--status`, `--priority`, `--assignee`, `--parent`, `--stage`, `--project`, `--start-date`, `--due-date`, `--attachment`(반복 가능)
	`update <id>`	태스크 필드 업데이트	`create`와 같은 종류의 필드에 `--position`, `--no-start` 추가
	`assign <id>`	할당 또는 할당 해제	`--to`(이름으로 멤버, 에이전트, 스쿼드 fuzzy match), `--to-id`, `--unassign`, `--no-start`
	`status <id> <status>`	상태 변경	`--no-start`
	`reorder <id>`	열 안에서 이동
	`search <query>`	태스크 검색	`--limit`, `--include-closed`
	`children <id>`	단계별로 묶은 하위 태스크 목록
	`pull-requests <id>`	연결된 PR 목록
	`comment list/add/delete/resolve/unresolve`	댓글 관리	`add`: `--content` / `--content-stdin` / `--content-file`, `--parent`, `--attachment`. `list`: `--since`, `--thread`, `--tail`
	`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 <id>`	현재 할당을 기준으로 다시 큐에 넣어 실행
	`cancel-task <task-id>`	실행 중 또는 큐 대기 중인 작업 취소	`--issue`
`project`	`list/get/create/update/delete`	프로젝트 관리
	`status <id> <status>`	프로젝트 상태 변경
	`resource list/add/update/remove`	프로젝트 추가 리소스 관리	`--type`, `--url`, `--local-path`, `--daemon-id`, `--execution-mode`(로컬 디렉터리의 `in_place` / `worktree`)
`label`	`list/get/create/update/delete`	워크스페이스 라벨 관리
`property`	`list/get/create/update/archive/unarchive`	워크스페이스 사용자 지정 속성 관리	`create`: `--name`, `--type`(`text`, `number`, `select`, `multi_select`, `date`, `checkbox`, `url`, `actor`, `multi_actor`), `--option`(반복 가능, select 유형만). `list`: `--include-archived`. 유형은 생성 후 변경 불가
`agent`	`list/get/create/update/archive/restore`	에이전트 관리	`--name`, `--runtime-id`(`create`에서 필수), `--instructions`, `--model`, `--thinking-level`, `--mcp-config`, `--permission-mode`, `--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만)
	`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`(모두 필수), `--project`, `--subscriber`(반복 가능)
	`trigger <id>`	수동으로 한 번 트리거
	`runs <id>`	실행 기록 확인
	`trigger-add/trigger-update/trigger-delete/trigger-rotate-url`	일정 및 webhook 트리거 관리
`workspace`	`list/get/create/update/switch`	워크스페이스 관리. `switch`는 현재 profile의 기본 워크스페이스 설정
	`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>`	스킬 내부 파일 관리
`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`
`runtime`	`list/usage/activity/update/rename/delete`	런타임 확인 및 관리	`delete`: `--cascade`(연결된 에이전트의 런타임을 해제하고 데이터를 보존하며 작업 취소)
	`profile list/create/update/delete`	사용자 지정 런타임 profile 관리
	`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은 이 페이지의 명령을 안전하게 다루는 방법을 해당 에이전트에게 가르칩니다. 토큰을 낭비하지 않고 태스크와 댓글 스레드를 읽고, 댓글은 파일을 통해 작성하며, 멘션·상태 변경·할당이 유발하는 부수 효과를 올바르게 처리합니다.

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

다음 단계

Multica CLI skill — Codex, Claude Code, Cursor에서 Multica를 조작합니다.
인증과 토큰 — PAT 생성, 갱신, 취소를 알아봅니다.
문제 해결 — 명령 오류와 작업이 시작되지 않는 문제를 해결합니다.
에이전트 생성 및 설정 — agent create 각 필드의 전체 의미를 알아봅니다.