Skip to content

Add JSON output, typed exit codes and a .valar.yml schema - #21

Merged
lnsp merged 1 commit into
masterfrom
cli-json-output
Nov 20, 2026
Merged

lnsp merged 1 commit into
masterfrom
cli-json-output

Conversation

@lnsp

@lnsp lnsp commented Nov 20, 2026

Copy link
Copy Markdown
Member

Machine-readable output

--json, or VALAR_OUTPUT=json, makes every command print its result as one JSON document on stdout:

  • lists are arrays of objects with the API's lowerCamelCase field names ([] when empty);
  • single results are the API object (build inspect, batch inspect, deployment create/rollback, project create, whoami, ...); commands without a result body print a small object naming what changed ({"domain": "...", "deleted": true});
  • service logs, build logs, build watch and batch logs print one JSON object per line: build log entries as {"timestamp", "source", "stage", "content"}, service and batch output as {"content"};
  • progress (push --wait build log, prompts, batch run --follow output) goes to stderr;
  • errors go to stderr as {"error": {"kind": "notFound", "message": "..."}}, including cobra's argument and flag errors.

build push --json prints the submitted build right away, so its ID is known even when --wait then fails.

Human output is unchanged.

Exit codes

Code Kind Meaning
0 success
1 failed the operation ran and failed (build, deployment, batch execution)
2 invalid bad arguments, flags or configuration
3 notFound API 404/410, no builds, unknown service
4 notAllowed API 401/403
5 conflict API 409, service init over an existing file
6 unavailable connection errors, API 429 and 5xx

Untyped errors keep exit code 1. Cobra usage errors and missing settings (Operation requires ...) now exit with 2. build status keeps exiting 1 for any build that is not done, and now reports API errors instead of exiting 0. The table is in valar help and the README.

.valar.yml schema

valar config schema prints a JSON Schema generated from the config types; it is checked in at schema/valar.yml.json and TestSchema_MatchesCheckedInFile fails when they drift (go test ./config -run TestSchema -update regenerates it). Loading .valar.yml now refuses unknown keys, for example:

/path/.valar.yml: line 4: unknown key "constructr" in build, known keys are constructor, environment, ignore

The deprecated environment lists stay valid and keep their push warning.

Tests

Table-driven tests for the status-to-exit-code mapping, JSON error output, --json/VALAR_OUTPUT detection, JSON line streaming, JSON output of list and inspect commands, and schema validation.

--json, or VALAR_OUTPUT=json, makes every command print its result as one
JSON document on stdout, logs as one JSON object per line, and errors as
{"error": {"kind", "message"}} on stderr. Human output is unchanged.

Exit codes now tell failures apart: 1 failed, 2 invalid arguments or
configuration, 3 not found, 4 not allowed, 5 conflict, 6 unavailable.
They are listed in 'valar help' and the README.

'valar config schema' prints the JSON Schema of .valar.yml, generated from
the config types and checked in at schema/valar.yml.json; a test keeps the
two in step. Loading .valar.yml refuses unknown keys, naming the key, its
line and the file.
@lnsp
lnsp merged commit 36db620 into master Nov 20, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant