CLI Overview - Ekanos SDK

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.

npx @ekanos/cli init --slug my-integration --yes
npx @ekanos/cli validate
npx @ekanos/cli test
npx @ekanos/cli dev

Install

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:

{
  "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:

{
  "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:

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.
ekanos upgrade — Resolves a coherent version set, installs, verifies with validate + the test script, and rolls back automatically on failure.
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 for details.

What’s next

Commands — Detailed reference for each verb
ekanos.json — Configuration reference
Authentication — Auth flow and credential storage
Publishing — Publish target verification
Exit codes — Exit code taxonomy

​Install

​Verbs at a glance

​Global flags

​JSON-first design

​Toolchain updates

​What’s next