> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.ekanos.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# JSON Output & Exit Codes

> JSON envelope format and exit code taxonomy for the ekanos CLI.

## JSON Envelope Format

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

### Success envelope

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

<ResponseField name="ok" type="boolean">
  `true` on success, `false` on error.
</ResponseField>

<ResponseField name="data" type="object">
  Verb-specific result data. Always present on success; present on an error only
  when the verb has something to report (for example, findings).
</ResponseField>

<ResponseField name="error" type="object">
  Error details (`code`, `message`, `hint`). Present only on error — a success
  envelope has no `error` key.
</ResponseField>

### Error envelope

```json theme={null}
{
  "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\"."
  }
}
```

<ResponseField name="error.code" type="string">
  Stable error code (e.g., `"validation"`, `"forbidden"`, `"auth_required"`).
  Machine-readable; branch on this.
</ResponseField>

<ResponseField name="error.message" type="string">
  Human-readable error message.
</ResponseField>

<ResponseField name="error.hint" type="string">
  Imperative next action. Always present and never empty.
</ResponseField>

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:

```json theme={null}
{
  "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:

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
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
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.