JSON Output & Scripting

--output json or -o json requests machine-readable output from commands with a structured response. It is a global flag and must appear before the subcommand:

1ctl -o json app list
1ctl --output json app get my-api

Verified application shapes

Command	Shape	Useful fields
1ctl app list	Array	app_label, deployment_id, status, domain
1ctl app get	Object	app_label, deployment_id, image, port, domain, namespace
1ctl app status	Object	deployment, status, domain_status, ingress
1ctl app releases	Array	version_number, version_id, image, status
1ctl config list	Array	deployment_id, app_label, key_values
1ctl secret list	Array	Secret-group metadata only

Mutation commands such as deploy, config create, and secret create print confirmation output rather than a stable JSON response.

Common patterns

Read an app URL:

URL=$(1ctl -o json app get my-api | jq -r '.domain')
printf 'App is live at: %s\n' "$URL"

Assert workload status:

STATUS=$(1ctl -o json app status my-api | jq -r '.status.status')
if [ "$STATUS" != "Running" ]; then
  echo "Deployment is not running: $STATUS"
  exit 1
fi

Running describes the workload. For an end-to-end check, also request the public URL or run Doctor with a smoke path.

DEPLOYMENT_ID=$(1ctl -o json app get my-api | jq -r '.deployment_id')
1ctl doctor --deployment-id "$DEPLOYMENT_ID" --health-path /health --smoke

Verify the reserved hostname resolves to its expected target:

1ctl -o json app status my-api | jq -e \
  '.domain_status.dns.condition.status == "verified"'

Only verified proves DNS observation succeeded. pending, nxdomain, wrong_target, and error are failures or incomplete states. Evaluate route and application readiness separately.

List running applications:

1ctl -o json app list | \
  jq -r '.[] | select(.status == "ready") | .app_label'

Build a name/status table:

1ctl -o json app list | jq '[.[] | {name: .app_label, status}]'

Look up a deployment ID:

DEPLOYMENT_ID=$(1ctl -o json app list | \
  jq -r '.[] | select(.app_label == "my-api") | .deployment_id')
test -n "$DEPLOYMENT_ID"
test "$DEPLOYMENT_ID" != null

Secrets

Secret values must never be used as script output. Treat secret list as group metadata only; do not rely on it to prove that a particular key reached a pod. Verify application behavior instead, or use an operator-controlled key-presence check that never prints the value.

Exit codes

Check both the process exit code and the response fields needed by your script. Validate required identifiers before invocation; some command paths currently display help without returning a non-zero status when an identifier is omitted.

jq is not bundled with 1ctl. Install it separately before using these examples.