CLI 사용 | Melso Docs

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

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

설치

macOS / Linux

curl -fsSL https://downloads.melso.ai/install.sh | bash

Windows PowerShell

irm https://downloads.melso.ai/install.ps1 | iex

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

melso version

처음 연결

Melso Cloud 연결:

melso setup

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

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

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

melso auth status
melso daemon status

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

melso login --token

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

워크스페이스 선택

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

melso workspace list
melso workspace switch <slug>

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

멤버 초대:

melso workspace member invite teammate@example.com
melso workspace member invite admin@example.com --role admin

자주 사용하는 이슈 작업

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

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

# 댓글 및 실행 기록
melso issue comment list MUL-123
melso issue comment add MUL-123 --content "회귀 테스트를 먼저 확인해 주세요"
melso issue runs MUL-123

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

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

특정 실행의 메시지를 확인하거나 태스크를 중지합니다.

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

에이전트와 스킬

melso agent list
melso agent get <agent-id>
melso agent create --help
melso agent update <agent-id> --help

melso skill list
melso skill get <skill-id>
melso skill import --url <skill-url>
melso agent skills add <agent-id> --skill-ids <skill-id>

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

melso skill import --url <skill-url> --on-conflict overwrite
melso skill import --url <skill-url> --on-conflict rename
melso skill import --url <skill-url> --on-conflict skip

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

데몬과 런타임

melso daemon start
melso daemon stop
melso daemon restart
melso daemon status --output json
melso daemon logs --follow

melso runtime list
melso runtime rename <runtime-id> "Office Mac"
melso runtime usage <runtime-id>
melso runtime activity <runtime-id>

활성 에이전트가 계속 연결된 런타임을 삭제하면 명령이 기본적으로 거부됩니다. melso 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 업데이트 또는 버전 확인

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

ID와 출력 형식

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

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

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

melso issue list --output json
melso agent list --output json

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

Profile과 설정

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

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

melso issue list --profile staging

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

melso config show
melso config show --profile staging

CLI 설정 파일에는 사용자를 대신해 Melso에 접근할 수 있는 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`(반복 가능), `--limit`, `--offset`, `--sort`, `--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`(모두 필수), `--priority`, `--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 전용. 여기에 추가한 서버는 어떤 에이전트에도 할당되지 않으며 `melso 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`)

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

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

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

다음 단계

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