From b1da0f0ad0cde6dc0619f7298d8158bc37cd1f38 Mon Sep 17 00:00:00 2001 From: Rafael Garcia Date: Thu, 8 Jan 2026 18:37:45 -0500 Subject: [PATCH 1/2] 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 --- reference/cli.mdx | 17 +++++ reference/cli/apps.mdx | 13 ++-- reference/cli/browsers.mdx | 125 +++++++++++++++++++++++++++++++++++++ 3 files changed, 151 insertions(+), 4 deletions(-) diff --git a/reference/cli.mdx b/reference/cli.mdx index 364d175b..be56d5b7 100644 --- 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 ` - 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. + Looking for the API? See the [API Reference](/api-reference/invocations/invoke-an-action). diff --git a/reference/cli/apps.mdx b/reference/cli/apps.mdx index be823c24..cd01b973 100644 --- 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 `, `-e` | Set environment variables (repeatable). | | `--env-file ` | Load environment variables from a file (repeatable). | +| `--output json`, `-o` | Output JSONL (one JSON object per line for each deployment event). | `package.json` (JS/TS) or `pyproject.toml` (Python) must be present next to the entrypoint. @@ -23,7 +24,7 @@ Stream build and runtime logs for a deployment. | `--since `, `-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. | -Log lines longer than 64 KiB are truncated. Emit bulky payloads to external storage and log references. +Log lines longer than 64 KiB are truncated. Emit bulky payloads to external storage and log references. ## `kernel deploy history [app_name]` Show deployment history for all apps or a specific app. @@ -31,6 +32,7 @@ Show deployment history for all apps or a specific app. | Flag | Description | |------|-------------| | `--limit ` | Maximum number of deployments to return (default: 100, `0` = all). | +| `--output json`, `-o` | Output raw JSON array. | ## `kernel invoke ` Invoke an app action. By default the CLI returns immediately after the invocation is queued. @@ -38,8 +40,9 @@ Invoke an app action. By default the CLI returns immediately after the invocatio | Flag | Description | |------|-------------| | `--version `, `-v` | Target a specific app version (default: latest). | -| `--payload `, `-p` | Provide a JSON payload (stringified, max 64 KB). | -| `--sync`, `-s` | Wait for completion (timeout after 60 s). | +| `--payload `, `-p` | Provide a JSON payload (stringified, max 64 KB). | +| `--sync`, `-s` | Wait for completion (timeout after 60 s). | +| `--output json`, `-o` | Output JSONL (one JSON object per line for each invocation event). | Press `Ctrl+C` to cancel an in-flight invocation. The associated browser sessions are cleaned up automatically. @@ -50,6 +53,7 @@ List deployed app versions. |------|-------------| | `--name ` | Filter by app name. | | `--version ` | Filter by version label. | +| `--output json`, `-o` | Output raw JSON array. | ## `kernel app history ` Show deployment history for a specific app. @@ -57,6 +61,7 @@ Show deployment history for a specific app. | Flag | Description | |------|-------------| | `--limit ` | Maximum number of deployments to return (default: 100, `0` = all). | +| `--output json`, `-o` | Output raw JSON array. | ## `kernel logs ` Tail app logs. @@ -68,4 +73,4 @@ Tail app logs. | `--since `, `-s` | Fetch logs from a duration or timestamp (same formats as `kernel deploy logs`). | | `--with-timestamps` | Include timestamps in each line. | -Log lines longer than 64 KiB are truncated. +Log lines longer than 64 KiB are truncated. diff --git a/reference/cli/browsers.mdx b/reference/cli/browsers.mdx index b3358051..9f9e8f55 100644 --- 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` | 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` | Output raw JSON object. | ### `kernel browsers delete ` 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 ` Return a live view URL for remote monitoring and control. +| Flag | Description | +|------|-------------| +| `--output json`, `-o` | Output JSON with `liveViewUrl` field. | + +### `kernel browsers get ` +Get detailed information about a browser session. + +| Flag | Description | +|------|-------------| +| `--output json`, `-o` | Output raw JSON object. | + ## Browser logs ### `kernel browsers logs stream ` @@ -47,6 +63,10 @@ Stream browser logs from the supervisor or a file path. ### `kernel browsers replays list ` List replay recordings for a browser session. +| Flag | Description | +|------|-------------| +| `--output json`, `-o` | Output raw JSON array. | + ### `kernel browsers replays start ` Start recording a replay. @@ -54,6 +74,7 @@ Start recording a replay. |------|-------------| | `--framerate ` | Recording framerate in frames per second. | | `--max-duration ` | Maximum recording duration. | +| `--output json`, `-o` | Output raw JSON object. | ### `kernel browsers replays stop ` Stop an active replay recording. @@ -78,6 +99,7 @@ Execute a command synchronously inside the browser VM. | `--timeout ` | Execution timeout. | | `--as-user ` | Run as a specific user. | | `--as-root` | Run as root. | +| `--output json`, `-o` | Output raw JSON object. | ### `kernel browsers process spawn [--] [command...]` Execute a command asynchronously in the browser VM. @@ -90,6 +112,7 @@ Execute a command asynchronously in the browser VM. | `--timeout ` | Execution timeout. | | `--as-user ` | Run as a specific user. | | `--as-root` | Run as root. | +| `--output json`, `-o` | Output raw JSON object. | ### `kernel browsers process kill ` Send a signal to a process running in the browser VM. @@ -149,6 +172,7 @@ Retrieve metadata for a file or directory. | Flag | Description | |------|-------------| | `--path ` | Absolute file or directory path (required). | +| `--output json`, `-o` | Output raw JSON object. | ### `kernel browsers fs list-files ` List directory contents. @@ -156,6 +180,7 @@ List directory contents. | Flag | Description | |------|-------------| | `--path ` | Absolute directory path (required). | +| `--output json`, `-o` | Output raw JSON array. | ### `kernel browsers fs move ` 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` | Output raw JSON array. | + ### `kernel extensions upload ` Upload an unpacked extension directory. | Flag | Description | |------|-------------| | `--name ` | Optional unique extension name. | +| `--output json`, `-o` | Output raw JSON object. | ### `kernel extensions download ` 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` | Output raw JSON array. | + ### `kernel proxies get ` Show details for a proxy configuration. +| Flag | Description | +|------|-------------| +| `--output json`, `-o` | Output raw JSON object. | + ### `kernel proxies create` Create a new proxy configuration. @@ -354,6 +392,7 @@ Create a new proxy configuration. | `--port ` | Proxy port (custom; required). | | `--username ` | Proxy username (custom). | | `--password ` | Proxy password (custom). | +| `--output json`, `-o` | Output raw JSON object. | ### `kernel proxies delete ` Delete a proxy configuration. @@ -361,3 +400,89 @@ Delete a proxy configuration. | Flag | Description | |------|-------------| | `--yes`, `-y` | Skip confirmation. | + +## Browser pools + +### `kernel browser-pools list` +List all browser pools. + +| Flag | Description | +|------|-------------| +| `--output json`, `-o` | Output raw JSON array. | + +### `kernel browser-pools create` +Create a new browser pool. + +| Flag | Description | +|------|-------------| +| `--name ` | Optional unique name for the pool. | +| `--size ` | Number of browsers in the pool (required). | +| `--fill-rate ` | Percentage of the pool to fill per minute. | +| `--timeout ` | Idle timeout for browsers acquired from the pool. | +| `--output json`, `-o` | Output raw JSON object. | + +### `kernel browser-pools get ` +Get pool details. + +| Flag | Description | +|------|-------------| +| `--output json`, `-o` | Output raw JSON object. | + +### `kernel browser-pools update ` +Update pool configuration. + +| Flag | Description | +|------|-------------| +| `--size ` | Updated pool size. | +| `--discard-all-idle` | Discard all idle browsers and refill. | +| `--output json`, `-o` | Output raw JSON object. | + +### `kernel browser-pools acquire ` +Acquire a browser from the pool. + +| Flag | Description | +|------|-------------| +| `--timeout ` | Acquire timeout before returning 204. | +| `--output json`, `-o` | Output raw JSON object. | + +### `kernel browser-pools release ` +Release a browser back to the pool. + +| Flag | Description | +|------|-------------| +| `--session-id ` | Browser session ID to release (required). | +| `--reuse` | Reuse the browser instance (default: true). | + +### `kernel browser-pools delete ` +Delete a pool. + +| Flag | Description | +|------|-------------| +| `--force` | Force delete even if browsers are leased. | + +### `kernel browser-pools flush ` +Destroy all idle browsers in the pool. + +## Profiles + +### `kernel profiles list` +List all browser profiles. + +| Flag | Description | +|------|-------------| +| `--output json`, `-o` | Output raw JSON array. | + +### `kernel profiles get ` +Get profile details. + +| Flag | Description | +|------|-------------| +| `--output json`, `-o` | Output raw JSON object. | + +### `kernel profiles create` +Create a new browser profile. + +| Flag | Description | +|------|-------------| +| `--name ` | Optional unique name for the profile. | +| `--output json`, `-o` | Output raw JSON object. | From 67811c1065bb3d08480a751db1c3477e8379a666 Mon Sep 17 00:00:00 2001 From: Rafael Garcia Date: Fri, 9 Jan 2026 09:51:01 -0500 Subject: [PATCH 2/2] 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 --- reference/cli/apps.mdx | 10 ++++---- reference/cli/browsers.mdx | 50 ++++++++++++++++++++------------------ 2 files changed, 32 insertions(+), 28 deletions(-) diff --git a/reference/cli/apps.mdx b/reference/cli/apps.mdx index cd01b973..062fe025 100644 --- a/reference/cli/apps.mdx +++ b/reference/cli/apps.mdx @@ -11,7 +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 `, `-e` | Set environment variables (repeatable). | | `--env-file ` | Load environment variables from a file (repeatable). | -| `--output json`, `-o` | Output JSONL (one JSON object per line for each deployment event). | +| `--output json`, `-o json` | Output JSONL (one JSON object per line for each deployment event). | `package.json` (JS/TS) or `pyproject.toml` (Python) must be present next to the entrypoint. @@ -32,7 +32,7 @@ Show deployment history for all apps or a specific app. | Flag | Description | |------|-------------| | `--limit ` | Maximum number of deployments to return (default: 100, `0` = all). | -| `--output json`, `-o` | Output raw JSON array. | +| `--output json`, `-o json` | Output raw JSON array. | ## `kernel invoke ` Invoke an app action. By default the CLI returns immediately after the invocation is queued. @@ -42,7 +42,7 @@ Invoke an app action. By default the CLI returns immediately after the invocatio | `--version `, `-v` | Target a specific app version (default: latest). | | `--payload `, `-p` | Provide a JSON payload (stringified, max 64 KB). | | `--sync`, `-s` | Wait for completion (timeout after 60 s). | -| `--output json`, `-o` | Output JSONL (one JSON object per line for each invocation event). | +| `--output json`, `-o json` | Output JSONL (one JSON object per line for each invocation event). | Press `Ctrl+C` to cancel an in-flight invocation. The associated browser sessions are cleaned up automatically. @@ -53,7 +53,7 @@ List deployed app versions. |------|-------------| | `--name ` | Filter by app name. | | `--version ` | Filter by version label. | -| `--output json`, `-o` | Output raw JSON array. | +| `--output json`, `-o json` | Output raw JSON array. | ## `kernel app history ` Show deployment history for a specific app. @@ -61,7 +61,7 @@ Show deployment history for a specific app. | Flag | Description | |------|-------------| | `--limit ` | Maximum number of deployments to return (default: 100, `0` = all). | -| `--output json`, `-o` | Output raw JSON array. | +| `--output json`, `-o json` | Output raw JSON array. | ## `kernel logs ` Tail app logs. diff --git a/reference/cli/browsers.mdx b/reference/cli/browsers.mdx index 9f9e8f55..38c1bc98 100644 --- a/reference/cli/browsers.mdx +++ b/reference/cli/browsers.mdx @@ -11,7 +11,7 @@ List all browser sessions. | Flag | Description | |------|-------------| -| `--output json`, `-o` | Output raw JSON array. | +| `--output json`, `-o json` | Output raw JSON array. | ### `kernel browsers create` Create a new browser session. @@ -21,7 +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` | Output raw JSON object. | +| `--output json`, `-o json` | Output raw JSON object. | ### `kernel browsers delete ` Delete a browser session. Use `-y` to skip confirmation. @@ -35,14 +35,14 @@ Return a live view URL for remote monitoring and control. | Flag | Description | |------|-------------| -| `--output json`, `-o` | Output JSON with `liveViewUrl` field. | +| `--output json`, `-o json` | Output JSON with `liveViewUrl` field. | ### `kernel browsers get ` Get detailed information about a browser session. | Flag | Description | |------|-------------| -| `--output json`, `-o` | Output raw JSON object. | +| `--output json`, `-o json` | Output raw JSON object. | ## Browser logs @@ -65,7 +65,7 @@ List replay recordings for a browser session. | Flag | Description | |------|-------------| -| `--output json`, `-o` | Output raw JSON array. | +| `--output json`, `-o json` | Output raw JSON array. | ### `kernel browsers replays start ` Start recording a replay. @@ -74,7 +74,7 @@ Start recording a replay. |------|-------------| | `--framerate ` | Recording framerate in frames per second. | | `--max-duration ` | Maximum recording duration. | -| `--output json`, `-o` | Output raw JSON object. | +| `--output json`, `-o json` | Output raw JSON object. | ### `kernel browsers replays stop ` Stop an active replay recording. @@ -99,7 +99,7 @@ Execute a command synchronously inside the browser VM. | `--timeout ` | Execution timeout. | | `--as-user ` | Run as a specific user. | | `--as-root` | Run as root. | -| `--output json`, `-o` | Output raw JSON object. | +| `--output json`, `-o json` | Output raw JSON object. | ### `kernel browsers process spawn [--] [command...]` Execute a command asynchronously in the browser VM. @@ -112,7 +112,7 @@ Execute a command asynchronously in the browser VM. | `--timeout ` | Execution timeout. | | `--as-user ` | Run as a specific user. | | `--as-root` | Run as root. | -| `--output json`, `-o` | Output raw JSON object. | +| `--output json`, `-o json` | Output raw JSON object. | ### `kernel browsers process kill ` Send a signal to a process running in the browser VM. @@ -172,7 +172,7 @@ Retrieve metadata for a file or directory. | Flag | Description | |------|-------------| | `--path ` | Absolute file or directory path (required). | -| `--output json`, `-o` | Output raw JSON object. | +| `--output json`, `-o json` | Output raw JSON object. | ### `kernel browsers fs list-files ` List directory contents. @@ -180,7 +180,7 @@ List directory contents. | Flag | Description | |------|-------------| | `--path ` | Absolute directory path (required). | -| `--output json`, `-o` | Output raw JSON array. | +| `--output json`, `-o json` | Output raw JSON array. | ### `kernel browsers fs move ` Move or rename a file or directory. @@ -322,7 +322,7 @@ List all uploaded extensions. | Flag | Description | |------|-------------| -| `--output json`, `-o` | Output raw JSON array. | +| `--output json`, `-o json` | Output raw JSON array. | ### `kernel extensions upload ` Upload an unpacked extension directory. @@ -330,7 +330,7 @@ Upload an unpacked extension directory. | Flag | Description | |------|-------------| | `--name ` | Optional unique extension name. | -| `--output json`, `-o` | Output raw JSON object. | +| `--output json`, `-o json` | Output raw JSON object. | ### `kernel extensions download ` Download an extension archive. @@ -364,14 +364,14 @@ List available proxy configurations. | Flag | Description | |------|-------------| -| `--output json`, `-o` | Output raw JSON array. | +| `--output json`, `-o json` | Output raw JSON array. | ### `kernel proxies get ` Show details for a proxy configuration. | Flag | Description | |------|-------------| -| `--output json`, `-o` | Output raw JSON object. | +| `--output json`, `-o json` | Output raw JSON object. | ### `kernel proxies create` Create a new proxy configuration. @@ -392,7 +392,7 @@ Create a new proxy configuration. | `--port ` | Proxy port (custom; required). | | `--username ` | Proxy username (custom). | | `--password ` | Proxy password (custom). | -| `--output json`, `-o` | Output raw JSON object. | +| `--output json`, `-o json` | Output raw JSON object. | ### `kernel proxies delete ` Delete a proxy configuration. @@ -403,12 +403,14 @@ Delete a proxy configuration. ## 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` | Output raw JSON array. | +| `--output json`, `-o json` | Output raw JSON array. | ### `kernel browser-pools create` Create a new browser pool. @@ -419,14 +421,14 @@ Create a new browser pool. | `--size ` | Number of browsers in the pool (required). | | `--fill-rate ` | Percentage of the pool to fill per minute. | | `--timeout ` | Idle timeout for browsers acquired from the pool. | -| `--output json`, `-o` | Output raw JSON object. | +| `--output json`, `-o json` | Output raw JSON object. | ### `kernel browser-pools get ` Get pool details. | Flag | Description | |------|-------------| -| `--output json`, `-o` | Output raw JSON object. | +| `--output json`, `-o json` | Output raw JSON object. | ### `kernel browser-pools update ` Update pool configuration. @@ -435,7 +437,7 @@ Update pool configuration. |------|-------------| | `--size ` | Updated pool size. | | `--discard-all-idle` | Discard all idle browsers and refill. | -| `--output json`, `-o` | Output raw JSON object. | +| `--output json`, `-o json` | Output raw JSON object. | ### `kernel browser-pools acquire ` Acquire a browser from the pool. @@ -443,7 +445,7 @@ Acquire a browser from the pool. | Flag | Description | |------|-------------| | `--timeout ` | Acquire timeout before returning 204. | -| `--output json`, `-o` | Output raw JSON object. | +| `--output json`, `-o json` | Output raw JSON object. | ### `kernel browser-pools release ` Release a browser back to the pool. @@ -465,19 +467,21 @@ 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` | Output raw JSON array. | +| `--output json`, `-o json` | Output raw JSON array. | ### `kernel profiles get ` Get profile details. | Flag | Description | |------|-------------| -| `--output json`, `-o` | Output raw JSON object. | +| `--output json`, `-o json` | Output raw JSON object. | ### `kernel profiles create` Create a new browser profile. @@ -485,4 +489,4 @@ Create a new browser profile. | Flag | Description | |------|-------------| | `--name ` | Optional unique name for the profile. | -| `--output json`, `-o` | Output raw JSON object. | +| `--output json`, `-o json` | Output raw JSON object. |