Skip to content

Commit b1da0f0

Browse files
rgarciargarcia
committed
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
1 parent 1953a00 commit b1da0f0

File tree

3 files changed

+151
-4
lines changed

3 files changed

+151
-4
lines changed

‎reference/cli.mdx‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,23 @@ kernel invoke my-app action-name --payload '{"key":"value"}'
6464
- `--no-color` - Disable color output
6565
- `--log-level <level>` - Set the log level (trace, debug, info, warn, error, fatal, print)
6666

67+
## JSON Output
68+
69+
Many commands support `--output json` (or `-o json`) for machine-readable output, useful for scripting and automation:
70+
71+
```bash
72+
# Get browser session as JSON
73+
kernel browsers create -o json
74+
75+
# List apps as JSON array
76+
kernel app list -o json
77+
78+
# Deploy with JSONL streaming (one JSON object per line)
79+
kernel deploy index.ts -o json
80+
```
81+
82+
See individual command documentation for JSON output availability.
83+
6784
<Info>
6885
Looking for the API? See the [API Reference](/api-reference/invocations/invoke-an-action).
6986
</Info>

‎reference/cli/apps.mdx‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ Deploy an app to Kernel from the current directory. The entrypoint file and depe
1111
| `--force` | Overwrite an existing version with the same label. |
1212
| `--env <KEY=VALUE>`, `-e` | Set environment variables (repeatable). |
1313
| `--env-file <file>` | Load environment variables from a file (repeatable). |
14+
| `--output json`, `-o` | Output JSONL (one JSON object per line for each deployment event). |
1415

1516
<Info>`package.json` (JS/TS) or `pyproject.toml` (Python) must be present next to the entrypoint.</Info>
1617

@@ -23,23 +24,25 @@ Stream build and runtime logs for a deployment.
2324
| `--since <duration>`, `-s` | Fetch logs starting from a relative duration (e.g. `5m`, `1h`, `1h30m`) or timestamp (`2006-01-02T15:04`). |
2425
| `--with-timestamps`, `-t` | Prefix each line with an RFC3339 timestamp. |
2526

26-
<Info>Log lines longer than 64 KiB are truncated. Emit bulky payloads to external storage and log references.</Info>
27+
<Info>Log lines longer than 64 KiB are truncated. Emit bulky payloads to external storage and log references.</Info>
2728

2829
## `kernel deploy history [app_name]`
2930
Show deployment history for all apps or a specific app.
3031

3132
| Flag | Description |
3233
|------|-------------|
3334
| `--limit <n>` | Maximum number of deployments to return (default: 100, `0` = all). |
35+
| `--output json`, `-o` | Output raw JSON array. |
3436

3537
## `kernel invoke <app> <action>`
3638
Invoke an app action. By default the CLI returns immediately after the invocation is queued.
3739

3840
| Flag | Description |
3941
|------|-------------|
4042
| `--version <version>`, `-v` | Target a specific app version (default: latest). |
41-
| `--payload <json>`, `-p` | Provide a JSON payload (stringified, max 64 KB). |
42-
| `--sync`, `-s` | Wait for completion (timeout after 60 s). |
43+
| `--payload <json>`, `-p` | Provide a JSON payload (stringified, max 64 KB). |
44+
| `--sync`, `-s` | Wait for completion (timeout after 60 s). |
45+
| `--output json`, `-o` | Output JSONL (one JSON object per line for each invocation event). |
4346

4447
<Info>Press `Ctrl+C` to cancel an in-flight invocation. The associated browser sessions are cleaned up automatically.</Info>
4548

@@ -50,13 +53,15 @@ List deployed app versions.
5053
|------|-------------|
5154
| `--name <app_name>` | Filter by app name. |
5255
| `--version <version>` | Filter by version label. |
56+
| `--output json`, `-o` | Output raw JSON array. |
5357

5458
## `kernel app history <app_name>`
5559
Show deployment history for a specific app.
5660

5761
| Flag | Description |
5862
|------|-------------|
5963
| `--limit <n>` | Maximum number of deployments to return (default: 100, `0` = all). |
64+
| `--output json`, `-o` | Output raw JSON array. |
6065

6166
## `kernel logs <app_name>`
6267
Tail app logs.
@@ -68,4 +73,4 @@ Tail app logs.
6873
| `--since <duration>`, `-s` | Fetch logs from a duration or timestamp (same formats as `kernel deploy logs`). |
6974
| `--with-timestamps` | Include timestamps in each line. |
7075

71-
<Info>Log lines longer than 64 KiB are truncated.</Info>
76+
<Info>Log lines longer than 64 KiB are truncated.</Info>

‎reference/cli/browsers.mdx‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,10 @@ title: "Browsers"
99
### `kernel browsers list`
1010
List all browser sessions.
1111

12+
| Flag | Description |
13+
|------|-------------|
14+
| `--output json`, `-o` | Output raw JSON array. |
15+
1216
### `kernel browsers create`
1317
Create a new browser session.
1418

@@ -17,6 +21,7 @@ Create a new browser session.
1721
| `--stealth` | Enable stealth mode to reduce automation fingerprints. |
1822
| `--headless` | Launch without GUI/VNC access. |
1923
| `--kiosk` | Launch in Chrome kiosk mode. |
24+
| `--output json`, `-o` | Output raw JSON object. |
2025

2126
### `kernel browsers delete <session-id>`
2227
Delete a browser session. Use `-y` to skip confirmation.
@@ -28,6 +33,17 @@ Delete a browser session. Use `-y` to skip confirmation.
2833
### `kernel browsers view <session-id>`
2934
Return a live view URL for remote monitoring and control.
3035

36+
| Flag | Description |
37+
|------|-------------|
38+
| `--output json`, `-o` | Output JSON with `liveViewUrl` field. |
39+
40+
### `kernel browsers get <session-id>`
41+
Get detailed information about a browser session.
42+
43+
| Flag | Description |
44+
|------|-------------|
45+
| `--output json`, `-o` | Output raw JSON object. |
46+
3147
## Browser logs
3248

3349
### `kernel browsers logs stream <session-id>`
@@ -47,13 +63,18 @@ Stream browser logs from the supervisor or a file path.
4763
### `kernel browsers replays list <session-id>`
4864
List replay recordings for a browser session.
4965

66+
| Flag | Description |
67+
|------|-------------|
68+
| `--output json`, `-o` | Output raw JSON array. |
69+
5070
### `kernel browsers replays start <session-id>`
5171
Start recording a replay.
5272

5373
| Flag | Description |
5474
|------|-------------|
5575
| `--framerate <fps>` | Recording framerate in frames per second. |
5676
| `--max-duration <seconds>` | Maximum recording duration. |
77+
| `--output json`, `-o` | Output raw JSON object. |
5778

5879
### `kernel browsers replays stop <session-id> <replay-id>`
5980
Stop an active replay recording.
@@ -78,6 +99,7 @@ Execute a command synchronously inside the browser VM.
7899
| `--timeout <seconds>` | Execution timeout. |
79100
| `--as-user <user>` | Run as a specific user. |
80101
| `--as-root` | Run as root. |
102+
| `--output json`, `-o` | Output raw JSON object. |
81103

82104
### `kernel browsers process spawn <session-id> [--] [command...]`
83105
Execute a command asynchronously in the browser VM.
@@ -90,6 +112,7 @@ Execute a command asynchronously in the browser VM.
90112
| `--timeout <seconds>` | Execution timeout. |
91113
| `--as-user <user>` | Run as a specific user. |
92114
| `--as-root` | Run as root. |
115+
| `--output json`, `-o` | Output raw JSON object. |
93116

94117
### `kernel browsers process kill <session-id> <process-id>`
95118
Send a signal to a process running in the browser VM.
@@ -149,13 +172,15 @@ Retrieve metadata for a file or directory.
149172
| Flag | Description |
150173
|------|-------------|
151174
| `--path <path>` | Absolute file or directory path (required). |
175+
| `--output json`, `-o` | Output raw JSON object. |
152176

153177
### `kernel browsers fs list-files <session-id>`
154178
List directory contents.
155179

156180
| Flag | Description |
157181
|------|-------------|
158182
| `--path <path>` | Absolute directory path (required). |
183+
| `--output json`, `-o` | Output raw JSON array. |
159184

160185
### `kernel browsers fs move <session-id>`
161186
Move or rename a file or directory.
@@ -295,12 +320,17 @@ Execute Playwright/TypeScript code against a running browser session.
295320
### `kernel extensions list`
296321
List all uploaded extensions.
297322

323+
| Flag | Description |
324+
|------|-------------|
325+
| `--output json`, `-o` | Output raw JSON array. |
326+
298327
### `kernel extensions upload <directory>`
299328
Upload an unpacked extension directory.
300329

301330
| Flag | Description |
302331
|------|-------------|
303332
| `--name <name>` | Optional unique extension name. |
333+
| `--output json`, `-o` | Output raw JSON object. |
304334

305335
### `kernel extensions download <id-or-name>`
306336
Download an extension archive.
@@ -332,9 +362,17 @@ Upload one or more unpacked Chrome extensions directly into a running browser se
332362
### `kernel proxies list`
333363
List available proxy configurations.
334364

365+
| Flag | Description |
366+
|------|-------------|
367+
| `--output json`, `-o` | Output raw JSON array. |
368+
335369
### `kernel proxies get <id>`
336370
Show details for a proxy configuration.
337371

372+
| Flag | Description |
373+
|------|-------------|
374+
| `--output json`, `-o` | Output raw JSON object. |
375+
338376
### `kernel proxies create`
339377
Create a new proxy configuration.
340378

@@ -354,10 +392,97 @@ Create a new proxy configuration.
354392
| `--port <port>` | Proxy port (custom; required). |
355393
| `--username <username>` | Proxy username (custom). |
356394
| `--password <password>` | Proxy password (custom). |
395+
| `--output json`, `-o` | Output raw JSON object. |
357396

358397
### `kernel proxies delete <id>`
359398
Delete a proxy configuration.
360399

361400
| Flag | Description |
362401
|------|-------------|
363402
| `--yes`, `-y` | Skip confirmation. |
403+
404+
## Browser pools
405+
406+
### `kernel browser-pools list`
407+
List all browser pools.
408+
409+
| Flag | Description |
410+
|------|-------------|
411+
| `--output json`, `-o` | Output raw JSON array. |
412+
413+
### `kernel browser-pools create`
414+
Create a new browser pool.
415+
416+
| Flag | Description |
417+
|------|-------------|
418+
| `--name <name>` | Optional unique name for the pool. |
419+
| `--size <n>` | Number of browsers in the pool (required). |
420+
| `--fill-rate <n>` | Percentage of the pool to fill per minute. |
421+
| `--timeout <seconds>` | Idle timeout for browsers acquired from the pool. |
422+
| `--output json`, `-o` | Output raw JSON object. |
423+
424+
### `kernel browser-pools get <id-or-name>`
425+
Get pool details.
426+
427+
| Flag | Description |
428+
|------|-------------|
429+
| `--output json`, `-o` | Output raw JSON object. |
430+
431+
### `kernel browser-pools update <id-or-name>`
432+
Update pool configuration.
433+
434+
| Flag | Description |
435+
|------|-------------|
436+
| `--size <n>` | Updated pool size. |
437+
| `--discard-all-idle` | Discard all idle browsers and refill. |
438+
| `--output json`, `-o` | Output raw JSON object. |
439+
440+
### `kernel browser-pools acquire <id-or-name>`
441+
Acquire a browser from the pool.
442+
443+
| Flag | Description |
444+
|------|-------------|
445+
| `--timeout <seconds>` | Acquire timeout before returning 204. |
446+
| `--output json`, `-o` | Output raw JSON object. |
447+
448+
### `kernel browser-pools release <id-or-name>`
449+
Release a browser back to the pool.
450+
451+
| Flag | Description |
452+
|------|-------------|
453+
| `--session-id <id>` | Browser session ID to release (required). |
454+
| `--reuse` | Reuse the browser instance (default: true). |
455+
456+
### `kernel browser-pools delete <id-or-name>`
457+
Delete a pool.
458+
459+
| Flag | Description |
460+
|------|-------------|
461+
| `--force` | Force delete even if browsers are leased. |
462+
463+
### `kernel browser-pools flush <id-or-name>`
464+
Destroy all idle browsers in the pool.
465+
466+
## Profiles
467+
468+
### `kernel profiles list`
469+
List all browser profiles.
470+
471+
| Flag | Description |
472+
|------|-------------|
473+
| `--output json`, `-o` | Output raw JSON array. |
474+
475+
### `kernel profiles get <id-or-name>`
476+
Get profile details.
477+
478+
| Flag | Description |
479+
|------|-------------|
480+
| `--output json`, `-o` | Output raw JSON object. |
481+
482+
### `kernel profiles create`
483+
Create a new browser profile.
484+
485+
| Flag | Description |
486+
|------|-------------|
487+
| `--name <name>` | Optional unique name for the profile. |
488+
| `--output json`, `-o` | Output raw JSON object. |

0 commit comments

Comments
 (0)