CLI polish: v1 ping, YAML config get, table output, run --watch, config init (#3)

- ping: hit /v1/me (no health endpoint exists); distinguish unreachable from
  unauthenticated instead of a bare 404.
- config get: render as YAML by default; `-o/--output json` for JSON.
- config list / run list: aligned column tables. config list shows the GitHub
  source (path@branch) and last editor and flags sync errors; run list shows
  status, source, created, and cost.
- run: replace the non-functional `run view` (WS streaming is deferred
  server-side) with `run get --watch`, which polls run status to a terminal
  state. Spec for real token-level streaming added at docs/RUN_STREAMING_SPEC.md.
- config init [path]: scaffold a minimal valid agent config YAML (default
  agents/my_agent.yaml); verified it parses with the backend config parser.
- CI: add a `bun build --compile` smoke step so the release's single-binary
  build can't regress the way v0.1.0's first tag did.
- Bump to 0.1.1.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: hbrooks

.github/workflows/ci.yml

@@ -17,3 +17,8 @@ jobs:
       - run: bun run typecheck
       - run: bun run test
       - run: bun run build
+      # Compile-smoke: the release Bun-compiles a single binary, which bundles
+      # everything (unlike tsup) and can fail where `build` passes. Catch that
+      # here so a release tag never breaks on it.
+      - run: bun build src/cli.tsx --compile --outfile /tmp/agent
+      - run: /tmp/agent --version

README.md

@@ -25,19 +25,25 @@ agent run start --config <id>     # start a run from a saved config
 agent run start --config-file f.json   # ...or from an inline config
 agent run list --limit 20         # list recent runs (filter by --source, --days, …)
 agent run get <run-id>            # inspect one run
-agent run view                    # attach to the latest run and stream output
+agent run get <run-id> --watch    # follow a run until it finishes
 
 agent config list                 # list saved agent configs
-agent config get <config-id>      # inspect one config
+agent config get <config-id>      # show one config as YAML (-o json for JSON)
+agent config init [path]          # scaffold a starter config (default: agents/my_agent.yaml)
 
 agent budget                      # current budget summary
 agent usage                       # usage dashboard for the period
-agent ping                        # check API connectivity
+agent ping                        # check authenticated /v1 connectivity
 ```
 
 Most commands accept `--json` to print the raw API response. The CLI talks to
 the public `/v1` REST API; point it elsewhere with `ELLIPSIS_API_BASE`.
 
+`agent run get --watch` polls run status until the run finishes. Token-level
+output streaming over WebSocket is specified in
+[`docs/RUN_STREAMING_SPEC.md`](docs/RUN_STREAMING_SPEC.md) and will slot in
+behind the same `--watch` flag.
+
 ### Auth
 
 `agent login` uses the device-code flow: it requests a code pair, prints a

docs/RUN_STREAMING_SPEC.md

@@ -0,0 +1,102 @@
+# Requirements: live run streaming for `agent run get --watch`
+
+**Status:** proposed — not yet implemented.
+**Audience:** the engineer/agent implementing WebSocket streaming, server + client.
+
+## 1. Background
+
+The CLI can start runs and read their state over the public `/v1` REST API, but
+it cannot stream a run's output. `agent run get --watch` exists today and gives a
+**status-level** live view by polling `GET /v1/agents/runs/{id}` until the run
+reaches a terminal status (`completed`/`error`/`cancelled`/`stopped`). It shows
+status transitions and the final summary — not the step-by-step stdout/stderr or
+token stream.
+
+Token-level streaming over `/v1` is explicitly deferred in the backend design
+doc (`documents/eng/ELLIPSIS_API_AND_CLI.md` §7, "Deferred → Streaming run steps
+through `/v1` for CLI clients"). This spec defines the work to close that gap.
+
+Scaffolding already in this repo (currently unused, kept as a starting point):
+- `src/lib/ws.ts` — a `streamRun()` WebSocket client and a `StreamFrame` type
+  (`stdout`/`stderr`/`status`/`done`/`error`). It connects to
+  `${wsBase}/v1/runs/{id}/stream` with a bearer token. No reconnect/resume/heartbeat.
+- `src/ui/RunView.tsx` — an Ink component that renders frames from `streamRun()`.
+- `DEFAULT_WS_BASE` in `src/lib/constants.ts` (`wss://api.ellipsis.dev`).
+
+The reported `error: [object ErrorEvent]` came from this scaffolding connecting to
+a non-existent server endpoint; `ws.ts` stringifies the raw `ErrorEvent`. Fix the
+error rendering as part of this work (surface `err.message`).
+
+## 2. Goal
+
+`agent run get <id> --watch` streams a run's output live, in real time, and
+falls back to REST polling when streaming is unavailable. The same flag covers
+both modes — no new top-level command.
+
+## 3. Server-side requirements (`/v1`)
+
+1. **Endpoint:** `GET /v1/runs/{run_id}/stream`, upgraded to WebSocket.
+2. **Auth:** `Authorization: Bearer <token>`, resolved by the same `V1Auth`
+   path as the REST API (user/API/sandbox tokens), authorizing the run's
+   customer. Reject with a close code on auth failure (see §5).
+3. **Frame protocol (server → client), one JSON object per WS message:**
+   - `{ "type": "status", "status": "<AgentRunStatus>", "ts": "<iso8601>" }`
+   - `{ "type": "stdout", "data": "<chunk>", "seq": <int>, "ts": "<iso8601>" }`
+   - `{ "type": "stderr", "data": "<chunk>", "seq": <int>, "ts": "<iso8601>" }`
+   - `{ "type": "done", "status": "<terminal status>", "exit_status": "<...>" }`
+   - `{ "type": "error", "message": "<human-readable>" }`
+   - `seq` is a monotonic per-run cursor used for resume.
+4. **Backfill + resume:** accept `?after_seq=<int>` (query or first client
+   message). On connect, replay buffered frames with `seq > after_seq`, then
+   stream live. This makes reconnects lossless.
+5. **Heartbeat:** server sends WS ping (or a `status` keepalive) at a fixed
+   interval (e.g. 20s) so dead connections are detectable.
+6. **Termination:** send a final `done` frame, then close with a normal code.
+   For an already-terminal run, replay buffered output then `done` immediately.
+7. **Retention:** define how long run output is buffered for backfill (at least
+   the run's lifetime + a grace window). Document the limit.
+
+## 4. Client-side requirements (this repo)
+
+1. `agent run get <id> --watch` connects to the stream and renders frames:
+   `stdout`/`stderr` as output, `status` as transition lines, `done`/`error`
+   to finish. Exit 0 on `done` with a successful terminal status, non-zero on
+   `error` or a failed terminal status.
+2. **Reconnect with backoff** and resume from the last seen `seq` via
+   `after_seq`, so a dropped socket doesn't lose or duplicate output.
+3. **Fallback:** if the WebSocket can't connect (e.g. server without streaming,
+   or a `1003`/unsupported close), fall back to the existing REST polling
+   `watchRun()` automatically, with a one-line notice. `--watch` must keep
+   working against a backend that lacks the endpoint.
+4. **Heartbeat:** respond to/expect pings; treat a missed heartbeat as a dropped
+   connection and reconnect.
+5. `--json` with `--watch`: emit one JSON object per frame (NDJSON) for piping.
+6. Fix `ws.ts` error handling to surface a readable message, not
+   `[object ErrorEvent]`.
+
+## 5. WebSocket close codes (suggested)
+
+| Code | Meaning |
+|------|---------|
+| 1000 | normal — run reached a terminal state |
+| 1008 | auth failed / not authorized for this run |
+| 1003 | streaming unsupported (client should fall back to polling) |
+| 1011 | server error |
+
+## 6. Acceptance criteria
+
+- Streaming a live run shows stdout/stderr in near real time end to end.
+- Killing the socket mid-run and reconnecting resumes with no lost or duplicated
+  frames (verified via `seq`/`after_seq`).
+- `--watch` against a backend without the endpoint transparently falls back to
+  REST polling and still completes.
+- `--json --watch` emits valid NDJSON, one frame per line.
+- Unit tests for the client frame handler, reconnect/resume cursor, and fallback
+  trigger (mirror the fake-timer style in `test/auth.test.ts` / `test/run.test.ts`).
+- No `[object ErrorEvent]`; connection errors print a real message.
+
+## 7. Out of scope
+
+- Bidirectional control over the stream (stop/input). `run stop` is tracked
+  separately and also has no `/v1` endpoint yet.
+- Multiplexing multiple runs over one socket.

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@ellipsis/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Ellipsis agent CLI — drive the Ellipsis cloud from your terminal",
   "license": "MIT",
   "type": "module",
@@ -30,7 +30,8 @@
     "ink": "^5.0.1",
     "ink-spinner": "^5.0.0",
     "react": "^18.3.1",
-    "ws": "^8.18.0"
+    "ws": "^8.18.0",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/node": "^22.5.0",

package.json

@@ -1,6 +1,11 @@
-import type { Command } from 'commander'
+import { InvalidArgumentError, type Command } from 'commander'
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { basename, dirname, extname } from 'node:path'
 import { ApiClient } from '../lib/api'
-import { printJson, runAction } from '../lib/output'
+import { formatTs, printJson, printTable, printYaml, runAction } from '../lib/output'
+import type { SavedAgentConfig } from '../lib/types'
+
+const DEFAULT_CONFIG_PATH = 'agents/my_agent.yaml'
 
 export function registerConfig(program: Command): void {
   const config = program.command('config').description('Inspect saved agent configurations')
@@ -20,37 +25,102 @@ export function registerConfig(program: Command): void {
           console.log('No configs found.')
           return
         }
-        for (const c of configs) {
-          const flags = [c.deleted ? 'deleted' : null, c.last_sync_error ? 'sync-error' : null]
-            .filter(Boolean)
-            .join(',')
-          console.log(`${c.id}  ${c.updated_at}${flags ? `  [${flags}]` : ''}`)
-        }
+        printTable(
+          ['ID', 'SOURCE', 'UPDATED', 'EDITED BY'],
+          configs.map((c) => [
+            c.id,
+            configSource(c),
+            formatTs(c.updated_at),
+            editedBy(c),
+          ]),
+        )
       })
     })
 
   config
     .command('get <configId>')
     .description('Get a single agent configuration (GET /v1/agents/configs/{id})')
-    .option('--json', 'output raw JSON')
-    .action(async (configId: string, opts: { json?: boolean }) => {
+    .option('-o, --output <format>', 'output format: yaml (default) or json', parseFormat, 'yaml')
+    .action(async (configId: string, opts: { output: 'yaml' | 'json' }) => {
       await runAction(async () => {
         const c = await new ApiClient().getAgentConfig(configId)
-        if (opts.json) {
+        if (opts.output === 'json') {
           printJson(c)
-          return
+        } else {
+          printYaml(c)
         }
-        console.log(`id:        ${c.id}`)
-        console.log(`created:   ${c.created_at}`)
-        console.log(`updated:   ${c.updated_at}`)
-        if (c.last_synced_commit_sha) console.log(`synced:    ${c.last_synced_commit_sha}`)
-        if (c.last_sync_error) console.log(`sync error: ${c.last_sync_error}`)
-        console.log('config:')
-        printJson(c.agent_config)
       })
     })
 
-  // Note: agent configs are sourced from YAML in GitHub, not created/deployed
-  // through the API (see documents/eng/ELLIPSIS_API_AND_CLI.md). There is no
-  // /v1 create/deploy endpoint; edit the config file in your repo instead.
+  config
+    .command('init [path]')
+    .description(`Scaffold a starter agent config YAML (default: ${DEFAULT_CONFIG_PATH})`)
+    .option('-f, --force', 'overwrite the file if it already exists')
+    .action((path: string | undefined, opts: { force?: boolean }) => {
+      // Configs are sourced from YAML in GitHub, not created through the API
+      // (see documents/eng/ELLIPSIS_API_AND_CLI.md), so `init` is a local
+      // scaffold the user commits to a path Ellipsis syncs from.
+      const target = path ?? DEFAULT_CONFIG_PATH
+      if (existsSync(target) && !opts.force) {
+        console.error(`error: ${target} already exists (use --force to overwrite)`)
+        process.exitCode = 1
+        return
+      }
+      const name = basename(target, extname(target))
+      mkdirSync(dirname(target), { recursive: true })
+      writeFileSync(target, starterConfig(name))
+      console.log(`✓ wrote ${target}`)
+      console.log(
+        'Commit it to your default branch — Ellipsis syncs agent configs from GitHub.',
+      )
+    })
+}
+
+// A minimal valid agent config. `claude.system` is the only required field;
+// everything else has a server-side default. Roots Ellipsis syncs from:
+// agents/, .agents/, ellipsis/, .ellipsis/ (any depth), as .yaml/.yml.
+function starterConfig(name: string): string {
+  return `# Ellipsis agent config — commit this to your default branch; Ellipsis syncs it
+# from GitHub. Valid locations: agents/, .agents/, ellipsis/, .ellipsis/ (any depth).
+ellipsis:
+  version: v1
+  name: ${name}
+  description: What this agent does.
+
+claude:
+  # System prompt defining the agent's behavior (required).
+  system: |
+    You are an Ellipsis agent. Describe the task you want it to perform here.
+  # model: claude-opus-4-8   # optional; defaults to the account default
+
+# Optional — uncomment and fill in as needed:
+# triggers:
+#   - type: cron
+#     schedule: "0 9 * * 1-5"   # weekdays at 09:00
+# tools: []
+# repositories: []
+`
+}
+
+// GitHub source as `path@branch` (repo is only an opaque numeric id in the API).
+// Prefixed with ⚠ when the last sync failed so it stands out in the list.
+function configSource(c: SavedAgentConfig): string {
+  const s = c.agent_config_source_details as
+    | { repo_id: number; path: string; branch: string }
+    | null
+    | undefined
+  const base = s ? `${s.path}@${s.branch}` : '—'
+  return c.last_sync_error ? `⚠ ${base}` : base
+}
+
+function editedBy(c: SavedAgentConfig): string {
+  const by = c.edited_by as { login?: string } | null | undefined
+  return by?.login ?? '—'
+}
+
+function parseFormat(value: string): 'yaml' | 'json' {
+  if (value !== 'yaml' && value !== 'json') {
+    throw new InvalidArgumentError("output format must be 'yaml' or 'json'")
+  }
+  return value
 }

src/commands/config.ts

@@ -1,17 +1,28 @@
 import type { Command } from 'commander'
-import { ApiClient } from '../lib/api'
+import { ApiClient, ApiError } from '../lib/api'
 
 export function registerPing(program: Command): void {
   program
     .command('ping')
-    .description('Check connectivity to the Ellipsis API')
+    .description('Check authenticated connectivity to the Ellipsis /v1 API')
     .action(async () => {
+      // There's no unauthenticated health route on the public API, so we probe
+      // the lightest authenticated endpoint (/v1/me): a 200 proves the API is
+      // reachable AND the stored token is valid.
       const api = new ApiClient()
       try {
-        await api.request('GET', '/health')
-        console.log('ok')
+        const me = await api.whoami()
+        console.log(`ok — ${me.customer_login} (${me.customer_id})`)
       } catch (err) {
-        console.error(`ping failed: ${(err as Error).message}`)
+        if (err instanceof ApiError && err.status === 401) {
+          // Reachable, just not authenticated — point the user at login.
+          console.error('reachable, but not authenticated. Run `agent login` first.')
+        } else if (err instanceof ApiError) {
+          console.error(`ping failed: ${err.status} ${err.message}`)
+        } else {
+          // Network/DNS/connection error: never got an HTTP response.
+          console.error(`cannot reach the API: ${(err as Error).message}`)
+        }
         process.exitCode = 1
       }
     })