skydive-cli 0.1.0-beta.45

package/README.md

@@ -0,0 +1,185 @@
+# skydive-cli
+
+The Skydive CLI — manage agents and chat with them from the terminal.
+
+```sh
+npx skydive-cli --help
+```
+
+## Authentication
+
+The CLI has two credentials, stored together in `~/.config/skydive/config.json`:
+
+- **API key** (`sky_live_…`) for the management commands. Mint one at
+  `skydive.com/account`, then:
+
+  ```sh
+  skydive auth login            # paste the key
+  ```
+
+- **User session** for `skydive chat`. Chat is user-level and multi-agent,
+  so it signs you in via the browser (device flow) rather than a per-agent
+  API key. `skydive chat` does this automatically on first run; you can also
+  do it up front:
+
+  ```sh
+  skydive auth login --web      # opens the browser, prompts for approval
+  ```
+
+`skydive auth status` shows both; `skydive auth logout` clears them.
+
+## Commands
+
+```sh
+skydive agents list
+skydive agents get <id>
+skydive agents create --name "My Agent"
+
+skydive keys list --agent-id <id>
+skydive keys create <name> --agent-id <id>
+skydive keys revoke <id> --agent-id <id>
+
+skydive secrets list --agent-id <id>
+skydive secrets set <KEY> --agent-id <id>       # value from stdin
+skydive secrets rm <KEY> --agent-id <id>
+
+skydive chat                    # interactive chat TUI (Node; fetches Bun on first run)
+skydive chat -p "<prompt>"       # one-shot, non-interactive (runs under Node)
+```
+
+Global flags: `--json`, `--quiet`, `--api-url <url>`.
+
+## `skydive secrets`
+
+Manage the environment secrets injected into an agent's sandbox. All
+subcommands are scoped to an agent with `--agent-id <id>` and require an
+API key with edit access to that agent.
+
+```sh
+skydive secrets list --agent-id <id>              # names only — values are never returned
+skydive secrets set OPENAI_API_KEY --agent-id <id>   # reads the value from stdin
+echo -n "$TOKEN" | skydive secrets set MY_TOKEN --agent-id <id>
+skydive secrets set MY_TOKEN "literal-value" --agent-id <id>
+skydive secrets rm MY_TOKEN --agent-id <id>
+```
+
+- Keys must be env-var identifiers (uppercase letters, digits, underscores).
+- `set` reads the value from **stdin** when no value argument is given, so the
+  secret stays out of shell history. Passing it inline is supported for
+  scripting but avoid it in an interactive shell.
+- **Values are write-only over the API.** `list` returns key names, never
+  values — the same contract as the in-sandbox `platform secrets` surface.
+- Setting a secret updates the agent's vault. If an outbound-proxy rule
+  references that key, the proxy picks up the new value on the next request.
+  Setting a secret does **not** by itself create a proxy rule — see below.
+
+## `skydive chat`
+
+An interactive terminal chat client (an OpenTUI app) that drives the same
+agents, sandboxes, and streaming responses as the web app — over the
+internal API. On launch it walks you through:
+
+1. **Agent picker** — type to filter your agents by name; `↑/↓` to move,
+   `↵` to open, or `ctrl+n` to create one.
+2. **Conversation picker** — resume an existing thread or start a new one
+   (also filterable).
+3. **Chat** — send a message and watch the reply stream, with markdown
+   formatting, collapsed reasoning, and rich rendering of tool calls
+   (`bash`, `edit`/`write` diffs, `read`, `grep`/`glob`).
+
+Runs under **Node** like every other command. The TUI renders through
+OpenTUI, whose native core needs the [Bun](https://bun.sh) runtime, so the
+first `chat` run downloads a private, pinned Bun and re-execs under it
+automatically — no separate Bun install required:
+
+```sh
+npx skydive-cli chat
+```
+
+The Bun binary is cached under the CLI config dir and reused after the first
+run. Already have Bun and want to skip the download? Point `SKYDIVE_BUN_PATH`
+at your `bun` binary, or just invoke the command under `bun`.
+
+### Non-interactive: `chat -p`
+
+For scripts, pipes, and CI, `-p`/`--print` sends a single prompt, streams the
+reply to stdout, and exits — the `claude -p` convention. It has no TUI, so it
+runs under plain **Node** (no Bun needed):
+
+```sh
+skydive chat -p "summarize my open PRs" --agent grace
+echo "what changed today?" | skydive chat -p --agent grace   # prompt from stdin
+skydive chat -p "and the one before?" --agent grace --conversation <id>
+skydive chat -p "status?" --agent grace --json               # structured envelope
+```
+
+- `--agent <id|slug|name>` targets the agent. Optional when the account has
+  exactly one agent; required (with the candidate list printed) otherwise.
+- `--conversation <id>` continues an existing thread; omitted, it starts a new
+  one. The conversation id is included in `--json` output for chaining.
+- `-p` needs a user session just like `chat`, but never opens the interactive
+  browser login — sign in first with `skydive auth login --web` or set
+  `SKYDIVE_SESSION_TOKEN`.
+- `--json` prints `{ agentId, agentName, conversationId, isNewConversation,
+runId, text }` instead of streaming the raw text.
+
+It defaults to the production API (`https://api.skydive.com`). For local
+dev, point it at your stack:
+
+```sh
+npx skydive-cli chat --api-url http://localhost:4500
+```
+
+`--api-url` in chat overrides the **app/session** origin (where better-auth
+and the internal tRPC API live), which is distinct from the public
+management API used by `agents`/`keys`.
+
+### Keybindings
+
+| Context      | Key           | Action                               |
+| ------------ | ------------- | ------------------------------------ |
+| Pickers      | _type_        | filter the list                      |
+| Pickers      | `↑` / `↓`     | move selection                       |
+| Pickers      | `↵`           | open / select                        |
+| Pickers      | `esc`         | back                                 |
+| Agent picker | `ctrl+n`      | create an agent                      |
+| Chat         | `↵`           | send (or queue, while streaming)     |
+| Chat         | `pgup`/`pgdn` | scroll the transcript                |
+| Chat         | `ctrl+c`      | cancel the active run; again to quit |
+| Chat         | `esc`         | back to the conversation picker      |
+
+Messages typed while a response is streaming are **queued** and sent in
+order as each run finishes; `ctrl+c` cancels the current run and clears the
+queue.
+
+## Environment variables
+
+| Variable                | Effect                                           |
+| ----------------------- | ------------------------------------------------ |
+| `SKYDIVE_API_KEY`       | Management API key (overrides stored key)        |
+| `SKYDIVE_API_URL`       | Management API base URL                          |
+| `SKYDIVE_SESSION_TOKEN` | Chat session token (for non-interactive use)     |
+| `SKYDIVE_APP_URL`       | Chat app/session origin (overrides stored value) |
+
+## Testing the TUI
+
+`yarn test:unit` runs both suites: unit tests (`*.test.ts`) under vitest,
+then TUI tests (`*.tui.test.tsx`) under `bun test` (needs [Bun](https://bun.sh)
+≥ 1.3.14 on your PATH — see `engines`).
+
+TUI tests render the real OpenTUI screens headlessly — fixed terminal size,
+mock keyboard input, frames captured as plain text — via
+`@opentui/react/test-utils`. OpenTUI needs Bun's FFI, which is why they run
+under `bun test`, not vitest:
+
+```sh
+bun test .tui.test        # just the TUI suite
+```
+
+Frame snapshots live in `__snapshots__/` next to each test; a diff there is
+a visual diff of the screen. `yarn render:frames <dir>` writes true-color
+ANSI captures of key screens — CI converts them to PNGs (textimg) and posts
+them as a sticky screenshot comment on CLI PRs.
+
+The pattern (stub `fetch`, seed the store, drive keys, assert on
+`captureCharFrame()`) is in `src/chat/tui/screens/agent-picker.tui.test.tsx`.