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

# Quickstart

> Zero to a running integration in minutes using the Ekanos CLI

# Quickstart

Create your first Ekanos integration and run it in the local dev harness.

<Steps>
  ### Install the CLI

  ```bash theme={null}
  npm i -g @ekanos/cli@latest
  ekanos --version   # 0.3.3 or later
  ```

  Or use it without installing:

  ```bash theme={null}
  npx @ekanos/cli --version
  ```

  Inside a project, `validate`, `dev`, `publish` and `test` automatically delegate to that project's own pinned `@ekanos/cli` devDependency when it differs from the global binary. Set `EKANOS_NO_DELEGATE=1` to opt out for one invocation.

  ### Scaffold a new integration

  ```bash theme={null}
  ekanos init --slug my-integration --yes
  cd my-integration
  ```

  `init` never prompts for the slug — `--slug` is required. It scaffolds into `./<slug>`; pass `--dir .` to scaffold in place. It creates:

  * `ekanos.json` — `{ "slug": "my-integration", "entry": "src/integration.ts" }`
  * `src/integration.ts` — a working `defineIntegration()` call, plus `src/integration.test.ts`
  * `package.json` pinning `@ekanos/sdk`, `@ekanos/ui` and `@ekanos/harness` to `^0.4.0` and `@ekanos/cli` to `^0.3.3`, plus the peers the harness needs, including `next-intl` (`^4.14.7`) for `<Trans>`
  * `pnpm-workspace.yaml` approving `esbuild`'s build script (`allowBuilds: { esbuild: true }`). pnpm 10+ refuses to run dependency build scripts it has not been told to allow; without this file every `ekanos dev` / `ekanos test` fails with `ERR_PNPM_IGNORED_BUILDS`. npm and yarn ignore the file.
  * `tsconfig.json`, `vitest.config.ts`, `.gitignore`, and a pre-commit hook script wired through the `prepare` script
  * Agent-context files: `AGENTS.md` (the authoring contract, including `signature.scheme` for webhooks and the actions surface), `CLAUDE.md`, Claude Code skills under `.claude/skills/` (`ekanos`, `build-integration`, `polish-widgets`), `docs/api-notes.md`, and `.mcp.json`

  ### Install dependencies

  ```bash theme={null}
  pnpm install
  ```

  (or `npm install` / `yarn install` — the scaffold is agnostic)

  Install before the next step: `ekanos init` does not install anything, and `ekanos dev` stops with `precondition_failed` if the harness's packages are missing.

  ### Start the dev harness

  ```bash theme={null}
  ekanos dev --start
  ```

  `ekanos dev` first materializes the harness (`harness.config.ts` plus the generated shell under `.ekanos/harness/`), then runs it with your own Next. In an interactive terminal a bare `ekanos dev` also starts the server. When output is JSON (`--json`, a pipe, or `CLAUDECODE=1`), which is the case for coding agents and scripts, a bare `ekanos dev` only materializes the harness and returns; the result's `data.server` carries `{ started: false, command, url, port }` so the caller can start it. `--start` starts the server in every mode, so use it in docs, scripts and agent sessions. `--no-start` materializes only, even in a terminal.

  The first run also writes `harness.config.ts` — the harness registry you own and edit — and generates the shell under `.ekanos/harness/`. The harness serves on `http://localhost:3100` by default (`--port` changes it). Each integration gets these surfaces:

  * **Widgets** — your widgets in the real dashboard grid, plus a single-widget page
  * **Tile** — the marketplace card users see before connecting
  * **Activation** — the connection form
  * **Triggers** — your declared webhooks and schedules, run locally

  ### Edit and iterate

  The scaffolded `src/integration.ts` declares:

  * A `capabilities` and a `permissions` entry
  * One widget, `my-integration-hello`, rendered by a small component in the same file
  * One tool, `get_greeting`
  * A commented-out example `actions['create-record']` declaration

  Try:

  1. **Change the widget name** — Edit `name` in the widget declaration
  2. **Add a tool** — Copy `get_greeting` and give it a new snake\_case name
  3. **Add storage** — Declare a key such as `'settings/location'` under `storage.account`

  `defineIntegration()` validates at import time and throws a remediation message for an invalid declaration.

  ### Validate your integration

  ```bash theme={null}
  ekanos validate
  ```

  This loads your definition and checks it with the real `@ekanos/integration-schema` schemas:

  * Definition structure — the schema is strict, so unknown keys are errors
  * Naming rules (slugs, widget ids, tool names, webhook/schedule/action names, storage keys)
  * Cron syntax and OAuth endpoint egress coverage (the checks `defineIntegration()` runs)
  * Collisions across multiple integrations declared in one `ekanos.json`
  * Project checks: the `ekanos.json` slug agrees with the definition, the vitest config inlines `@ekanos/sdk`, and `tsconfig.json` sets the host's compiler rules (`strict`, `noUncheckedIndexedAccess` — a warning)
  * Advisory checks such as `icons/pro-only`

  Exit code `0` means no error-severity findings; `3` means there are some.

  ### Test locally

  ```bash theme={null}
  ekanos test
  ```

  This runs your project's own `test` script through its package manager.

  `@ekanos/sdk/testing` provides:

  * `createMockContext()` — an in-memory capability context for handlers
  * `invokeWebhook()` — run a webhook handler against a definition-derived context
  * `invokeSchedule()` — run a schedule handler the same way
  * `invokeActivate()` — run the `onActivate` hook
  * `createMockFetchProvider()` — a fixture-backed fetch provider for widget tests

  See the [SDK overview](/sdk/overview) for testing examples.

  ### Authenticate (for publishing)

  ```bash theme={null}
  ekanos login --host https://your-ekanos-host
  ekanos whoami
  ```

  `login` uses a browser device flow (Auth0): it prints a code and URL, you approve in a browser, and the session is stored on this machine.

  ### Publish your integration

  ```bash theme={null}
  ekanos sources          # List sources you hold a seat on
  ekanos use my-source    # Set this project's publish target
  ekanos publish          # Validate, pack, and submit
  ```

  `publish`:

  1. Runs the same findings pass as `ekanos validate`, and refuses to submit (`gate_failed`, exit 10) on any error-severity finding
  2. Packs `ekanos.json`, `package.json`, `README.md`, `src/**`, and your root `tsconfig*.json` and vitest/vite config
  3. Submits the archive to the Ekanos host, where the submission gate runs its checks

  `publish` does not run your tests locally and does not wait for the gate. Watch the verdict with:

  ```bash theme={null}
  ekanos status --watch
  ```
</Steps>

## Next steps

* **Learn the structure** — Read [How integrations are structured](/concepts/structure)
* **Build a widget** — See [Widgets](/sdk/surfaces/widgets) for the `Widget` compound API
* **Call an API** — Use `ctx.fetch` in handlers to reach your provider's API
* **Add OAuth** — See [OAuth](/sdk/surfaces/oauth)
* **Fix errors** — Check [Common errors](/troubleshooting/common-errors)

## Common issues

<Note>
  **`ERR_PNPM_IGNORED_BUILDS` on `ekanos dev` or `ekanos test`** — The project
  has no `pnpm-workspace.yaml` approving `esbuild`'s build script (projects
  scaffolded before CLI 0.3.3). Create `pnpm-workspace.yaml` containing
  `allowBuilds: { esbuild: true }` (or add that key to the existing file), then
  run `pnpm install` again.
</Note>

<Note>
  **`ekanos dev` fails its precondition check** — Run `pnpm install` after
  scaffolding. The harness needs the scaffolded devDependencies
  (`@ekanos/harness`, `next`, `tailwindcss`, `@tailwindcss/postcss`) installed.
</Note>

<Tip>
  **The CLI is behind** — Update the global binary with `npm i -g
      @ekanos/cli@latest`. Run `ekanos upgrade --check` to compare current and
  target versions (read-only), then `ekanos upgrade` to move the project's
  toolchain, verifying and rolling back automatically on failure. On 0.x semver
  `^0.3.0` excludes 0.4.0, so a project scaffolded by an older CLI needs `ekanos
      upgrade` to reach `@ekanos/sdk`, `@ekanos/ui` and `@ekanos/harness` 0.4.0.
</Tip>

## Commands reference

| Command | What it does |
| - | - |
| `ekanos init --slug <name>` | Scaffold a new integration |
| `ekanos dev --start` | Start the dev harness (port 3100 by default) |
| `ekanos validate` | Check your integration for errors |
| `ekanos test` | Run your project's test script |
| `ekanos login --host <url>` | Authenticate for publishing |
| `ekanos publish` | Validate, pack, and submit your integration |
| `ekanos status` | Show login state and this project's submissions |

See the [CLI docs](/cli/overview) for the full command reference.


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