The leaf CLI provides complete machine-readable output across commands via the global --json flag.

Formatting principles

When --json is enabled:

1. Newline-delimited JSON: Output is streamed as independent JSON objects separated by newlines.
2. Schema version: Every JSON object includes "schema": 1 at its root.
3. List items: Collections such as sites, keys, sessions, and deploys print one object per item with "type": "<name>" and "data": { ... }. Empty lists print one object with an empty data array.
4. Errors: When a command fails, an error object is output: {"schema": 1, "error": "<message>"}.

Output shapes

Version (leaf --version --json)

{
  "schema": 1,
  "version": "0.1.0"
}

Dry run deploy (leaf deploy --dry-run --json)

{
  "schema": 1,
  "type": "dry_run",
  "data": {
    "framework": "Astro",
    "package_manager": "npm",
    "build": ["npm", "run", "build"],
    "output_dir": "dist",
    "files": 3,
    "bytes": 1716
  }
}

Sites list (leaf sites list --json)

{"schema":1,"type":"sites","data":{"name":"my-cool-project","url":"https://my-cool-project.leafcloud.app"}}
{"schema":1,"type":"sites","data":{"name":"portfolio","url":"https://portfolio.leafcloud.app"}}

Keys list (leaf keys list --json)

{"schema":1,"type":"keys","data":{"id":"key_82f1b0a","name":"github-actions-ci","scopes":["deploy"]}}

Sessions list (leaf sessions --json)

{"schema":1,"type":"sessions","data":{"id":"ses_9a0b1c2","name":"leaf on workstation","kind":"cli"}}

Deploy history (leaf deploys --site my-cool-project --json)

{"schema":1,"type":"deploys","data":{"created_at":1792723212,"deploy_id":"dep_01ha82f91m","status":"live","error":null}}
{"schema":1,"type":"deploys","data":{"created_at":1792696504,"deploy_id":"dep_01ha7x90qp","status":"superseded","error":null}}

Usage (leaf usage --json)

{
  "schema": 1,
  "sites": 2,
  "storage_bytes": 1482010,
  "storage_limit": 1073741824,
  "deploys_today": 5
}

Errors

When an error occurs:

{
  "schema": 1,
  "error": "Next.js must set output: 'export' to deploy as a static site"
}

Exit codes

Exit Code	Meaning	Example
0	Success	Command executed without errors.
1	CLI argument / usage error	Missing required flags, or invalid arguments.
2	Authentication / authorization error	Not logged in, expired session, or missing permissions.
3	Framework / build / file system error	Build command failure, invalid leaf.toml, or missing output directory.
4	API communication error	Network issue or unexpected API failure.