# JSON output Save command results, capture progress events, and read them in scripts. Source: https://debark.dev/docs/reference/json-output --- Use `--json` for a command’s final result and `--json-events PATH` for events while it runs. These options disable interactive prompts and terminal progress displays. They cannot be used with `--interactive`. ## Save a result and event stream ```bash debark build --snapshot target.snapshot.tar.zst \ --out ./bundle --sign operator.key \ --json --json-events build-events.ndjson jq > build-result.json ``` This example assumes the snapshot and signing key already exist. The final result goes to `build-result.json`; events go to `build-events.ndjson`; error messages go to stderr. Check the exit code before using the result. An early failure may occur before a JSON report is written. An incomplete build can write a report and return exit code 3. Use `--json-events -` when you want events on stdout. Keep the final result and events in separate outputs so your parser receives one format at a time. ## What each command returns | Command | JSON result | | ----------------------------- | ------------------------------------------------------------------------------------- | | `snapshot create` | `path`, `digest`, and `target`. | | `snapshot inspect` | Full `debark.snapshot/v1` document. | | `snapshot from-base` | `path`, `digest`, `backend`, `base`, `origin`, and `target`. | | `snapshot list-bases` | `debark.baselist/v1` base list. | | `build` | `debark.buildjob/v1` build result. | | `verify` | `debark.verifyreport/v1` verification report. | | `install`, including previews | `debark.installreport/v1` installation report. | | `inspect` | `debark.inspect/v1`: bundle path, signing indicator, manifest, and lock. | | `doctor` | `debark.doctorreport/v1` findings. | | `store ls` | `debark.storeindex/v1` cache index. | | `store gc` | `removed`, `kept`, `bytes_freed`, and `bytes_remaining`. | | `config show` | `debark.config/v1` effective configuration. | | `version` | `name`, `version`, `edition`, `go_version`, `platform`, and available build metadata. | | `keygen` | `key_id`, `private_key`, and `public_key` paths. | `config init` and `config path` always print plain text. Results without a named schema in this table do not include a schema version field. ## Read verification results Save the report: ```bash debark verify ./bundle --key operator.pub --json > verify.json ``` The key fields are `ok`, `signed`, `signatures`, `problems`, `files_checked`, and `bytes_checked`. `ok` means the required checks passed. `signed` means a signature verified against a trusted key. The bundle can still fail a later file check, so read both. For signed bundles, run without `--allow-unsigned`. In a Bash script with `jq`: ```bash set -euo pipefail debark verify ./bundle --key operator.pub --json > verify.json jq -e '.ok and .signed' verify.json > /dev/null ``` For a failed report, list its problem kinds: ```bash jq -r '.problems[]?.kind' verify.json ``` [Verify a bundle](/docs/trust/verifying) explains common problems. Do not use the `signed` indicator from `inspect` as a verification result; inspection does not check signatures. ## Event format An event stream is NDJSON: one complete JSON object per line. Each event has these fields: | Field | Meaning | | -------- | --------------------------------------------------------- | | `schema` | `debark.events/v1`. | | `ts` | UTC timestamp. | | `type` | Event name, such as `fetch.file`. | | `level` | Optional `info`, `warn`, or `error`; absent means `info`. | | `msg` | Optional human-readable message. | | `attrs` | Optional fields specific to the event type. | For example, this is an illustrative warning event: ```json { "schema": "debark.events/v1", "ts": "2026-09-06T12:00:00Z", "type": "warning", "level": "warn", "msg": "Example warning" } ``` Use `type`, `level`, and structured attributes in scripts. Message wording can change. ### Event types | Type | Meaning | | ---------------------- | ------------------------------------------------ | | `snapshot.created` | A snapshot was written. | | `snapshot.loaded` | The target snapshot was loaded. | | `backend.selected` | The local or container backend was selected. | | `apt.update` | apt repository indexes were refreshed. | | `apt.resolve` | apt resolved the package request. | | `fetch.file` | A package file was downloaded. | | `input.external` | A vendor URL or local package entered the build. | | `store.hit` | A cached download was reused. | | `policy.finding` | A policy rule produced a finding. | | `doctor.finding` | A package check produced a finding. | | `repo.indexed` | The bundle repository was indexed. | | `closed_world.checked` | The offline dependency check ran. | | `manifest.signed` | The manifest was signed. | | `bundle.assembled` | The bundle was assembled. | | `bundle.pruned` | Superseded files were removed. | | `verify.result` | Verification produced a result. | | `install.plan` | An installation plan was prepared. | | `install.result` | Installation produced a result. | | `warning` | The command recorded a warning. | | `build.started` | A build started. | | `build.finished` | A build finished. | | `progress` | A longer operation reported progress. | ### Read warnings with jq ```bash jq -r 'select(.level == "warn") | [.type, .msg] | @tsv' build-events.ndjson ``` The bundle’s `evidence.json` is a single document containing `schema`, `created_at`, optional `context`, and an `events` array. To read its warnings: ```bash jq -r '.events[] | select(.level == "warn") | [.type, .msg] | @tsv' ./bundle/evidence.json ``` The live stream and bundle record use the same event objects, with different outer formats. ## Schemas for integrations The [schema directory](https://github.com/inferops/debark/tree/main/api/schema) contains JSON Schema files and example fixtures. | Schema file | Describes | | ------------------------------ | --------------------------------------------------------------- | | `baselist.v1.schema.json` | Base list. | | `buildjob.v1.schema.json` | Build request and result. | | `doctorreport.v1.schema.json` | Doctor findings. | | `events.v1.schema.json` | Evidence document; `$defs/Event` describes each streamed event. | | `installreport.v1.schema.json` | Install result and preview. | | `lock.v1.schema.json` | Bundle package plan. | | `manifest.v1.schema.json` | Bundle manifest. | | `plugin.v1.schema.json` | Signing plugin messages. | | `policy.v1.schema.json` | Build policy. | | `signature.v1.schema.json` | Detached bundle signatures. | | `snapshot.v1.schema.json` | Target snapshot. | | `storeindex.v1.schema.json` | Download cache index. | | `verifyreport.v1.schema.json` | Verification result. | Use the schemas from the source revision matching your installed binary. Check required fields and allow for new event types or optional fields when upgrading an integration.