JSON Output & Exit Codes

JSON Envelope Format

In JSON mode, stdout carries exactly one JSON object. Every progress line goes to stderr.

Success envelope

{
  "ok": true,
  "data": {
    "slug": "my-integration",
    "integrations": [
      { "slug": "my-integration", "entry": "src/integration.ts" }
    ],
    "findings": []
  }
}

boolean

true on success, false on error.

object

Verb-specific result data. Always present on success; present on an error only when the verb has something to report (for example, findings).

object

Error details (code, message, hint). Present only on error — a success envelope has no error key.

Error envelope

{
  "ok": false,
  "data": {
    "slug": "my-integration",
    "integrations": [
      { "slug": "my-integration", "entry": "src/integration.ts" }
    ],
    "findings": [
      {
        "check": "definition.schema",
        "severity": "error",
        "file": "/path/to/src/integration.ts",
        "message": "version: version must be semver (\"1.0.0\", optionally with a prerelease/build suffix) — promotion diffs definitions by it.",
        "hint": "Correct the value at \"version\" so it satisfies @ekanos/integration-schema's IntegrationDefinitionSchema, then re-run validate."
      }
    ]
  },
  "error": {
    "code": "validation",
    "message": "1 validation finding.",
    "hint": "Resolve the error-severity findings in data.findings, then re-run \"ekanos validate\"."
  }
}

string

Stable error code (e.g., "validation", "forbidden", "auth_required"). Machine-readable; branch on this.

string

Human-readable error message.

string

Imperative next action. Always present and never empty.

In human mode, an error prints Error: <message> and Hint: <hint> to stderr.

Toolchain update notice

validate, dev, publish, and status check (24h cache, 1.5s timeout) whether a newer @ekanos/cli exists. When this CLI is not current, data carries an optional toolchain field:

{
  "status": "behind",
  "current": { "cli": "0.3.2" },
  "target": {
    "cli": "0.3.3",
    "sdk": "…",
    "ui": "…",
    "integrationSchema": "…",
    "harness": "…"
  },
  "upgradeCommand": "ekanos upgrade"
}

Status values:

"behind" — A newer version is available
"unsupported" — Your version is below the host’s declared minimum (makes publish fail with exit 9)

The field is absent when the CLI is current, when the check cannot resolve, or when disabled with EKANOS_NO_UPDATE_CHECK=1.

Exit Code Taxonomy

This is a frozen public contract. Exit codes never change meaning once shipped; new conditions get new numbers.

Exit	Code	Meaning	Example
0	—	Success	`validate` with no error-severity findings, `login` successful
1	`internal`	Unexpected internal error — a CLI bug, not user input	An unexpected thrown exception
2	`usage`	Usage error — unknown flag or command, missing required argument	`ekanos validate --typo-flag`, `ekanos use` without a slug, no host resolvable
3	`validation`	Validation failed	`validate` error-severity findings, ambiguous publish target without `--yes`, no source for `publish`
4	`auth_required`	Authentication is required but absent	No stored session, expired session that couldn’t be renewed, revoked token
5	`forbidden`	Authenticated, but not permitted	Publishing to (or `use`-ing) a source you don’t hold a seat on
6	`not_found`	A named resource was not found	No `ekanos.json`, an `entry` file that doesn’t exist, an unknown source slug on the host
7	`invalid_state`	Cannot run in current state	`.ekanos/harness` exists but wasn’t generated by `dev`, a version already submitted, a symlinked write target
8	`network`	A network operation failed	Host unreachable, server error, toolchain target unresolvable
9	`precondition_failed`	A required tool, config, or file is missing or invalid	`@ekanos/harness` not installed, invalid `ekanos.json`, `package.json` not ESM, schema version skew
10	`gate_failed`	A gate rejected the submission	`publish` refused on error-severity findings, `status --watch` on a `rejected` version

Codes outside the taxonomy

Three verbs pass a child process’s exit code straight through, with their own error.code:

Verb	`error.code`	Exit code
`test`	`test_failed`	The test runner’s
`dev`	`dev_server_failed`	Next’s
`upgrade`	`upgrade_install_failed` / `upgrade_validate_failed` / `upgrade_test_failed`	`9` / `3` / the test script’s

Branching on exit codes

0 — Proceed
1 — A CLI bug; report it with the --json envelope
2 — Fix the command (spelling, required arguments, --host)
3 — Fix the definition or resolve the ambiguity the hint names
4 — Run ekanos login and retry
5 — Check ekanos sources for the seats you hold
6 — Check the path or slug the message names
7 — Resolve the state the hint names (for a duplicate version, bump version in package.json)
8 — Retry with backoff; do not log in again
9 — Install or fix what the hint names
10 — Fix the findings in data.findings, then publish again

Command-specific exit codes

Not every verb emits every code:

init: 0, 1, 2, 7
validate: 0, 1, 2, 3, 6, 9
dev: 0, 1, 2, 6, 7, 9, or Next’s exit code
test: 6 or 9 if the project can’t be loaded; otherwise the runner’s exit code
login: 0, 1, 2, 4, 8, 9
logout: 0, 1, 2, 9
whoami: 0, 1, 2, 4, 8, 9
sources: 0, 1, 2, 4, 8, 9
use: 0, 1, 2, 4, 5, 6, 8, 9
status: 0 whenever the report is assembled; host errors still map through the taxonomy. With --watch: 0 on gated/dev, 10 on rejected, 4 without a session, 9 without a project or source
publish: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
upgrade: 0, 1, 2, 3, 6, 8, 9, or the test script’s exit code

Detailed error codes

`auth_required` (exit 4)

Returned by whoami, sources, use, publish, and status --watch when no session exists or it cannot be renewed, and by login when the code expires or the request is denied in the browser. Plain status reports authenticated: false instead of failing. What to do: Run ekanos login (with --host if you have multiple deployments).

`forbidden` (exit 5)

Returned by:

publish when you lack a seat on the target source
use when the slug doesn’t name a source you hold a seat on

What to do: Run ekanos sources to see what you have access to. The hint always lists your actual seats.

`precondition_failed` (exit 9)

Returned by:

validate, publish when the project resolves a newer @ekanos/integration-schema than the CLI bundles
validate, dev, test, use, publish, and upgrade when package.json does not declare "type": "module", or when ekanos.json is not valid JSON or fails its schema
dev when a required package is missing, @ekanos/harness declares no version, or the CLI and harness shell contracts don’t match
publish when the host has declared this CLI version unsupported
status --watch when there is no project or no source

What to do: Check the hint — it is specific about what’s missing or misconfigured. Common fixes:

# Install the harness dependencies
pnpm add -D @ekanos/harness next react react-dom tailwindcss @tailwindcss/postcss

# Set package.json to ESM
npm pkg set type=module

# Fix schema skew
ekanos upgrade

`validation` (exit 3)

Returned by:

validate when error-severity findings are present
publish when no source is given, the target is ambiguous without --yes, the confirm is declined, the archive exceeds 4 MiB, or the host rejects the submission as invalid
upgrade when run non-interactively without --yes, or when the confirm is declined

For validate, see data.findings[]. Each finding has:

check — The rule that produced it (e.g., "definition.schema", "project.slug-agreement", "collision.widget-id")
severity — "error", "warn", or "info"
message — The problem
hint — How to fix it
file, line — Where, when known

What to do: Read the hint and fix the integration. Run ekanos validate again.

`gate_failed` (exit 10)

Returned by:

publish when the local findings pass has error-severity findings (the same findings validate reports, plus escalated project.host-compiler-rules). Nothing is uploaded
status --watch when the host’s gate rejects the submitted version

Both carry the findings in data.findings. What to do: Fix the findings, bump the version if it was already submitted, and publish again. Use ekanos status --findings to see a rejected version’s findings.

Practical examples

Agent workflow

# Check if logged in
ekanos whoami
# Exit 0: authenticated
# Exit 4: run `ekanos login`, then retry

# Find the source to publish to
ekanos sources

# Publish explicitly to avoid ambiguity
ekanos publish --source my-source
# Exit 0: submitted
# Exit 5: no seat on that source — run `ekanos sources`
# Exit 7: this version is already submitted — bump package.json "version"
# Exit 9: toolchain or project issue — read the hint
# Exit 10: error-severity findings — see data.findings

# Wait for the gate verdict
ekanos status --watch
# Exit 0: gated or dev
# Exit 10: rejected — see data.findings

CI/CD pipeline

set -e  # Stop on the first failing command

ekanos validate
ekanos test

# Explicit source: no ambiguity, no prompt
ekanos publish --source "$SOURCE_SLUG"
ekanos status --watch

​JSON Envelope Format

​Success envelope

​Error envelope

​Toolchain update notice

​Exit Code Taxonomy

​Codes outside the taxonomy

​Branching on exit codes

​Command-specific exit codes

​Detailed error codes

​auth_required (exit 4)

​forbidden (exit 5)

​precondition_failed (exit 9)

​validation (exit 3)

​gate_failed (exit 10)

​Practical examples

​Agent workflow

​CI/CD pipeline

JSON Envelope Format

Success envelope

Error envelope

Toolchain update notice

Exit Code Taxonomy

Codes outside the taxonomy

Branching on exit codes

Command-specific exit codes

Detailed error codes

`auth_required` (exit 4)

`forbidden` (exit 5)

`precondition_failed` (exit 9)

`validation` (exit 3)

`gate_failed` (exit 10)

Practical examples

Agent workflow

CI/CD pipeline