skydive-cli 0.1.0-beta.106

package/README.md

@@ -0,0 +1,259 @@
+# 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 a single `config.json`. The
+location is platform-conventional (resolved via `env-paths`), so it is **not**
+`~/.config/skydive/` everywhere:
+
+| Platform | Path                                                             |
+| -------- | ---------------------------------------------------------------- |
+| macOS    | `~/Library/Preferences/skydive/config.json`                      |
+| Linux    | `~/.config/skydive/config.json` (or `$XDG_CONFIG_HOME/skydive/`) |
+| Windows  | `%APPDATA%\skydive\config.json`                                  |
+
+`skydive auth status` prints the real resolved path (`Config: …`) — trust that
+over this table if they ever disagree.
+
+- **API key** (`sky_live_…`). 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
+  ```
+
+Either credential authenticates the management commands (`agents`, `keys`,
+`secrets`): the CLI prefers the API key and falls back to the `--web` chat
+session, so a `--web` login alone is enough to run them — you do **not** need a
+separate API key. The API key is only required when you have no chat session
+(e.g. CI). `skydive chat` requires the chat session specifically.
+
+`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
+printf '%s' "$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.
+- Use `printf '%s'` rather than `echo -n` when piping a value: `echo -n` is not
+  portable (some `sh` builtins emit `-n` literally instead of suppressing the
+  newline), which would silently store a corrupted value. Since values are
+  write-only and cannot be read back to verify, that failure stays invisible
+  until something downstream breaks.
+- **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.
+- **Recovering a dropped run.** A long run's stream can be cut off at the edge
+  (a gateway 502/504) after the run was created. The run keeps going
+  server-side, so a blind retry would re-execute the agent. Instead, note the
+  `runId` (always in `--json` output) and fetch the result once it's done:
+
+  ```sh
+  skydive runs get <runId>            # prints the reply; --json for the envelope
+  ```
+
+  `runs get` re-attaches to the run and replays its full reply whether it's
+  still streaming or already finished.
+
+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                       |
+| Agent picker        | `ctrl+w`      | switch workspace                      |
+| Agent picker        | `tab`         | toggle mine / whole-org agents        |
+| Conversation picker | `ctrl+d`      | delete the highlighted conversation   |
+| 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       |
+| Chat                | `ctrl+p`      | switch model                          |
+| Chat                | `ctrl+o`      | switch theme                          |
+| Chat                | `ctrl+t`      | grant / revoke local machine access   |
+| Chat                | `ctrl+l`      | open this conversation in the browser |
+| Chat                | `ctrl+r`      | run the newest pending connect card   |
+| Chat                | `ctrl+v`      | paste an image from the clipboard     |
+| Chat                | `ctrl+x`      | drop the most recently staged image   |
+| Chat                | `?`           | show the keybinding reference         |
+
+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.
+
+### Local machine access (`--share-machine` / `ctrl+t`)
+
+The chat TUI can grant the agent the ability to run commands **on your local
+machine** so it can read the repo you launched from, run local tooling, etc.
+This is off by default (default-deny) and you opt in explicitly:
+
+- `skydive chat --share-machine` enables it at launch, or
+- `ctrl+t` toggles it from the chat screen (the status bar shows `local access`
+  when on, `revoke access` when off).
+
+What to know before enabling it:
+
+- **Per-agent.** The grant is scoped to the agent you're chatting with; other
+  agents don't inherit it.
+- **The working directory is a starting point, not a jail.** Commands run with
+  their working directory set to wherever you launched `skydive chat`, but this
+  is **not** a hard filesystem boundary. This is genuine remote command
+  execution (a WebSocket streaming stdin/stdout/stderr), so the agent runs
+  commands as your user and can reach anything your user can, including paths
+  outside the launch directory. Launch from a scoped directory, but treat the
+  grant as "this agent can act as me on this machine," not "this agent can only
+  see this folder."
+- **Teardown is automatic.** Access is revoked when the TUI unmounts, so
+  quitting the chat drops the grant and reaps any processes the agent spawned.
+- **Interactive only.** Machine sharing is **not** available in `-p`
+  (non-interactive) mode \u2014 `--share-machine` has no effect there and the
+  print path carries no portal code. You can have scripted (`-p`) or local
+  access, not both, in a single invocation.
+
+## 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) |
+| `SKYDIVE_THEME`         | Chat colorscheme id (flag `--theme` overrides)   |
+| `SKYDIVE_CONFIG_NAME`   | On-disk config profile name (default `skydive`)  |
+
+## 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`.