arkclaw-webchat-cli 0.5.1

CLI to chat with an ArkClaw EE space's Claw over enterprise SSO — zero permanent AK/SK.

arkclaw

Chat with your ArkClaw claws (agents) from the terminal — log in with your own SSO identity, no passwords, no permanent keys. Works the same for a human at a prompt and for another agent/script (--json + exit codes).

arkclaw init        # one-time interactive setup (asks only what it can't auto-detect)
arkclaw login       # browser SSO
arkclaw agents      # list the claws you can chat
arkclaw chat ci-xxxxxxxx

---

What it can do

• Log in as you — browser SSO (PKCE), short-lived token, auto-refresh. No AK/SK, no client secret, nothing permanent on disk but a token in your OS keychain.
• List your agents — arkclaw agents shows the claws you've chatted with (kept locally; add one with arkclaw chat ci-...).
• Chat — interactive REPL or one-shot -m, streaming token-by-token, with a live "what's it doing" spinner and tool-event trace.
• Talk to a specific claw — by id (chat ci-...) or by name (chat 答疑助手).
• Manage a claw's files — read/write its managed workspace files (AGENTS.md, SOUL.md, MEMORY.md, …) with ls / pull / push.
• Fan out — send one message to many claws in parallel.
• Be scripted — every command takes --json (one clean {ok,data,error} envelope on stdout) and returns a typed exit code.

Two transports, picked at login: openclaw (your claws, the default) and a2a (an agent endpoint).

---

Install

pip install arkclaw-webchat-cli          # provides the `arkclaw` command

From source:

git clone <repo> && cd ee-claw
uv venv && uv pip install -e .

---

Quick start

# 0. one-time setup — interactive. Asks for your space address and (only if the
#    space doesn't already publish them) the CLI client + STS role. Saved to
#    ~/.arkclaw/defaults.json so you never type them again.
arkclaw init

# 1. log in (a browser opens; sign in with SSO)
arkclaw login

# 2. list the claws you've used (empty at first — you add them by chatting)
arkclaw agents

# 3. chat — interactive…
arkclaw chat ci-xxxxxxxx
#    …or one-shot:
arkclaw chat ci-xxxxxxxx -m "用一句话介绍你自己"

arkclaw init resolves everything it can from the address (identity pool, region) and only prompts for what's missing. Once your space publishes auto-discovery, init asks for nothing but the address — and you can even skip straight to arkclaw login https://your-space.... See Configuration.

---

Commands

Command	What it does
arkclaw init [address]	One-time interactive setup. Saves the address + (only what isn't auto-discovered) the CLI client and STS role to ~/.arkclaw/defaults.json, so later commands need no env/flags.
arkclaw login [space-url]	Browser SSO login. Uses init defaults if you omit the URL. --transport a2a --endpoint <url> for an agent endpoint. --clawid ci-... sets a default claw. Bare arkclaw login re-logs into the previous space.
arkclaw agents	List the claws you've used from this machine (local history, newest first) + your default claw. Add a claw by chatting it once (arkclaw chat ci-...). Not a space-wide directory.
arkclaw chat [TARGET] [MSG]	Chat. TARGET = a claw id (ci-...), an agent name (from agents), or a profile. With MSG → one-shot; without → interactive REPL. -f attach files, -o write the reply, --session NAME name the conversation, --approve-all auto-approve tool runs.
arkclaw <name>	Shortcut: arkclaw 答疑助手 ≡ arkclaw chat 答疑助手.
arkclaw ls	List the claw's managed workspace files.
arkclaw pull <name> [local]	Download a managed file to local disk.
arkclaw push <local> [name]	Write a local text file into a managed file.
arkclaw fanout "<msg>" --clawid ci-a --clawid ci-b	Same message to many claws in parallel.
arkclaw sessions	Recent chat sessions on this machine.
arkclaw profile save/use/list	Named snapshots of the session config (multi-space / multi-claw).
arkclaw doctor	Self-check: login freshness, keychain, pool/STS/endpoint reachability.
arkclaw schema --json	Machine-readable command surface (for agents/tooling).
arkclaw claw list/describe/create/delete	Fleet management on the control plane.

All commands accept --clawid ci-... (where relevant) to target a specific claw, and --json for machine output.

---

Chatting

arkclaw chat ci-xxxx                       # REPL with that claw (Ctrl-C: interrupt turn; twice: exit)
arkclaw chat ci-xxxx -m "你好"             # one-shot
arkclaw chat 答疑助手 -m "怎么部署"         # by name (names come from `arkclaw agents`)
echo "$DATA" | arkclaw chat ci-xxxx --json -m "总结" | jq -r .data.reply   # piped, machine
arkclaw chat ci-xxxx -f notes.md -m "review" -o out.md   # attach context, save reply

• Streaming on both transports; until the first token a spinner shows elapsed time + the running tool.
• Sessions are server-side — --session NAME keeps a named conversation that survives CLI restarts.
• Tool approvals: in a terminal you're prompted; headless it fails closed (deny) unless --approve-all; a ~/.arkclaw/cmdpolicy.json deny-list always wins.

---

Files

ls / pull / push operate on a claw's managed workspace files — its "brain": AGENTS.md, SOUL.md, MEMORY.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md. (This is not a general file store — arbitrary filenames are rejected.)

arkclaw ls                          # list them (defaults to your default claw)
arkclaw pull SOUL.md                # download SOUL.md here
arkclaw pull AGENTS.md ./agents.md  # download to a path
arkclaw push ./agents.md AGENTS.md  # write a managed file
arkclaw ls --clawid ci-other        # a different claw

---

For agents / automation

• --json → stdout is exactly one {ok, data, error} document; progress/streaming goes to stderr. Pipe to jq.
• Exit codes: 0 ok · 1 api · 2 validation · 3 auth · 4 network · 5 internal.
• Headless never blocks: --json / piped stdin refuse the interactive REPL; tool approvals fail closed.
• arkclaw schema --json describes every command + option for programmatic discovery.

---

Identity & security

• Identity-through, zero permanent secrets. Browser PKCE (S256, public client, loopback) → a short-lived id_token that is your user identity (same as the web app), auto-refreshed. The claw sees you, not a shared key.
• openclaw path exchanges that token (via a least-privilege STS role that can do exactly GetClawInstanceChatToken) for a one-time ChatToken, then connects over wss. a2a presents the token directly to the agent's gateway.
• Tokens live in the OS keychain (0600 file fallback). The config file holds only non-secret routing. Every upstream error is redacted (tokens / AK-SK) before display.

---

Configuration

login resolves config in this order: explicit flag → ARKCLAW_* env → the space's published discovery → arkclaw init defaults → derived from the address. You normally only type the address.

The easy way — arkclaw init asks once (interactively) for whatever the space doesn't yet auto-publish, and saves it. After that, just arkclaw login.

The env way (scripts/CI, or instead of init) — supply the same non-secret values via env:

Env	Purpose
ARKCLAW_CLIENT_ID	The CLI's public OAuth client id for the pool.
ARKCLAW_ROLE_TRN	STS role that mints the ChatToken (openclaw).
ARKCLAW_REGION / ARKCLAW_SPACE_ID	Override region / space (usually auto).

Other config: ~/.arkclaw/defaults.json (init answers, 0600), ~/.arkclaw/session.json (routing, 0600), ~/.arkclaw/cmdpolicy.json (tool-approval allow/deny), OS keychain (tokens).

Escape hatch (admin/test): arkclaw login <url> --transport openclaw --static-creds uses VOLCENGINE_ACCESS_KEY/SECRET_KEY from the env instead of SSO — convenient for CI, but it's account-level keys, not identity-through.

---

Notes

• ls/pull/push and a bare chat use your default claw (set at login, or the last one you opened in the browser); override with --clawid (or chat ci-...).
• File commands cover the claw's managed files only; arbitrary file drop isn't exposed by the API.
• Nothing is hardcoded per space — the CLI reads what the space serves.