Metadata-Version: 2.4
Name: arkclaw-webchat-cli
Version: 0.6.0
Summary: CLI to chat with an ArkClaw EE space's Claw over enterprise SSO — zero permanent AK/SK.
Author: ArkClaw Team
Keywords: arkclaw,cli,ee,openclaw,sso,sts
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: keyring>=24.0
Requires-Dist: typer>=0.12.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# 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).

```bash
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

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

From source:

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

---

## Quick start

```bash
# 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](#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

```bash
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.)

```bash
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.
