CSGClaw: CLI reference

← Back to CSGClaw overview

csgclaw handles init, local service lifecycle, agent management, and collaboration commands. csgclaw-cli exposes only bot / room / member / message for scripts and agents. Both talk to the local HTTP API and do not drive the sandbox or channel SDKs directly.

Common conventions

Output

• --output table: human-readable tables or text.
• --output json: structured JSON.
• Default: table in a TTY; json when piped or redirected.
• Commands like serve, stop, agent logs follow current version behavior.

Environment

• CSGCLAW_BASE_URL: default API base.
• CSGCLAW_ACCESS_TOKEN: default token.
• CLI flags --endpoint / --token override env when both are set.

Channels

• Many collaboration commands accept --channel: csgclaw (default) or feishu.

Paths ( csgclaw only)

• --config: default ~/.csgclaw/config.toml.
• Daemon log: ~/.csgclaw/server.log; PID: ~/.csgclaw/server.pid.
• Agent state: ~/.csgclaw/agents/state.json; IM state: ~/.csgclaw/im/state.json.

Global layout

csgclaw [global-flags] <command> [args]

Global flags

Flag	Meaning
--endpoint	HTTP base; default CSGCLAW_BASE_URL
--token	API token; default CSGCLAW_ACCESS_TOKEN
--output	table | json
--config	Config file path
--version / -V	Print version

Top-level commands: onboard, serve, stop, agent, user, bot, room, member, message.

csgclaw onboard

Initialize local config and bootstrap state.

Flag	Description
--provider	csghub-lite, custom
--base-url	LLM base URL
--api-key	LLM API key
--models	Comma-separated model IDs
--reasoning-effort	Optional default upstream reasoning_effort
--manager-image	Bootstrap Manager image
--debian-registries	Comma-separated OCI registries for debian:bookworm-slim
--force-recreate-manager	Delete and recreate bootstrap Manager box

With no config and no model flags, an interactive wizard may run; scripts should pass models explicitly. Incomplete model config makes serve fail with a prompt to fix it.

csgclaw serve / stop

Command	Description
serve [-d|--daemon]	Start server; --daemon runs in background; optional --log, --pid
stop	Sends SIGTERM via PID file

csgclaw agent

Subcommands: list, create, start, stop, delete, logs, status.

Subcommand	Summary
list [--filter]	List agents; optional status filter
create --name ... [--id] [--description] [--profile]	Create
start <id> / stop <id>	Start / stop
delete <id> / delete --all [-f]	Delete; --all batch; -f skip confirm
logs <id> [-f] [-n lines]	Logs; -n must be > 0; --follow often incompatible with --output json
status [id]	One agent if id given; else like list

csgclaw user

Subcommands: list, create, delete. All support --channel (csgclaw / feishu). create requires --name; Feishu may use --avatar, etc.

Collaboration (bot / room / member / message)

Same flags and validation as csgclaw-cli.

bot: list, create, delete

• list: --channel, --role (manager / worker)
• create: --name (required), --role (manager | worker, required), --id, --description, --channel, --model-id
• delete <id> [--channel]

room: list, create, delete

• create: --title, --description, --creator-id, --member-ids (comma-separated), --locale, --channel

member: list, create

• list: --room-id, --channel
• create: --room-id, --user-id (required), --inviter-id, --locale, --channel

message: list, create

• list: --room-id (required), --channel
• create: --room-id, --sender-id, --content (required), optional --mention-id, --channel

csgclaw-cli

csgclaw-cli [global-flags] <command>

Globals: --endpoint, --token, --output, --version.
Commands: bot, room, member, message (same subcommands as under csgclaw).

HTTP and config.toml fields: API & config.