CLI reference

Every chataway command and flag — init, dev, validate, pack, login, logout, publish, status — plus environment variables and where credentials live.

The chataway CLI ships with @chataway/apps. Scaffolded apps have it as a dependency, so npx chataway … (or the npm scripts) works inside an app folder.

npx chataway --help
npx chataway --version

Every command that takes [dir] defaults to the current folder. Exit code 0 means success, 1 means errors (validation errors, a rejected upload, a failed request).

#chataway init [dir]

Scaffolds a new app — the same as npx create-chataway-app [dir].

npx chataway init my-app --name "My App" --publisher acme --id com.acme.my-app --yes

Without --yes in a terminal, it asks for anything you didn't pass.

#chataway dev [dir]

Runs your app in the Chataway on this Mac, in developer mode. Needs Settings → Developer → Developer mode turned on in Chataway.

npx chataway dev

It:

1. validates the folder at dev level (store-only rules are warnings),
2. starts npm run server and npm run watch:ui if your package.json has them, and waits for your MCP server,
3. links the folder into Chataway (marked DEV), with package.json → chataway.devMcpUrl as a development override of remote.mcpUrl,
4. re-validates and re-links when plugin.json changes; Chataway reloads the app's runtime and panel on changes,
5. prints the App inspector feed (tool calls, cards, remote traffic, logs),
6. on Ctrl+C: unlinks the app and stops the child processes.

#chataway validate [dir]

Runs the checks locally — the same validator the store and the desktop installer use — on the files that would go into the bundle.

npx chataway validate           # dev level
npx chataway validate --store   # store level: what the store would accept

Each issue is printed with its path and code:

✖ remote.mcpUrl: remote.mcpUrl must be an https URL [remote.url]
⚠ bundle.readme: Add a README.md — it becomes the store description [bundle.readme]

#chataway pack [dir]

Builds the .chataway-app bundle and validates what's in the zip.

npx chataway pack
# ✔ Packed com.acme.my-app@1.0.0 → dist/com.acme.my-app-1.0.0.chataway-app
#     14 files · 212 KB · sha256 9c1f…

Only plugin.json, ui/, assets/, README.md, CHANGELOG.md and LICENSE go in; your server code, web/ sources and node_modules are left out. Build your panel first (npm run build) — the scaffold's npm run pack does both.

#chataway login

Signs you in to chataway.co with a device code and saves a developer token for publishing.

npx chataway login

  Open https://chataway.co/developers/activate and enter the code

      WDJB-MJHT

→ waiting for approval (expires in 10 min)…
✔ Signed in to https://chataway.co. Token saved to ~/.config/chataway/credentials.json (0600).

It opens the page in your browser; sign in there, check that the code matches, and approve.

#chataway logout

Forgets the saved token for the store (--store-url to pick another store). Revoke tokens themselves in the developer dashboard.

#chataway publish [dir]

Packs, validates at store level, and uploads the bundle for review.

npx chataway publish

→ Checking com.acme.my-app (14 files, 212 KB)
→ Uploading to https://chataway.co…

  com.acme.my-app@1.0.0  in_review
  Review: https://chataway.co/dashboard/developer/apps/com.acme.my-app
  Follow it with: chataway status com.acme.my-app 1.0.0

Nothing is uploaded if validation fails. The exit code is 1 when the store rejects the upload.

See Publishing for review states.

#chataway status [appId] [version]

Shows a version's review status, check issues and reviewer notes. Inside an app folder, appId and version default to the ones in plugin.json.

npx chataway status com.acme.my-app 1.0.0
npx chataway status --json

#Environment variables

#Publishing from CI

- run: npm ci
- run: npm run build
- run: npx chataway publish
  env:
    CHATAWAY_TOKEN: ${{ secrets.CHATAWAY_TOKEN }}

Create the token in the developer dashboard, store it as a CI secret, and bump version in plugin.json for every upload.