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 public callback URL for a local app? Start the app yourself, then run npx @onkeiki/cli dev --port 8787. Install cloudflared first, or use --provider ngrok with your ngrok configuration. The foreground process prints the public origin and KEIKI_CALLBACK_URL=…; Ctrl+C stops the tunnel. Use --timeout 90s if the provider needs longer to start.

Development tunnels

npx @onkeiki/cli dev --port 8787
npx @onkeiki/cli dev --port 3000 --provider ngrok

This exposes the entire local port publicly. Keep authentication and webhook signature verification enabled. The CLI needs no Keiki login or API key, does not start or stop your app, and does not edit env files or change an agent's harness, dispatch mode, credentials, or routing. This makes it safe for callbacks of a cloud-served agent, not just external-harness dispatch.

Copy the printed origin into the application's callback configuration. For Zero, set KEIKI_CALLBACK_URL without changing browser OAuth/localhost URLs. Restart the application server after editing env files; a running Worker may still hold the previous values. Other apps may use their own callback variable. Quick-tunnel URLs are temporary and may change on the next run. Remote phones also need a public frontend URL for browser login; tunneling only the backend does not expose the frontend.

For an external-harness app, explicitly set its full dispatch URL in the agent dashboard. For a detached supervisor that updates that URL automatically, use the external-harness tunnel supervisor. keiki dev intentionally never switches a hosted agent into external-harness mode.

The provider must be installed separately. Its child process receives only OS, proxy/certificate configuration and, for ngrok, NGROK_AUTHTOKEN; app database, model and Keiki credentials are not inherited. A proxy variable that embeds credentials (user:password@host) is withheld with a warning; configure the provider's own proxy settings instead. Provider logs go to stderr and the ngrok token is redacted. Ctrl+C or a failed startup stops the provider and any helper processes it spawned.

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