From 7edd6c3a1dfef0c16de7fe9d429674ec1883599f Mon Sep 17 00:00:00 2001
From: Dax Raad <d@ironbay.co>
Date: Sat, 27 Jun 2026 13:18:22 -0400
Subject: [PATCH] feat(cli): use installation version and document API
 debugging

- Replace hardcoded "local" version string with InstallationVersion
- Document DESCRIPTION
  Make a request to the running server

USAGE
  opencode api [flags] <operation | method path...>

ARGUMENTS
  operation | method path... stringOpenAPI operation ID, or an HTTP method followed by a path

FLAGS
  --data, -d string      Request body
  --header, -H string    Request header in name:value form
  --param key=value      OpenAPI path or query parameter

GLOBAL FLAGS
  --help, -h                                                          Show help information
  --version, -v                                                       Show version information
  --completions <bash|zsh|fish|sh>                                    Print shell completion script (choices: bash, zsh, fish, sh)
  --log-level <all|trace|debug|info|warn|warning|error|fatal|none>    Sets the minimum log level (choices: all, trace, debug, info, warn, warning, error, fatal, none) server/API debugging command in AGENTS.md
---
 packages/cli/AGENTS.md    | 16 ++++++++++++++++
 packages/cli/src/index.ts |  3 ++-
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/packages/cli/AGENTS.md b/packages/cli/AGENTS.md
index f546d1dc48..c7215121e5 100644
--- a/packages/cli/AGENTS.md
+++ b/packages/cli/AGENTS.md
@@ -63,6 +63,22 @@ termctrl show opencode-v2-dev
 termctrl stop opencode-v2-dev
 ```
 
+## Server/API debugging
+
+- Use `bun dev api --help` from `packages/cli` to inspect the API debugging command. It sends one request to the V2 server using the same daemon discovery/auth path as the CLI.
+- Use `bun dev api` to introspect the server-side data backing the TUI. This is useful when debugging UI bugs: compare what the screen renders with the raw session, message, event, agent, or health data returned by the API to determine whether the bug is in the server state, the client data layer, or the TUI rendering.
+- `bun dev api` accepts either an OpenAPI operation ID or a raw HTTP method plus path:
+
+```bash
+bun dev api get /health
+bun dev api get /openapi.json
+bun dev api <operationId> --param key=value
+```
+
+- Pass JSON request bodies with `--data`/`-d`; the command sets `content-type: application/json` automatically unless you provide a header. Add extra headers with `--header`/`-H name:value`.
+- If no compatible background server is registered, `bun dev api` starts one through the daemon service. Use `bun dev service status`, `bun dev service restart`, and `bun dev service stop` when you need explicit lifecycle control.
+- Prefer raw method/path calls for quick server debugging and operation IDs when exercising documented OpenAPI routes with path or query parameters.
+
 ## Debugger
 
 - To debug the V2 CLI or TUI with Bun's inspector, launch the CLI entrypoint through Terminal Control with an inspector URL, then attach a debugger to that URL:
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 53c660b2b4..a2ab28bfc9 100755
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -10,6 +10,7 @@ import { Runtime } from "./framework/runtime"
 import { Daemon } from "./services/daemon"
 import { Logging } from "@opencode-ai/core/observability/logging"
 import { Updater } from "./services/updater"
+import { InstallationVersion } from "@opencode-ai/core/installation/version"
 
 const LoggingLayer = Logger.layer(Logging.loggers(), { mergeWithExisting: false }).pipe(
   Layer.provide(NodeFileSystem.layer),
@@ -34,7 +35,7 @@ const Handlers = Runtime.handlers(Commands, {
   serve: () => import("./commands/handlers/serve"),
 })
 
-Runtime.run(Commands, Handlers, { version: "local" }).pipe(
+Runtime.run(Commands, Handlers, { version: InstallationVersion }).pipe(
   Effect.annotateLogs({ role: "cli" }),
   Effect.provide(Daemon.defaultLayer),
   Effect.provide(Updater.defaultLayer),