Keiki CLI

The Keiki CLI connects a local app to an external-harness agent.

Install globally with npm install -g @onkeiki/cli to get the keiki command. Run it in your application directory:

npx @onkeiki/cli init

Install and sign in

The CLI installs a small platform-specific binary through npm's optional dependencies. It does not publish or modify your app until you run init.

npx @onkeiki/cli login
npx @onkeiki/cli whoami
npx @onkeiki/cli logout

login opens the Keiki consent page in your browser and starts a temporary loopback callback on 127.0.0.1. Approve access to the current organization. The CLI stores its public OAuth client ID and tokens in $XDG_CONFIG_HOME/keiki/credentials.json (usually ~/.config/keiki/credentials.json) with user-only permissions. Tokens are scoped to the platform URL. whoami displays the platform and organization; logout revokes the session and removes the local credentials.

When using SSH, forward the browser callback to the machine running the CLI, or open the printed authorization URL in a browser that can reach the CLI's loopback port. Use npx @onkeiki/cli login --no-browser to print the URL without launching a browser.

The platform defaults to https://onkeiki.com. Override it with --url, KEIKI_URL, or a url value in keiki.json, in that order.

Initialize an app

npx @onkeiki/cli init detects the framework from package.json dependencies:

• Eve writes agent/extensions/keiki.ts.
• Flue writes src/channels/keiki.ts when it can identify an agent module. Add the channel route and useKeiki() to the app and agent.
• AI SDK writes src/keiki.ts for Hono or Workers, or an App Router route (app/api/keiki/route.ts or src/app/api/keiki/route.ts) for Next.js. Hono and Workers need a manual route mount.

The CLI lists only external-harness agents. Choose one or create a new agent; new agents use the app's package name and the instructions you provide. It configures push delivery when you provide a public dispatch URL, retrieves a signing secret when needed, and writes it to .env, .env.local for Next.js, or .dev.vars for Workers. The env file is added to .gitignore when needed. Existing source files are never overwritten. keiki.json records the selected agent and framework.

If the app has a public URL, the CLI appends the framework's route path: /keiki/v1/dispatch for Eve, /channels/keiki/dispatch for Flue, /api/keiki for Next.js, or /keiki/turn for Hono and Workers. A blank URL leaves delivery unset; configure it later in the dashboard.

Flags

--url URL
--agent ID             Use an existing external-harness agent
--new                  Create a new agent
--name NAME            Name for a new agent
--prompt TEXT          Required system instructions for a new agent
--dispatch-url URL     Full dispatch URL, including its route path
--framework eve|flue|ai-sdk
--target nextjs|hono|workers
--rotate-secret        Rotate the signing secret
--skip-install         Do not install missing framework packages
--yes                  Accept defaults without prompting

Running npx @onkeiki/cli init again keeps the current signing secret, skips existing source files, and avoids duplicate .gitignore entries. A dispatch URL rejected by the platform is reported as a warning; finish the setup and configure a public URL later.

Rotating a signing secret immediately stops apps using the old value from verifying Keiki requests. The CLI does not rotate a configured secret on a rerun unless you pass --rotate-secret. Keep .env, .env.local, and .dev.vars out of version control.

Troubleshooting

• The app URL is rejected: use a public HTTPS URL or a tunnel. Localhost and private network destinations are not accepted by production.
• Consent does not return to the CLI over SSH: forward the callback port or use a browser on the same machine; the callback listens only on loopback.
• No framework is detected: install the framework package or pass --framework from an app directory with package.json.
• A secret is missing after setup: check the target-specific env file and configure the same KEIKI_SIGNING_SECRET in the app's runtime environment.
• Need a local dispatch tunnel? keiki dev is coming.

See the Eve, Flue, and AI SDK integration guides for runtime details.