JSON & Automation

The CLI is built to be scripted. Pass --json for machine-readable output, drive it from CI with a token, and discover any command’s schema at runtime.

The other reader of this output is an AI coding agent — deploying from Claude Code shows the JSON log commands it runs to check a deploy.

--json everywhere

Add --json to any command for structured output. The CLI also switches to JSON automatically when stdout isn’t a TTY.

lizard ps --json
lizard secrets list --json
lizard metrics --json

Streaming commands

For streaming commands (lizard up without --detach), --json emits one JSON object per line:

{ "event": "log", "line": "Step 1/8 : FROM node:20" }
{ "event": "log", "line": "..." }
{ "event": "deployed", "status": "running", "url": "https://app.onlizard.com" }

The build stream ends with done or error. Without --ci, lizard up then emits a final deployed, failed, or deploying event with status. Only deployed carries url (which may be null).

logs --json is a snapshot, not a stream

lizard logs --json returns the last 200 lines (override with --tail N, max 1000) and exits. Don’t wait on it expecting more output. For a specific incident, use --restart latest or --restart <id>.

Schema discovery

Dump any command’s exact arguments, options, and exit codes:

lizard --help --json                 # whole tree + global flags + exit codes
lizard service set --help --json     # one command

The response shape is { cli, version, agents, command: { arguments, options, subcommands }, globalOptions, exitCodes }. Because it’s generated from your installed binary, it always matches your version — prefer it over hard-coding flags.

CI / headless usage

Authenticate with a token and link the project explicitly (headless up won’t auto-create a project):

# Set LIZARD_TOKEN through your CI secret store.
lizard init --name my-project
lizard add --service api   # first run only; skip when the service exists
lizard up --ci --service api --detach

Check exit codes to branch your pipeline:

--wait makes redeploy wait for the build and for the new deploy to become ready. Without it, JSON mode exits 0 as soon as Lizard accepts the build request.

if lizard redeploy --service api --wait --json; then
  echo "Deploy succeeded"
else
  status=$?
  echo "Deploy failed with code $status" >&2
  lizard logs --build --json || true
  exit "$status"
fi

Updated October 9, 2026