Using the CLI

Install and log in to the Clowld Space CLI, and manage workspaces, issues, agents, and runtimes from the terminal.

The Clowld Space CLI both connects local runtimes and manages workspaces, issues, agents, and automations from the terminal. Its executable remains clowld for upstream compatibility. This page covers the common paths; the flags your installed version supports are always defined by each command's own --help.

Installation

macOS / Linux

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

Clowld Space does not publish a Homebrew tap. Use this installer so you do not accidentally install the upstream Multica build.

Windows PowerShell

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

Confirm the install:

clowld version

If Desktop is installed, do not run the standalone installer as well. Desktop manages the official CLI under ~/.clowld-space/bin/, the user PATH entry, and CLI updates. It preserves unknown, self-built, and newer binaries; named profiles remain independent.

First connection

Connect to Clowld Space:

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

Connect to a self-hosted instance:

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

For a standalone CLI, setup saves the server address, opens a browser to complete sign-in, and starts the daemon. A Desktop-managed default CLI uses Desktop's sign-in and daemon instead of creating a second daemon. When it finishes, check:

clowld auth status
clowld daemon status

If you only need to sign in again without overwriting other configuration, run clowld login. On a machine without a browser, create a personal access token in the web settings first, then enter it with:

clowld login --token

The command prompts you to paste the token in the terminal, keeping the full value out of shell history.

Choosing a workspace

List workspaces and switch the default:

clowld workspace list
clowld workspace switch <slug>

Subsequent commands use this workspace. A single command can override it with --workspace-id, or you can set CLOWLD_WORKSPACE_ID.

Invite members:

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

Common issue operations

# View and search
clowld issue list
clowld issue get CS-123
clowld issue search "login failure"

# Create and update
clowld issue create --title "Fix login failure"
clowld issue status CS-123 in_progress
clowld issue assign CS-123 --to "Backend Agent"

# Comments and runs
clowld issue comment list CS-123
clowld issue comment add CS-123 --content "Check the regression tests first"
clowld issue comment update <comment-id> --expected-revision 2 --content "Check the regression tests and release notes"
clowld issue runs CS-123

Read long descriptions or comments from stdin to avoid dealing with newlines and quoting:

clowld issue create --title "Upgrade notes" --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

View the messages of a single run, or stop one:

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

Agents and skills

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>

When an import hits a skill with the same name, the default is to stop without modifying existing content. Pick by intent:

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 is only allowed for the skill's creator and preserves the original ID and agent bindings.

Agent run history

clowld agent tasks <agent-id> --limit 200 returns the newest page of runs. The default and maximum page size is 200. If more runs exist, stderr prints a cursor; pass it unchanged as --before '<cursor>' to read the next page. --output json keeps the array output and includes usage for that page only.

The corresponding GET /api/agents/{id}/tasks endpoint accepts limit and before, and keeps its JSON array response. The X-Agent-Tasks-Next-Cursor response header supplies the next cursor; its absence marks the final page. Cursors preserve (created_at, id) order, including timestamp precision. Invalid limits or cursors return HTTP 400; limits above 200 are capped. Clients that do not follow the cursor receive only the newest 200 runs.

Daemon and runtimes

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>

Deleting a runtime that still has active agents bound to it is refused by default. clowld runtime delete <id> --cascade unbinds those agents, preserves their configuration and history, and cancels their active runs.

See Daemon and runtimes for how it works and for custom profiles.

Boot autostart

Only an explicit human-local command registers a profile to start at login:

clowld daemon autostart enable
clowld daemon autostart status --output json
clowld daemon autostart disable

Add --profile <name> for an independent profile. daemon start does not register autostart; it only refreshes an enabled entry created by Clowld Space. Desktop and external supervisors retain their daemon lifecycle. Windows uses a per-user Run key, macOS a LaunchAgent, and Linux a systemd user unit or XDG autostart entry. Only PATH is captured for login; persist other settings in the profile or user environment. disable prevents the next login start and leaves the current daemon running. On Linux the disabled unit stays on disk to preserve its running service's self-update restart policy. User-created entries are left untouched.

Command overview

Command	Purpose
`issue`	Create, update, assign, and search issues; manage comments, subscribers, labels, properties, and runs
`topic`	Manage topics and their resources
`label`, `property`	Manage workspace labels and custom properties
`agent`, `skill`, `squad`	Manage agents, skills, and squads
`autopilot`	Manage automations, triggers, and run history
`workspace`	Create, view, and switch workspaces, and invite members
`repo`	Manage workspace repositories and check them out locally
`daemon`, `runtime`	Start and stop the local daemon; view and manage runtimes
`attachment`	Upload or download attachments
`user profile`	View or update the current user's profile
`auth`, `login`, `setup`	Log in, check auth status, and initialize a connection
`config`	View or edit the current CLI profile's local configuration
`update`, `version`	Update the CLI or print the version

clowld chat reads the external chat session an agent is currently handling; it is mainly for agents in chat integrations, not a general command for browsing arbitrary workspace conversations.

IDs and output formats

Issues use keys like CS-123 or full UUIDs; short UUID prefixes are not accepted.

list commands for other resources usually print copyable short IDs and support --full-id for the full UUID. When a short ID is ambiguous, the CLI asks for more characters or the full UUID. Short run IDs also require --issue to identify the owning issue.

Many commands support structured output:

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

Scripts should use JSON output rather than parsing the terminal-oriented tables. The output formats and pagination flags each command supports are defined by clowld <command> --help.

Profiles and configuration

The default configuration lives in ~/.clowld-space/cli/config.json. Use --profile <name> to isolate a separate set of server address, token, default workspace, and daemon state:

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

Named profiles live in ~/.clowld-space/cli/profiles/<name>/config.json. If the profile's preferred health port is unavailable, the daemon binds an available loopback port and records its port and PID in daemon.port beside that config. CLI lifecycle commands and Desktop validate the live profile and PID before using this record. It is a discovery hint, not a port setting. Inspect the current values:

clowld config show
clowld config show --profile staging

Do not set CLOWLD_DAEMON_PORT in the host shell, Compose service, or container entrypoint that starts a daemon. The host daemon normally derives its health port from --profile; if that port cannot be bound, it uses an available loopback port and injects the actual port into agent tasks itself. Remove the variable from older startup environments entirely: versions 0.4.22 and 0.4.23 otherwise mistake that shell for a managed task and reject login. Newer versions let guarded human login and daemon status recover when the port is the only task signal, but ordinary API and profile-resolving commands intentionally remain fail-closed until the variable is removed.

When the CLI runs inside a daemon-managed agent run, it does not load or modify these human-owned profile files. Clowld Space API commands authenticate with the task-scoped credential injected by the daemon. config show and config set use private task-local state; human/local commands such as login, logout, setup, workspace switch, local runtime profile path changes, daemon start / stop / restart, daemon logs, and daemon probe-runtimes are unavailable. auth status does not print token material in this context.

daemon status and daemon disk-usage stay available so an agent can inspect the runtime hosting it, scoped to that runtime: status probes the health port the daemon injected, and disk-usage scans the workspaces root the daemon injected. Neither accepts --profile, disk-usage also rejects --all-profiles and --workspaces-root, and its STATUS column is blank because resolving it would require the human's stored token. Use du and df for anything outside that scope.

This protects implicit Clowld Space CLI profile resolution while preserving the normal HOME and XDG variables used by other provider tools. It is not an OS filesystem boundary: processes running as the same system user may still open an explicitly known path. Use a dedicated user, container, VM, or equivalent isolation when that stronger guarantee is required.

CLI configuration files contain tokens that can access Clowld Space as you. Don't commit them to a repository, upload them to logs, or share them with others.

Command reference

The tables below cover every current top-level command, grouped the way the CLI itself groups them. All commands accept the global flags --server-url, --workspace-id, --profile, and --debug. --output is registered per command, and the default format varies: list commands default to a table, while get and create commands mostly default to JSON. Full flags are defined by clowld <command> --help.

Core

Command	Subcommand	Purpose	Key flags
`issue`	`list`	List issues	`--status`, `--priority`, `--assignee`, `--topic`, `--metadata` (repeatable), `--property` (repeatable, `"Name=Value"`; `__none__` matches unset), `--limit`, `--offset`, `--sort` (incl. `property:<name-or-id>`), `--full-id`, `--resolve-properties` (JSON only; rows with property, option and member names beside the stored ids)
	`get <id>`	Show a single issue	`--resolve-properties` (JSON only; rows with property, option and member names beside the stored ids)
	`create`	Create an issue	`--title` (required), `--description` / `--description-stdin` / `--description-file`, `--status`, `--priority`, `--assignee`, `--parent`, `--stage`, `--topic`, `--start-date`, `--due-date`, `--attachment` (repeatable), `--no-start`
	`update <id>`	Update issue fields	Same fields as `create`, plus `--position`
	`assign <id>`	Assign or unassign	`--to` (fuzzy name match against members, agents, and squads), `--to-id`, `--unassign`, `--no-start`
	`status <id> <status>`	Change status	`--no-start`
	`reorder <id>`	Move within a column
	`search <query>`	Search issues	`--limit`, `--include-closed`
	`children <id>`	List sub-issues grouped by stage
	`pull-requests <id>`	List linked PRs
	`comment list/add/delete/resolve/unresolve`	Manage comments	`add`: `--content` / `--content-stdin` / `--content-file`, `--parent`, `--attachment`; `list`: `--since`, `--thread`, `--tail`
	`subscriber list/add/remove <issue-id>`	Manage subscribers	`--user`, `--user-id` (defaults to the current user)
	`label list/add/remove <issue-id>`	Manage labels on an issue
	`metadata list/get/set/delete <issue-id>`	Manage issue-level key-value metadata
	`property list/set/unset <issue-id>`	Set custom property values	`set`: `--name`, `--value` (`actor` / `multi_actor` accept a member name, email, or id)
	`runs <issue-id>`	View run history	`--full-id`
	`run-messages <run-id>`	View the messages of a single run	`--since`, `--issue`
	`usage <issue-id>`	View aggregated token usage
	`rerun <id>`	Re-enqueue a run for the current assignee
	`cancel-task <run-id>`	Cancel a running or queued run	`--issue`
`topic`	`list/get/create/update/delete`	Manage topics
	`status <id> <status>`	Change topic status
	`resource list/add/update/remove`	Manage topic resources	`--type`, `--url`, `--local-path`, `--daemon-id`, `--execution-mode` (`in_place` / `worktree` for a local directory)
`label`	`list/get/create/update/delete`	Manage workspace labels	`list`: `--resource-type` (`issue` or `skill`), `--full-id`; `create`: `--name`, `--color`, `--resource-type` (`issue` or `skill`), `--description`
`property`	`list/get/create/update/archive/unarchive`	Manage workspace custom properties	`create`: `--name`, `--type` (`text`, `number`, `select`, `multi_select`, `date`, `checkbox`, `url`, `actor`, `multi_actor`, `multi_text`, `multi_url`), `--option` (repeatable, select types only); `list`: `--include-archived`; the type cannot be changed after creation
`agent`	`list/get/create/update/archive/restore`	Manage agents	`--name`, `--runtime-id` (required for `create`), `--instructions`, `--conversation-starters`, `--model`, `--thinking-level`, `--mcp-config`, `--permission-mode`, `--max-concurrent-tasks`
	`copy <agent-id>`	Copy into a new agent; the original is untouched	`--name` (defaults to the original name plus `(copy)`), `--runtime-id` (copying to another runtime also requires `--model`), `--no-skills`; secret configuration such as `custom_env`, `mcp_config`, and `runtime_config` is not copied — re-provide it with the same flags as `create`
	`tasks <id>`	View an agent's runs
	`avatar <id>`	Upload an avatar
	`env get/set <agent-id>`	Read and write custom environment variables (owner and admin only)
	`skills list/set/add <agent-id>`	Manage attached skills	`--skill-ids` (`set` replaces the full list, `add` appends)
	`mcp list/add/enable/disable/remove <agent-id>`	Assign workspace MCP servers to this agent	Take the server id from `workspace mcp list`. A library entry does nothing until it is added here; `disable` stops sending it without dropping the assignment
`autopilot`	`list/get/create/update/delete`	Manage automations	`create`: `--title`, `--agent`, `--mode` (all required), `--topic`, `--subscriber` (repeatable)
	`trigger <id>`	Trigger a run manually
	`runs <id>`	View run history
	`trigger-list/trigger-add/trigger-update/trigger-delete/trigger-rotate-url`	List trigger IDs and manage schedule and webhook triggers	`trigger-list`: `--full-id`, `--output`
`workspace`	`list/get/create/update/switch`	Manage workspaces; `switch` sets the current profile's default workspace
	`mcp list/add/update/remove`	Manage the workspace's MCP server library	Writes are owner/admin. A server added here is assigned to no agent — give it to one with `clowld agent mcp add`. `list` shows names and transports only; the stored entry is write-only and never returned. `--server-config-file` / `--server-config-stdin` keep tokens out of shell history
	`member list/invite <email>`	View members, send invites	`invite`: `--role` (member or admin, default member)
`repo`	`list/add/remove/checkout`	Manage workspace repositories and check them out locally	`--url` (repeatable); `checkout`: `--ref`
`skill`	`list/get/create/update/delete`	Manage skills
	`import`	Import a skill from a URL or local file	`--url` / `--file`, `--on-conflict` (`fail`, `overwrite`, `rename`, `skip`; default `fail`)
	`search <query>`	Search skills
	`files list/upsert/delete <skill-id>`	Manage the files inside a skill
	`label list/add/remove <skill-id>`	Manage labels on a skill	`add` / `remove`: `<label-id>` accepts a full UUID or short prefix
`squad`	`list/get/create/update/delete`	Manage squads (`delete` archives)
	`member list/add/set-role/remove`	Manage squad members
	`activity <issue-id> <outcome>`	Record a leader evaluation
`chat`	`history`, `thread [id]`	Read the external chat session an agent is currently handling	`--limit`, `--before`

Runtime

Command	Subcommand	Purpose	Key flags
`daemon`	`start`	Start the local daemon	`--foreground`, `--device-name`, `--runtime-name`, `--workspaces-root`, `--poll-interval`, `--heartbeat-interval`, `--agent-timeout` (`0` means no limit), `--max-concurrent-tasks`, `--no-auto-update`; each has a matching `CLOWLD_*` environment variable
	`stop` / `status` / `restart`	Stop, check status, restart (`restart` takes the same flags as `start`)
	`logs`	View daemon logs	`--follow`, `--lines`
	`disk-usage`	View local disk usage	`--by-workspace`, `--by-task`, `--top`
`runtime`	`list/usage/activity/update/rename/delete`	View and manage runtimes	`delete`: `--cascade` (unbinds bound agents, preserves their data, and cancels their runs)
	`profile list/create/update/delete`	Manage custom runtime profiles
	`profile set-path/unset-path <profile-id>`	Pin a local executable path (local only, never uploaded to the server)

Additional

Command	Subcommand	Purpose	Key flags
`auth`	`status` / `logout`	Check auth status; `logout` only deletes the locally saved token and does not revoke it on the server
`user`	`profile get/update`	View or update the current user's profile
`login`	—	Sign in via the browser and configure all workspaces automatically	`--token` (prompts interactively in the terminal when passed without a value)
`setup`	`cloud` (default), `self-host`	Save the server address, complete sign-in, and start the daemon	`self-host`: `--server-url`, `--app-url`, `--port`, `--frontend-port`
`attachment`	`download <attachment-id>`, `upload <path>`	Download or upload attachments	`download`: `--output-dir`; `upload`: `--task`
`config`	`show`, `set <key> <value>`	View or edit the current profile's local configuration	Precedence: command-line flags > environment variables > `config.json` > built-in defaults; set an empty string to clear a value
`update`	—	Update the CLI to the latest version
`version`	—	Print version information	`--output` (`text` or `json`)

Driving Clowld Space from another coding agent

Agents launched by Clowld Space through Codex, Claude Code, Cursor, and other supported runtimes receive built-in skills that teach the clowld commands on this page. They cover token-efficient issue and comment reads, file-based comment writes, and the side effects of mentions, status changes, and assignments.

The skills run through the task-scoped CLI credential supplied by Clowld Space and grant no access of their own. Permissions still come from the task's member, workspace, and agent scope; there is no separate CLI-skill login to maintain.

Next steps

Skills — understand how Clowld Space delivers reusable instructions to agents.
Authentication and tokens — creating, renewing, and revoking PATs.
Troubleshooting — diagnosing command errors and runs that never start.
Create and configure an agent — the full semantics of every agent create field.

On this page