Skip to main content
The ekanos.json file declares your integration’s entry point and publishing target.

​
Single-integration project

​
Multi-integration project

Declare one form or the other, never both. validate cross-checks multiple integrations for colliding slugs, widget ids, and tool names.

​
All fields

​
string
required
Kebab-case identifier (e.g., "my-integration"). Must match the definition’s slug field. Only used in the single-integration form.
​
string
required
Path to the module exporting your defineIntegration(...) result (default export, or any named export that is an object with a string slug field). Only used in the single-integration form.
​
array
required
Array of { slug, entry } objects for multi-integration projects. Each slug must be unique, and each entry must export a definition with a matching slug. Only used in the list form.
​
string[]
Extra Tailwind @source globs to include in the dev harness. Project-relative, no .. allowed, restricted character set (validated strictly since they’re written verbatim into generated CSS).Top level only — not per-integration, because Tailwind scans one content set for the whole shell.
The harness already points at: src/, app/, lib/, components/, integrations/, packages/. Add globs here only for integration sources outside those locations.
​
string
Ekanos source slug this project publishes to (e.g., "my-source"). Written by ekanos use and by every successful publish whose source differs. Read by publish when no --source flag is passed, and by status to list the project’s submissions.
​
string
Ekanos host origin (e.g., "https://your-ekanos-host"). Written by a successful publish or ekanos use only when the field is absent — an existing host is never overwritten. Read by every host-taking verb except login (see Authentication).
​
string
Ignored — provided for editor tooling only.
​
string[]
One or more http(s) URLs or project-relative paths to the target API’s documentation. Created by ekanos init --docs if provided, but you can add or edit this field anytime.Optional. URLs are never fetched; a project-relative path that doesn’t exist produces a docs/missing-file warning from validate.

​
Slug consistency

The slug in ekanos.json must equal the slug in the definition it points at. If they disagree, validate reports a project.slug-agreement error naming both values.

​
Strictness

The file is strict: an unrecognised key is an error naming the key, not a silent no-op. Given:
every verb that loads the project fails with precondition_failed (exit 9):

​
Auto-generated fields

A successful publish writes source (and host, if absent) to ekanos.json. This lets later verbs find the same deployment without needing flags:
ekanos use <slug> also writes source, and optionally host if not already set.

​
Where it lives

ekanos.json lives at the root of your project directory — the current working directory, or --dir. validate, dev, test, use, publish, and upgrade require it and fail with not_found (exit 6) when it is missing; status and sources read it when present.

​
Troubleshooting

​
Unrecognized key

Check your field names against the reference above. Remember:
  • Single projects use slug + entry
  • Multi projects use integrations (array of objects)
  • Never mix both forms

​
Slug mismatch

validate reports ekanos.json declares slug "<a>" for this entry, but the definition says "<b>". Edit either ekanos.json or the definition so they agree.

​
Missing required fields

  • Single-integration projects must have slug and entry
  • Multi-integration projects must have integrations with at least one entry
  • entry must be a path, relative to the project, to a file that exists (otherwise not_found, exit 6)