CLI Reference

The Clawdentity CLI (clawdentity) is the primary operator tool for managing agent identities, keys, and provider integrations.

Admin commands

admin bootstrap

Bootstraps the registry by creating the first admin account and PAT.

clawdentity admin bootstrap \
  --registry-url <url> \
  --bootstrap-secret <secret>

The returned API key is printed once and persisted to local config. If config persistence fails, the token is still printed for manual recovery.

Config commands

config init

Initialize local config file at ~/.clawdentity/config.json.

clawdentity config init [--registry-url <url>]

Options:

• --registry-url <url> — override registry URL

Creates the file with default values if it does not already exist. Auto-fetches registry metadata via GET /v1/metadata to resolve proxyUrl.

config set

Set a config value.

clawdentity config set <key> <value>

Valid keys: registryUrl, proxyUrl, apiKey, humanName.

config get

Get a resolved config value.

clawdentity config get <key>

Prints (not set) when the key has no value.

config show

Show all resolved config values.

clawdentity config show

Outputs JSON with apiKey masked as ********.

Invite commands

invite create

Creates a registry onboarding invite code. Requires admin authentication.

clawdentity invite create [--expires-at <timestamp>] [--registry-url <url>]

Options:

• --expires-at <timestamp> — optional invite expiry (ISO-8601)
• --registry-url <url> — override registry URL

Returns a single-use, time-limited invite code (clw_inv_<random>).

invite redeem

Redeems an invite code to create an account and receive an API key.

clawdentity invite redeem <code> [--display-name <name>] [--registry-url <url>]

Options:

• --display-name <name> — human display name for onboarding
• --registry-url <url> — override registry URL

The plaintext PAT is printed before config persistence so operators can recover from local write failures.

Agent commands

agent create

Creates a new agent identity using a two-step challenge-response handshake.

clawdentity agent create <name> [--framework <framework>] [--ttl-days <days>]

Options:

• --framework <framework> — agent framework label (registry defaults to openclaw)
• --ttl-days <days> — agent token TTL in days (registry default when omitted)

Generates an Ed25519 keypair locally, proves key ownership to the registry, and stores all credentials under ~/.clawdentity/agents/<name>/.

agent inspect

Displays agent identity details and token metadata.

clawdentity agent inspect <name>

agent auth revoke

Revokes an agent’s active auth session tokens. Use this when you need to invalidate connector/session auth for an agent without deleting the agent identity.

clawdentity agent auth revoke <name>

agent auth refresh

Refreshes agent auth tokens using Claw + PoP headers.

clawdentity agent auth refresh <name>

Rewrites registry-auth.json atomically on success.

API key commands

api-key create

Creates a new PAT. The token is printed once and not persisted automatically.

clawdentity api-key create --name <key-name>

api-key list

Lists PAT metadata (never exposes token values).

clawdentity api-key list

api-key revoke

Revokes a specific PAT by ULID.

clawdentity api-key revoke <key-id>

Install command

install

Detects or selects a provider platform and installs provider artifacts and defaults.

clawdentity install [--for <platform>] [--port <port>] [--token <token>] [--json]

Options:

• --for <platform> — explicit platform (openclaw, picoclaw, nanobot, nanoclaw)
• --port <port> — webhook port override
• --token <token> — webhook auth token override
• --json — machine-readable JSON output

List providers:

clawdentity install --list [--json]

Provider commands

provider status

Reports auto-detected provider status or explicit provider diagnostics.

clawdentity provider status [--for <platform>] [--json]

provider setup

Configures provider runtime integration (paths, webhook settings, connector options).

clawdentity provider setup \
  --for <platform> \
  [--agent-name <name>] \
  [--platform-base-url <url>] \
  [--webhook-host <host>] \
  [--webhook-port <port>] \
  [--webhook-token <token>] \
  [--connector-base-url <url>] \
  [--connector-url <url>] \
  [--relay-transform-peers-path <path>] \
  [--json]

provider doctor

Runs provider health checks for config, runtime wiring, and connector readiness.

clawdentity provider doctor \
  [--for <platform>] \
  [--peer <alias>] \
  [--platform-state-dir <path>] \
  [--connector-base-url <url>] \
  [--skip-connector-runtime] \
  [--json]

provider relay-test

Sends a relay probe to a peer alias using provider runtime settings.

clawdentity provider relay-test \
  [--for <platform>] \
  [--peer <alias>] \
  [--platform-state-dir <path>] \
  [--platform-base-url <url>] \
  [--webhook-token <token>] \
  [--connector-base-url <url>] \
  [--message <text>] \
  [--session-id <id>] \
  [--no-preflight] \
  [--json]

Pairing and cross-agent trust

Proxy trust pairing is supported through proxy API routes (POST /pair/start, POST /pair/confirm, POST /pair/status).

The current Rust CLI surface in this branch does not expose pair subcommands yet. Use the proxy API/SDK flow documented in:

• /api-reference/proxy/
• /guides/discovery/

Connector commands

connector start

Starts the local relay connector runtime.

clawdentity connector start <agentName> \
  [--proxy-ws-url <url>] \
  [--openclaw-base-url <url>] \
  [--openclaw-hook-path <path>] \
  [--openclaw-hook-token <token>]

Options:

• --proxy-ws-url <url> — proxy websocket URL (or CLAWDENTITY_PROXY_WS_URL env)
• --openclaw-base-url <url> — OpenClaw base URL (default OPENCLAW_BASE_URL env or http://127.0.0.1:18789)
• --openclaw-hook-path <path> — OpenClaw hooks path (default OPENCLAW_HOOK_PATH env or /hooks/agent)
• --openclaw-hook-token <token> — OpenClaw hooks token (default OPENCLAW_HOOK_TOKEN env)

connector service install

Installs autostart service using OS-native tooling (launchd on macOS, systemd on Linux).

clawdentity connector service install <agentName> \
  [--platform <platform>] \
  [--proxy-ws-url <url>] \
  [--openclaw-base-url <url>] \
  [--openclaw-hook-path <path>] \
  [--openclaw-hook-token <token>]

Options:

• --platform <platform> — service platform: auto, launchd, or systemd (default auto)
• --proxy-ws-url <url> — proxy websocket URL (or CLAWDENTITY_PROXY_WS_URL env)
• --openclaw-base-url <url> — OpenClaw base URL override for connector runtime
• --openclaw-hook-path <path> — OpenClaw hooks path override for connector runtime
• --openclaw-hook-token <token> — OpenClaw hooks token override for connector runtime

connector service uninstall

Removes the autostart service. Safe to re-run.

clawdentity connector service uninstall <agentName> [--platform <platform>]

Options:

• --platform <platform> — service platform: auto, launchd, or systemd (default auto)

Command idempotency

Command	Idempotent?	Note
config init	Yes	Safe to re-run
invite redeem	No	One-time; invite consumed on success
agent create	No	Fails if agent directory exists
agent auth revoke	Yes	Safe to re-run; token state remains revoked
install --for <platform>	Yes	Reports platform install and verify status
provider setup --for <platform>	Usually yes	Primary reconciliation re-entry point
provider doctor --for <platform>	Yes	Read-only health checks
provider relay-test --for <platform>	Mostly yes	Sends real probe traffic
connector service install	Yes	Idempotent