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

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:

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:

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:

jq -r '.problems[]?.kind' verify.json

Verify a bundle 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:

{
  "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

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:

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 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.