feat: add --output json flag for machine-readable output #67

rgarcia · 2026-01-08T23:38:36Z

Summary

Add --output json (or -o json) flag to CLI commands for machine-readable output
For streaming commands (deploy, invoke), output is JSONL format (one JSON object per line)
For list commands, output is a JSON array
For single-object commands, output is a JSON object
Update README with JSON output documentation

Commands with JSON output support:

Tier 1 (create/acquire operations):

browsers create
browser-pools create, acquire
profiles create
extensions upload
proxies create
deploy (JSONL streaming)

Tier 2 (list/get operations):

browsers list, get, view
browser-pools list, get, update
profiles list, get
extensions list
proxies list, get

Tier 3 (app/invoke/browser sub-operations):

app list, history
deploy history
invoke (JSONL streaming), history
browsers replays list, start
browsers process exec, spawn
browsers fs file-info, list-files

Test plan

Test kernel browsers create -o json returns valid JSON
Test kernel deploy index.ts -o json streams JSONL events
Test kernel app list -o json returns JSON array
Test invalid --output value shows error message

Note

Adds machine-readable output across the CLI and documents it.

Introduces --output json/-o json for many commands (apps, browsers, browser-pools, profiles, extensions, proxies), emitting raw JSON objects/arrays; suppresses interactive logs when JSON is selected and validates unsupported values
Implements JSONL streaming for deploy and invoke follow operations, including terminal-state handling and JSON-formatted errors; updates followDeployment/invocation streaming paths
Extends subcommands with new flags and JSON marshalling (e.g., browsers view/get/create, replays list/start, process exec/spawn, fs file-info/list-files; browser-pools create/get/update/acquire; app list/history; deploy history)
Minor flag tweak: browsers replays download switches to -f/--output-file
Updates README with JSON output examples and per-command support list

^{Written by Cursor Bugbot for commit 362c55a. This will update automatically on new commits. Configure here.}

Add JSON output support to CLI commands for scripting and automation: Tier 1 (create/acquire operations): - browsers create - browser-pools create, acquire - profiles create - extensions upload - proxies create - deploy (JSONL streaming) Tier 2 (list/get operations): - browsers list, get, view - browser-pools list, get, update - profiles list, get - extensions list - proxies list, get Tier 3 (app/invoke/browser sub-operations): - app list, history - deploy history - invoke (JSONL streaming), history - browsers replays list, start - browsers process exec, spawn - browsers fs file-info, list-files For streaming commands (deploy, invoke), output is JSONL format (one JSON object per line) for real-time parsing. Usage: --output json or -o json

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

tembo · 2026-01-08T23:42:57Z

cmd/app.go

+
+	if output != "" && output != "json" {
+		pterm.Error.Println("unsupported --output value: use 'json'")
+		return nil


Returning nil here exits 0, which is a bit surprising for an invalid flag value (especially if this is used in scripts). Consider returning an error so the CLI exits non-zero.

Suggested change

return nil

if output != "" && output != "json" {

return fmt.Errorf("unsupported --output value: use 'json'")

}

tembo · 2026-01-08T23:43:00Z

cmd/deploy.go

+				if status == string(kernel.DeploymentGetResponseStatusFailed) ||
+					status == string(kernel.DeploymentGetResponseStatusStopped) ||
+					status == string(kernel.DeploymentGetResponseStatusRunning) {
+					return nil


In JSONL mode this returns success even when the deployment fails/stops. It’d be nicer for automation if the exit code still reflected failure.

Suggested change

return nil

if status == string(kernel.DeploymentGetResponseStatusFailed) ||

status == string(kernel.DeploymentGetResponseStatusStopped) {

return fmt.Errorf("deployment %s: %s", status, deploymentState.Deployment.StatusReason)

}

if status == string(kernel.DeploymentGetResponseStatusRunning) {

return nil

}

tembo · 2026-01-08T23:43:02Z

cmd/invoke.go

 	if resp.Status != kernel.InvocationNewResponseStatusQueued {
+		if jsonOutput {
+			bs, _ := json.Marshal(resp)
+			fmt.Println(string(bs))


Minor: avoid ignoring json.Marshal errors here.

Suggested change

fmt.Println(string(bs))

bs, err := json.Marshal(resp)

if err != nil {

return err

}

fmt.Println(string(bs))

cmd/browsers.go

cmd/deploy.go

cmd/browser_pools.go

cmd/profiles.go

cmd/invoke.go

- profiles get: output null instead of pterm error when profile not found - invoke: output JSON error object instead of human-readable text when API call fails in JSON mode Addresses cursor[bot] review feedback.

1. Fix replays download flag: read "output-file" instead of "output" 2. Return proper exit codes in JSON mode for failures: - deploy: return error on failed/stopped deployments - invoke: return error on failed invocations 3. Handle acquire timeout in JSON mode: - browser-pools acquire: output null instead of pterm warning - browsers create (with pool): output null instead of pterm error

cmd/browsers.go

Sayan- · 2026-01-09T00:24:47Z

cmd/app.go

+
+	if output != "" && output != "json" {
+		pterm.Error.Println("unsupported --output value: use 'json'")
+		return nil


Should we return an error and exit non-zero instead of just error logging? Might be more script-friendly.

Sayan- · 2026-01-09T00:25:02Z

Small gotcha in cmd/browsers.go line 2177-2184: allowedFlags should include "output": true since it's not a browser config flag. Open to removing this check in favor of a simpler pattern if you have ideas.

Sayan-

Nice feature! Two small items flagged inline/in comments.

1. Return error (non-zero exit) for invalid --output value instead of just logging and returning nil - more script-friendly 2. Add "output" to allowedFlags in browsers create pool path so --output flag doesn't conflict with pool configuration

* 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

cursor · 2026-01-09T14:59:40Z

cmd/deploy.go

+
+	if output != "" && output != "json" {
+		return fmt.Errorf("unsupported --output value: use 'json'")
+	}


Missing output flag registration on deploy github subcommand

Medium Severity

The runDeployGithub handler reads the output flag on line 97, but this flag is not registered on deployGithubCmd. The flag is only registered on the parent deployCmd (line 60), and Cobra's regular Flags() are not inherited by subcommands. Users running kernel deploy github ... -o json will get an "unknown flag: -o" error instead of JSON output.

Additional Locations (1)

cmd/deploy.go#L73-L83

rgarcia mentioned this pull request Jan 8, 2026

docs: add --output json flag documentation for CLI commands kernel/docs#161

Merged

2 tasks

tembo bot approved these changes Jan 8, 2026

View reviewed changes

cursor bot reviewed Jan 8, 2026

View reviewed changes

cmd/browsers.go Show resolved Hide resolved

cmd/deploy.go Show resolved Hide resolved

rgarcia requested a review from Sayan- January 8, 2026 23:50

fix: update test files to pass required input structs to List methods

7070bc5

cursor bot reviewed Jan 8, 2026

View reviewed changes

cmd/browser_pools.go Show resolved Hide resolved

cmd/profiles.go Show resolved Hide resolved

cmd/invoke.go Show resolved Hide resolved

rgarcia added 2 commits January 8, 2026 18:59

fix: handle JSON mode properly for error cases

52b5c9b

- profiles get: output null instead of pterm error when profile not found - invoke: output JSON error object instead of human-readable text when API call fails in JSON mode Addresses cursor[bot] review feedback.

cursor bot reviewed Jan 9, 2026

View reviewed changes

cmd/browsers.go Show resolved Hide resolved

Sayan- reviewed Jan 9, 2026

View reviewed changes

Sayan- approved these changes Jan 9, 2026

View reviewed changes

fix: address Sayan's review feedback

362c55a

1. Return error (non-zero exit) for invalid --output value instead of just logging and returning nil - more script-friendly 2. Add "output" to allowedFlags in browsers create pool path so --output flag doesn't conflict with pool configuration

rgarcia merged commit 251fba5 into main Jan 9, 2026
2 checks passed

rgarcia deleted the add-json-output-flag branch January 9, 2026 14:53

cursor bot reviewed Jan 9, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add --output json flag for machine-readable output #67

feat: add --output json flag for machine-readable output #67

Uh oh!

rgarcia commented Jan 8, 2026 •

edited by cursor bot

Loading

Uh oh!

tembo bot Jan 8, 2026

Uh oh!

tembo bot Jan 8, 2026

Uh oh!

tembo bot Jan 8, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Sayan- Jan 9, 2026

Uh oh!

Sayan- commented Jan 9, 2026

Uh oh!

Sayan- left a comment

Uh oh!

Uh oh!

cursor bot Jan 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

-			fmt.Println(string(bs))
+			bs, err := json.Marshal(resp)
+			if err != nil {
+				return err
+			}
+			fmt.Println(string(bs))

feat: add --output json flag for machine-readable output #67

feat: add --output json flag for machine-readable output #67

Uh oh!

Conversation

rgarcia commented Jan 8, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Commands with JSON output support:

Test plan

Uh oh!

tembo bot Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

tembo bot Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

tembo bot Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Sayan- Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

Sayan- commented Jan 9, 2026

Uh oh!

Sayan- left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor bot Jan 9, 2026

Choose a reason for hiding this comment

Missing output flag registration on deploy github subcommand

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rgarcia commented Jan 8, 2026 •

edited by cursor bot

Loading