CLI 사용 | Clowld Space Docs

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

Clowld Space CLI는 로컬 런타임을 연결할 뿐 아니라 터미널에서 워크스페이스, 태스크, 에이전트, 자동화를 관리할 수 있습니다. 업스트림 호환성을 위해 실행 파일 이름은 계속 clowld를 사용합니다. 이 페이지에서는 자주 사용하는 경로를 설명합니다. 현재 버전에서 지원하는 인수는 항상 명령 자체의 --help를 기준으로 확인하세요.

설치

macOS / Linux

curl -fsSL https://updates.clowld.xyz/cli/install.sh | bash

Clowld Space는 아직 별도의 Homebrew Tap을 배포하지 않습니다. Multica 업스트림 빌드를 잘못 설치하지 않도록 위 설치 프로그램을 사용하세요.

Windows PowerShell

irm https://updates.clowld.xyz/cli/install.ps1 | iex

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

clowld version

Desktop이 설치되어 있다면 독립 설치 프로그램을 다시 실행할 필요가 없습니다. Desktop이 ~/.clowld-space/bin/의 공식 CLI, 사용자 PATH, 업데이트를 관리합니다. 출처를 알 수 없거나 직접 빌드했거나 더 최신인 바이너리는 덮어쓰지 않으며, 이름 있는 profile은 독립적으로 유지됩니다.

처음 연결

Clowld Space 연결:

clowld setup self-host --server-url https://api.clowld.com --app-url https://space.clowld.com

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

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

독립 CLI의 setup은 서비스 주소를 저장하고 브라우저 로그인을 마친 뒤 데몬을 시작합니다. Desktop이 관리하는 기본 CLI는 두 번째 데몬을 만들지 않고 Desktop의 로그인과 데몬을 사용합니다. 완료 후 다음을 확인하세요.

clowld auth status
clowld daemon status

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

clowld login --token

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

워크스페이스 선택

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

clowld workspace list
clowld workspace switch <slug>

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

멤버 초대:

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

자주 사용하는 태스크 작업

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

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

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

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

clowld issue create --title "업그레이드 안내" --description-stdin < notes.md
clowld issue comment add CS-123 --content-stdin < review.md
clowld issue comment update <comment-id> --expected-revision 2 --content-file revised-review.md

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

clowld issue run-messages <task-id> --issue CS-123
clowld issue cancel-task <task-id> --issue CS-123

에이전트와 스킬

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

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

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

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

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

데몬과 런타임

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

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

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

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

명령 개요

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

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

ID와 출력 형식

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

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

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

clowld issue list --output json
clowld agent list --output json

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

Profile과 설정

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

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

clowld issue list --profile staging

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

clowld config show
clowld config show --profile staging

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

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

Core

명령	하위 명령	용도	주요 flag
`issue`	`list`	태스크 목록	`--status`, `--priority`, `--assignee`, `--topic`, `--metadata`(반복 가능), `--property`(반복 가능, `"이름=값"`; `__none__은 미설정과 일치),` --limit`,` --offset`,` --sort`(`property:이름 또는 id`지원),`--full-id`,` --resolve-properties`(JSON 전용; 저장된 id와 함께 속성, 옵션, 멤버 이름을 반환)
	`get <id>`	태스크 하나 확인	`--resolve-properties`(JSON 전용; 저장된 id와 함께 속성, 옵션, 멤버 이름을 반환)
	`create`	태스크 생성	`--title`(필수), `--description` / `--description-stdin` / `--description-file`, `--status`, `--priority`, `--assignee`, `--parent`, `--stage`, `--topic`, `--start-date`, `--due-date`, `--attachment`(반복 가능), `--no-start`
	`update <id>`	태스크 필드 업데이트	`create`와 같은 종류의 필드에 `--position` 추가
	`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`
`topic`	`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`	워크스페이스 라벨 관리	`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`, `--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`(모두 필수), `--topic`, `--subscriber`(반복 가능)
	`trigger <id>`	수동으로 한 번 트리거
	`runs <id>`	실행 기록 확인
	`trigger-list/trigger-add/trigger-update/trigger-delete/trigger-rotate-url`	트리거 ID를 나열하고 일정 및 webhook 트리거 관리	`trigger-list`: `--full-id`, `--output`
`workspace`	`list/get/create/update/switch`	워크스페이스 관리. `switch`는 현재 profile의 기본 워크스페이스 설정
	`mcp list/add/update/remove`	워크스페이스의 MCP 서버 라이브러리를 관리	쓰기는 owner/admin 전용. 여기에 추가한 서버는 어떤 에이전트에도 할당되지 않으며 `clowld 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`. 모두 대응하는 `CLOWLD_*` 환경 변수가 있음
	`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`)

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

Clowld Space가 Codex, Claude Code, Cursor 같은 지원 런타임에서 에이전트를 시작하면 이 페이지의 clowld 명령을 가르치는 내장 skill이 자동으로 전달됩니다. 태스크와 댓글 스레드를 적은 토큰으로 읽고, 파일을 통해 댓글을 작성하며, 멘션·상태 변경·할당의 부수 효과를 올바르게 처리하는 방법이 포함됩니다.

이 skill은 Clowld Space가 태스크에 주입한 전용 CLI 자격 증명을 사용하며 자체적으로 권한을 늘리지 않습니다. 권한은 태스크를 시작한 멤버, workspace, 에이전트 범위에서 결정되며 별도의 CLI skill 로그인을 관리할 필요가 없습니다.

다음 단계

Skill — Clowld Space가 재사용 가능한 지침을 에이전트에 전달하는 방식을 확인합니다.
인증과 토큰 — PAT 생성, 갱신, 취소를 알아봅니다.
문제 해결 — 명령 오류와 실행이 시작되지 않는 문제를 해결합니다.
에이전트 생성 및 설정 — agent create 각 필드의 전체 의미를 알아봅니다.