JSON output

Every Kalup command takes --json. With it, the command prints exactly one JSON document, envelope/1, to stdout and nothing else. Scripts, CI jobs and AI agents should always use it: the shape is versioned and fixed, while the human text may change.

The envelope

{
  "format": "envelope/1",
  "ok": true,
  "data": { "valid": true, "counts": { "errors": 0, "warnings": 0 } },
  "issues": []
}

Issues

Every error and warning is one issue:

{
  "code": "E_UNKNOWN_TARGET",
  "message": "target 'staging' is not declared",
  "file": "kalup.config.ts",
  "line": 9,
  "configPath": "targets",
  "fix": "use one of sandbox, production, or declare targets.staging",
  "docs": "errors/E_UNKNOWN_TARGET.md"
}

Warnings ride in issues even when ok is true. Tell them apart by the W_ prefix on code. status, plan and snapshot also keep an E_SCOPE there when a list answered 403: they record the gap, mark what was not read, and still exit 0. An issue on an ok: true envelope never stopped the command.

Where human text goes

--help and --version follow the same rule: with --json they are envelopes too, with data.usage and data.name, data.version, data.disclaimer and data.formats, the document formats this version reads and writes (ir/1, plan/1, kalup.state/1, envelope/1, blueprint/1, blueprints-lock/1), so a tool can check before it relies on one.

What data holds

Each command page documents its data in full.

Pull changes

Each entry of changes[] has a kind and an address, and field when it is one field of the resource, such as label or options[paused].label. kind is one of:

added, changed, missing, local-only, excluded, shadowed, removed, removed-group, kept, conflict, removed-in-hubspot, ignored, override-group

Where a change has before and after, before is the file's value and after the portal's. A changed value takes after; kept, conflict, removed-group and override-group keep before.

When ok is false, data may still be present. validate always returns its verdict, status returns every target's checks even when one of them failed, and init keeps its result when only the first pull failed. After an incomplete read (E_INCOMPLETE, exit 1), pull and pull --discover keep data, which covers only the lists they read, and compare keeps the whole comparison with complete: false. apply keeps its data once a run began, whatever the exit, and omits it when a check refused the plan before the run began. ir and fmt omit data on failure, and so does pull on any other failure.

Parsing it robustly

1. Read stdout as a whole and parse it as one JSON document. Do not read it line by line.
2. Check format === "envelope/1" before you trust the rest.
3. Branch on the process exit code first, then on ok. The exit code tells you what kind of outcome it is; ok alone cannot tell "invalid config" from "a person is needed".
4. Match issues on code, never on message.
5. Ignore fields you do not know. New optional fields may appear inside envelope/1.

A small example in Node:

import { execFileSync } from 'node:child_process'

function kalup(args: string[]) {
  try {
    const stdout = execFileSync('npx', ['kalup', ...args, '--json'], { encoding: 'utf8' })
    return { exitCode: 0, envelope: JSON.parse(stdout) }
  } catch (error) {
    // a non-zero exit still printed an envelope on stdout
    const e = error as { status: number; stdout: string }
    return { exitCode: e.status, envelope: JSON.parse(e.stdout) }
  }
}

const { exitCode, envelope } = kalup(['validate'])
if (exitCode === 3) {
  for (const issue of envelope.issues) console.log(`${issue.file}:${issue.line} ${issue.code} ${issue.fix ?? ''}`)
}

In a shell, with jq:

npx kalup validate --json | jq -r '.issues[] | select(.code | startswith("E_")) | "\(.file):\(.line) \(.code)"'

What it never contains

No envelope carries a key or a token, including in error messages: only the name of the variable a key is read from.

Text that came from a portal is treated as data. In human text (messages, fixes, plan titles, the text output) and in pull's change lines it is stripped of control characters and newlines and capped in length. The structured values of a plan, a comparison and a snapshot keep it exactly, so nothing is lost. Instead, every JSON document Kalup prints or writes escapes U+007F to U+009F, U+2028 and U+2029 as \uXXXX, on top of JSON's own escaping, so no control sequence reaches a terminal raw. See Network and safety.