docs: add --output json flag documentation for CLI commands (#161)

rgarcia · web-flow · commit 44aaddeaf3d8 · 2026-01-09T09:53:09.000-05:00
* docs: add --output json flag documentation for CLI commands Document JSON output support for CLI commands: - Add JSON Output section to main CLI reference page - Document --output json flag for deploy, invoke, app commands - Document --output json flag for browsers, browser-pools, profiles - Document --output json flag for extensions, proxies - Add browser-pools and profiles CLI sections Related to kernel/cli#67 * fix: address review feedback - Add cross-links to /browsers/pools and /browsers/profiles pages - Fix flag documentation: use `-o json` instead of just `-o` for consistency
diff --git a/reference/cli.mdx b/reference/cli.mdx
@@ -64,6 +64,23 @@ kernel invoke my-app action-name --payload '{"key":"value"}'
 - `--no-color` - Disable color output
 - `--log-level <level>` - Set the log level (trace, debug, info, warn, error, fatal, print)
 
+## JSON Output
+
+Many commands support `--output json` (or `-o json`) for machine-readable output, useful for scripting and automation:
+
+```bash
+# Get browser session as JSON
+kernel browsers create -o json
+
+# List apps as JSON array
+kernel app list -o json
+
+# Deploy with JSONL streaming (one JSON object per line)
+kernel deploy index.ts -o json
+```
+
+See individual command documentation for JSON output availability.
+
 <Info>
 Looking for the API? See the [API Reference](/api-reference/invocations/invoke-an-action).
 </Info>
diff --git a/reference/cli/apps.mdx b/reference/cli/apps.mdx
@@ -11,6 +11,7 @@ Deploy an app to Kernel from the current directory. The entrypoint file and depe
 | `--force` | Overwrite an existing version with the same label. |
 | `--env <KEY=VALUE>`, `-e` | Set environment variables (repeatable). |
 | `--env-file <file>` | Load environment variables from a file (repeatable). |
+| `--output json`, `-o json` | Output JSONL (one JSON object per line for each deployment event). |
 
 <Info>`package.json` (JS/TS) or `pyproject.toml` (Python) must be present next to the entrypoint.</Info>
 
@@ -23,23 +24,25 @@ Stream build and runtime logs for a deployment.
 | `--since <duration>`, `-s` | Fetch logs starting from a relative duration (e.g. `5m`, `1h`, `1h30m`) or timestamp (`2006-01-02T15:04`). |
 | `--with-timestamps`, `-t` | Prefix each line with an RFC3339 timestamp. |
 
-<Info>Log lines longer than 64 KiB are truncated. Emit bulky payloads to external storage and log references.</Info>
+<Info>Log lines longer than 64 KiB are truncated. Emit bulky payloads to external storage and log references.</Info>
 
 ## `kernel deploy history [app_name]`
 Show deployment history for all apps or a specific app.
 
 | Flag | Description |
 |------|-------------|
 | `--limit <n>` | Maximum number of deployments to return (default: 100, `0` = all). |
+| `--output json`, `-o json` | Output raw JSON array. |
 
 ## `kernel invoke <app> <action>`
 Invoke an app action. By default the CLI returns immediately after the invocation is queued.
 
 | Flag | Description |
 |------|-------------|
 | `--version <version>`, `-v` | Target a specific app version (default: latest). |
-| `--payload <json>`, `-p` | Provide a JSON payload (stringified, max 64 KB). |
-| `--sync`, `-s` | Wait for completion (timeout after 60 s). |
+| `--payload <json>`, `-p` | Provide a JSON payload (stringified, max 64 KB). |
+| `--sync`, `-s` | Wait for completion (timeout after 60 s). |
+| `--output json`, `-o json` | Output JSONL (one JSON object per line for each invocation event). |
 
 <Info>Press `Ctrl+C` to cancel an in-flight invocation. The associated browser sessions are cleaned up automatically.</Info>
 
@@ -50,13 +53,15 @@ List deployed app versions.
 |------|-------------|
 | `--name <app_name>` | Filter by app name. |
 | `--version <version>` | Filter by version label. |
+| `--output json`, `-o json` | Output raw JSON array. |
 
 ## `kernel app history <app_name>`
 Show deployment history for a specific app.
 
 | Flag | Description |
 |------|-------------|
 | `--limit <n>` | Maximum number of deployments to return (default: 100, `0` = all). |
+| `--output json`, `-o json` | Output raw JSON array. |
 
 ## `kernel logs <app_name>`
 Tail app logs.
@@ -68,4 +73,4 @@ Tail app logs.
 | `--since <duration>`, `-s` | Fetch logs from a duration or timestamp (same formats as `kernel deploy logs`). |
 | `--with-timestamps` | Include timestamps in each line. |
 
-<Info>Log lines longer than 64 KiB are truncated.</Info>
+<Info>Log lines longer than 64 KiB are truncated.</Info>
diff --git a/reference/cli/browsers.mdx b/reference/cli/browsers.mdx
@@ -9,6 +9,10 @@ title: "Browsers"
 ### `kernel browsers list`
 List all browser sessions.
 
+| Flag | Description |
+|------|-------------|
+| `--output json`, `-o json` | Output raw JSON array. |
+
 ### `kernel browsers create`
 Create a new browser session.
 
@@ -17,6 +21,7 @@ Create a new browser session.
 | `--stealth` | Enable stealth mode to reduce automation fingerprints. |
 | `--headless` | Launch without GUI/VNC access. |
 | `--kiosk` | Launch in Chrome kiosk mode. |
+| `--output json`, `-o json` | Output raw JSON object. |
 
 ### `kernel browsers delete <session-id>`
 Delete a browser session. Use `-y` to skip confirmation.
@@ -28,6 +33,17 @@ Delete a browser session. Use `-y` to skip confirmation.
 ### `kernel browsers view <session-id>`
 Return a live view URL for remote monitoring and control.
 
+| Flag | Description |
+|------|-------------|
+| `--output json`, `-o json` | Output JSON with `liveViewUrl` field. |
+
+### `kernel browsers get <session-id>`
+Get detailed information about a browser session.
+
+| Flag | Description |
+|------|-------------|
+| `--output json`, `-o json` | Output raw JSON object. |
+
 ## Browser logs
 
 ### `kernel browsers logs stream <session-id>`
@@ -47,13 +63,18 @@ Stream browser logs from the supervisor or a file path.
 ### `kernel browsers replays list <session-id>`
 List replay recordings for a browser session.
 
+| Flag | Description |
+|------|-------------|
+| `--output json`, `-o json` | Output raw JSON array. |
+
 ### `kernel browsers replays start <session-id>`
 Start recording a replay.
 
 | Flag | Description |
 |------|-------------|
 | `--framerate <fps>` | Recording framerate in frames per second. |
 | `--max-duration <seconds>` | Maximum recording duration. |
+| `--output json`, `-o json` | Output raw JSON object. |
 
 ### `kernel browsers replays stop <session-id> <replay-id>`
 Stop an active replay recording.
@@ -78,6 +99,7 @@ Execute a command synchronously inside the browser VM.
 | `--timeout <seconds>` | Execution timeout. |
 | `--as-user <user>` | Run as a specific user. |
 | `--as-root` | Run as root. |
+| `--output json`, `-o json` | Output raw JSON object. |
 
 ### `kernel browsers process spawn <session-id> [--] [command...]`
 Execute a command asynchronously in the browser VM.
@@ -90,6 +112,7 @@ Execute a command asynchronously in the browser VM.
 | `--timeout <seconds>` | Execution timeout. |
 | `--as-user <user>` | Run as a specific user. |
 | `--as-root` | Run as root. |
+| `--output json`, `-o json` | Output raw JSON object. |
 
 ### `kernel browsers process kill <session-id> <process-id>`
 Send a signal to a process running in the browser VM.
@@ -149,13 +172,15 @@ Retrieve metadata for a file or directory.
 | Flag | Description |
 |------|-------------|
 | `--path <path>` | Absolute file or directory path (required). |
+| `--output json`, `-o json` | Output raw JSON object. |
 
 ### `kernel browsers fs list-files <session-id>`
 List directory contents.
 
 | Flag | Description |
 |------|-------------|
 | `--path <path>` | Absolute directory path (required). |
+| `--output json`, `-o json` | Output raw JSON array. |
 
 ### `kernel browsers fs move <session-id>`
 Move or rename a file or directory.
@@ -295,12 +320,17 @@ Execute Playwright/TypeScript code against a running browser session.
 ### `kernel extensions list`
 List all uploaded extensions.
 
+| Flag | Description |
+|------|-------------|
+| `--output json`, `-o json` | Output raw JSON array. |
+
 ### `kernel extensions upload <directory>`
 Upload an unpacked extension directory.
 
 | Flag | Description |
 |------|-------------|
 | `--name <name>` | Optional unique extension name. |
+| `--output json`, `-o json` | Output raw JSON object. |
 
 ### `kernel extensions download <id-or-name>`
 Download an extension archive.
@@ -332,9 +362,17 @@ Upload one or more unpacked Chrome extensions directly into a running browser se
 ### `kernel proxies list`
 List available proxy configurations.
 
+| Flag | Description |
+|------|-------------|
+| `--output json`, `-o json` | Output raw JSON array. |
+
 ### `kernel proxies get <id>`
 Show details for a proxy configuration.
 
+| Flag | Description |
+|------|-------------|
+| `--output json`, `-o json` | Output raw JSON object. |
+
 ### `kernel proxies create`
 Create a new proxy configuration.
 
@@ -354,10 +392,101 @@ Create a new proxy configuration.
 | `--port <port>` | Proxy port (custom; required). |
 | `--username <username>` | Proxy username (custom). |
 | `--password <password>` | Proxy password (custom). |
+| `--output json`, `-o json` | Output raw JSON object. |
 
 ### `kernel proxies delete <id>`
 Delete a proxy configuration.
 
 | Flag | Description |
 |------|-------------|
 | `--yes`, `-y` | Skip confirmation. |
+
+## Browser pools
+
+For more details on browser pools, see [Browser Pools](/browsers/pools).
+
+### `kernel browser-pools list`
+List all browser pools.
+
+| Flag | Description |
+|------|-------------|
+| `--output json`, `-o json` | Output raw JSON array. |
+
+### `kernel browser-pools create`
+Create a new browser pool.
+
+| Flag | Description |
+|------|-------------|
+| `--name <name>` | Optional unique name for the pool. |
+| `--size <n>` | Number of browsers in the pool (required). |
+| `--fill-rate <n>` | Percentage of the pool to fill per minute. |
+| `--timeout <seconds>` | Idle timeout for browsers acquired from the pool. |
+| `--output json`, `-o json` | Output raw JSON object. |
+
+### `kernel browser-pools get <id-or-name>`
+Get pool details.
+
+| Flag | Description |
+|------|-------------|
+| `--output json`, `-o json` | Output raw JSON object. |
+
+### `kernel browser-pools update <id-or-name>`
+Update pool configuration.
+
+| Flag | Description |
+|------|-------------|
+| `--size <n>` | Updated pool size. |
+| `--discard-all-idle` | Discard all idle browsers and refill. |
+| `--output json`, `-o json` | Output raw JSON object. |
+
+### `kernel browser-pools acquire <id-or-name>`
+Acquire a browser from the pool.
+
+| Flag | Description |
+|------|-------------|
+| `--timeout <seconds>` | Acquire timeout before returning 204. |
+| `--output json`, `-o json` | Output raw JSON object. |
+
+### `kernel browser-pools release <id-or-name>`
+Release a browser back to the pool.
+
+| Flag | Description |
+|------|-------------|
+| `--session-id <id>` | Browser session ID to release (required). |
+| `--reuse` | Reuse the browser instance (default: true). |
+
+### `kernel browser-pools delete <id-or-name>`
+Delete a pool.
+
+| Flag | Description |
+|------|-------------|
+| `--force` | Force delete even if browsers are leased. |
+
+### `kernel browser-pools flush <id-or-name>`
+Destroy all idle browsers in the pool.
+
+## Profiles
+
+For more details on browser profiles, see [Profiles](/browsers/profiles).
+
+### `kernel profiles list`
+List all browser profiles.
+
+| Flag | Description |
+|------|-------------|
+| `--output json`, `-o json` | Output raw JSON array. |
+
+### `kernel profiles get <id-or-name>`
+Get profile details.
+
+| Flag | Description |
+|------|-------------|
+| `--output json`, `-o json` | Output raw JSON object. |
+
+### `kernel profiles create`
+Create a new browser profile.
+
+| Flag | Description |
+|------|-------------|
+| `--name <name>` | Optional unique name for the profile. |
+| `--output json`, `-o json` | Output raw JSON object. |
