> ## 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.

# CLI Overview

> Ekanos CLI scaffolds, validates, tests, and publishes Ekanos integrations from any Node project.

The **@ekanos/cli** is the Ekanos partner toolchain. It scaffolds, validates, tests, and publishes Ekanos integrations against the published `@ekanos` packages — from any Node project, with no bundler and no dependency on `@ekanos/sdk` at runtime.

```bash theme={null}
npx @ekanos/cli init --slug my-integration --yes
npx @ekanos/cli validate
npx @ekanos/cli test
npx @ekanos/cli dev
```

## Install

```bash theme={null}
npm i -g @ekanos/cli   # convenient — the `ekanos` binary is always on PATH
```

Inside a project, `validate`/`dev`/`publish`/`test` automatically delegate to **that project's own** pinned `@ekanos/cli` devDependency whenever it differs from the globally invoked binary — the same wrapper pattern as Gradle's `./gradlew` or `npx`. A partner with several integrations on different `@ekanos/sdk` versions gets the right toolchain per project without juggling installs.

Machine-level verbs (`init`, `login`, `logout`, `whoami`, `sources`, `use`, `status`, `upgrade`) never delegate — they always run on the binary you invoked. Set `EKANOS_NO_DELEGATE=1` to opt out for one invocation.

## Verbs at a glance

| Verb | What it does |
| - | - |
| **`init`** | Scaffold `ekanos.json`, a working `defineIntegration`, a test, tsconfig, vitest config, `.gitignore`, `package.json`, and agent-context files. |
| **`validate`** | Load the definition via esbuild and validate it with the real `@ekanos/integration-schema` zod schemas; run project integrity checks. |
| **`dev`** | Scaffold the local harness and run it with your Next.js, so widgets, tile, activation form, and triggers render in real Ekanos chrome. |
| **`test`** | Delegate to the project's own test script via its package manager. |
| **`login`** | Authenticate this machine against an Ekanos deployment (Auth0 device flow). |
| **`logout`** | Revoke the session at Auth0 and delete local credentials. |
| **`whoami`** | Print the identity the stored session authenticates as, plus a compact seats list. |
| **`status`** | Read the login state, project's `ekanos.json`, and its submissions on the host. |
| **`sources`** | List every Ekanos source you hold a developer or source-admin seat on. |
| **`use`** | Set this project's publish target to a source you hold a seat on. |
| **`publish`** | Validate, pack, and submit the integration to an Ekanos host. |
| **`upgrade`** | Move this toolchain to a coherent target version with verify-and-rollback. |

## Global flags

| Flag | What it does |
| - | - |
| **`--json`** | Force the JSON envelope on, even at a terminal. |
| **`--no-json`** | Force the human-readable form on, even when piped. |
| **`--version`** | Print the CLI version and exit 0. |
| **`--help`** | Print usage. Also available per-verb (`ekanos validate --help`). |

Short flags are not supported — the parser rejects them rather than guessing.

## JSON-first design

Every verb speaks JSON. JSON mode is **inferred** from:

* Non-TTY stdout (piped output)
* `CLAUDECODE=1` environment variable

An explicit `--json` or `--no-json` overrides that inference. In JSON mode, **stdout carries exactly one JSON object**:

```json theme={null}
{
  "ok": true,
  "data": { "...": "verb-specific data" }
}
```

A success envelope has no `error` key. An error envelope carries `error`, plus `data` only when the verb has something to report (for example `validate`'s findings). Every progress line goes to stderr. Errors always carry an imperative `hint` telling you what to do:

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "validation",
    "message": "5 validation findings.",
    "hint": "Resolve the error-severity findings in data.findings, then re-run \"ekanos validate\"."
  }
}
```

The CLI never prompts — with one deliberate exception: `publish` asks for a `y/N` confirm at a real terminal when the publish target is ambiguous (implicit source + multiple developer seats). Every other verb, and `publish` itself in JSON/non-TTY mode or with an explicit `--source`, never prompts.

## Toolchain updates

Three independent defenses against a stale toolchain:

1. **Schema-skew gate** — `validate` and `publish` fail fast with `precondition_failed` (exit 9) if the project resolves a newer `@ekanos/integration-schema` than the CLI bundles.

2. **`ekanos upgrade`** — Resolves a coherent version set, installs, verifies with `validate` + the test script, and rolls back automatically on failure.

3. **Update notice** — `validate`, `dev`, `publish`, and `status` check (24h cache, 1.5s timeout) whether a newer CLI exists. Human mode gets a stderr line; JSON mode carries `data.toolchain` in the envelope. Set `EKANOS_NO_UPDATE_CHECK=1` to disable it.

See [Keeping the toolchain current](/cli/updating) for details.

## What's next

* **[Commands](/cli/commands)** — Detailed reference for each verb
* **[ekanos.json](/cli/ekanos-json)** — Configuration reference
* **[Authentication](/cli/authentication)** — Auth flow and credential storage
* **[Publishing](/cli/publishing)** — Publish target verification
* **[Exit codes](/cli/json-output-and-exit-codes)** — Exit code taxonomy


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