CLI Reference

Clawrium provides the clawctl command-line interface for managing your AI claw fleet.

Installation

uv tool install clawrium

Or run without installing:

uvx --from clawrium clawctl --help

Command Structure

clawctl <command> [options]
clawctl <group> <command> [options]

Root Commands

Command	Description
clawctl service init	Initialize Clawrium and check dependencies
clawctl agent describe	Show fleet status across all hosts
clawctl agent create	Install an agent on a host

Command Groups

Group	Description
clawctl host	Manage hosts in your fleet
clawctl agent registry	Browse available claw types
clawctl agent secret	Manage secrets for claw instances

---

clawctl service init

Initialize Clawrium configuration directory and check dependencies.

clawctl service init

Creates the configuration directory at ~/.config/clawrium/ (or $XDG_CONFIG_HOME/clawrium/ if set) and verifies that all required dependencies are available.

Example

$ clawctl service init
Clawrium initialized!
Config directory: /home/user/.config/clawrium

┏━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Dependency    ┃ Status  ┃ Version/Path   ┃ Action Required          ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ ansible       │ OK      │ 2.15.0         │ -                        │
│ ssh           │ OK      │ /usr/bin/ssh   │ -                        │
│ python        │ OK      │ 3.11.0         │ -                        │
└───────────────┴─────────┴────────────────┴──────────────────────────┘

Exit Codes

Code	Meaning
0	All dependencies found
1	One or more dependencies missing

---

clawctl agent describe

Show fleet status across all hosts.

clawctl agent describe [--host HOST]

Displays claw instances grouped by claw type with live health checks. Shows name, version, host, and status for each installed claw.

Options

Option	Short	Description
--host	-H	Filter to specific host (hostname or alias)

Example

$ clawctl agent describe
                         zeroclaw
┏━━━━━━━━━━┳━━━━━━━━━┳━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Host     ┃ Version ┃ User ┃ Status   ┃ Installed  ┃
┡━━━━━━━━━━╇━━━━━━━━━╇━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━┩
│ pi-lab   │ 0.1.0   │ zc   │ running  │ 2026-04-01 │
│ nuc-01   │ 0.1.0   │ zc   │ degraded │ 2026-03-28 │
└──────────┴─────────┴──────┴──────────┴────────────┘

Filter to a specific host:

$ clawctl agent describe --host pi-lab

Status Values

Status	Meaning
running	Claw is healthy and operational
degraded	Claw is running but missing required secrets
stopped	Claw service is not running
not installed	Claw record exists but service not found
install failed	Installation did not complete successfully
installing...	Installation in progress

---

clawctl agent create

Install an agent on a host.

clawctl agent create [--type AGENT_TYPE] [--host HOST] [--yes]

Without flags, prompts for agent type and host selection interactively. With --type and --host flags, runs directly for scripting.

Options

Option	Short	Description
--type	-t	Agent type to install (e.g., zeroclaw)
--host	-H	Target host (hostname or alias)
--yes	-y	Skip confirmation prompt

Interactive Example

$ clawctl agent create

Available agent types:
  1. zeroclaw (v0.1.0) - Zero-config Claude assistant
  2. openclaw (v0.2.0) - OpenAI-powered assistant

Select agent type: 1

Available hosts:
  1. pi-lab (aarch64, 4.0GB)
  2. nuc-01 (x86_64, 16.0GB)

Select host: 1

╭─────────────────────────────────────────╮
│          Installation Summary           │
├─────────────────────────────────────────┤
│ Agent Type: zeroclaw                    │
│ Version: 0.1.0                          │
│ Host: pi-lab                            │
│ Architecture: aarch64                   │
│ Memory: 4.0GB                           │
╰─────────────────────────────────────────╯

Proceed with installation? [y/N]: y

Success! zeroclaw v0.1.0 installed on pi-lab

Non-Interactive Example

$ clawctl agent create --type zeroclaw --host pi-lab --yes

Exit Codes

Code	Meaning
0	Installation successful
1	Installation failed or cancelled