@meissa_a/meissa-cli

Run Meissa Studio — an MCP connector dashboard + AI chat with generative UI — locally with a single command. No clone, no build, no manual .env setup.

npx @meissa_a/meissa-cli

That's it. The first run walks you through a one-time setup wizard, saves your answers, starts the app, and opens it in your browser.

Requirements

• Node.js >= 18
• An API key for your backing model provider — get one from your provider's web console under Settings → API Keys, or ask your administrator.

What you get

Meissa Studio is a chat app backed by your provider's models/agents/assistants, with:

• Generative UI — replies can render as interactive components (tables, forms, charts, buttons), not just markdown text.
• MCP servers — connect Model Context Protocol servers as real subprocesses; their tools are wired into the chat so the model can actually call them.
• Skills — install and run Claude-style skills from the dashboard.
• Sessions — chat history is saved locally and can be resumed or exported.
• Google Drive upload (optional) — let the chat save generated files straight to your Drive.

First run

Running npx @meissa_a/meissa-cli with no existing config launches a short wizard:

1. API key (required)
2. Base URL (optional — defaults to the standard provider endpoint)
3. Default namespace — one of assistants, agents, chat-models (default), or digital-workforce
4. Google Drive uploads (optional) — needs an OAuth Client ID/Secret from Google Cloud Console; skip and add later if you don't have one handy
5. Access password (optional) — protects the studio behind a password page. Recommended if you expose Meissa beyond localhost. Only a salted hash is stored — never the plaintext.

Your answers are saved to ~/.meissa/config.env (0600 permissions) so you're only asked once. Every later npx @meissa_a/meissa-cli reuses that config and starts straight into the app.

To redo the wizard (e.g. to rotate your API key):

npx @meissa_a/meissa-cli --reconfigure

Or hand-edit ~/.meissa/config.env directly — it's a plain KEY=value file.

Password protection

The wizard can set an optional access password. When one is set, opening Meissa shows a login page first, and a successful login is remembered for 7 days. Only a salted scrypt hash (MEISSA_PASSWORD_HASH) is stored — the plaintext never touches disk. Leaving it unset means no gate (the previous behavior).

To add, change, or remove the password after setup, run --reconfigure and answer the password step (leave it disabled to remove the gate). For a self-hosted deploy that reads a .env instead of the wizard, generate just the hash line to paste in:

npx @meissa_a/meissa-cli --set-password

Running it

• Meissa picks the first free port starting at 3000 and prints the URL, e.g. Meissa Studio is running at http://localhost:3000 — then opens it in your default browser.
• The server binds to 127.0.0.1 only, by design: it can spawn MCP subprocesses and install skills, so exposing it on your LAN would hand any other device on your network unauthenticated code execution. Set MEISSA_HOST=0.0.0.0 (or a specific interface) only on a trusted network if you need to reach it from another device.
• Chat sessions, artifacts, and other local data live under ~/.meissa/data — not inside the npm install directory, so they survive npm upgrading or reinstalling the package.
• Ctrl+C stops the server.

Configuration reference

All variables live in ~/.meissa/config.env:

| Var | Required | Notes | |-----|----------|-------| | ICA_API_KEY | yes | Your API key. | | ICA_BASE_URL | no | Defaults to the standard provider endpoint. | | ICA_DEFAULT_NAMESPACE | no | One of assistants, agents, chat-models, digital-workforce. Defaults to chat-models. | | GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET | no | Enables the optional Google Drive upload feature. | | GOOGLE_REDIRECT_URI | no | Set automatically from the port Meissa picks — you don't need to manage this by hand. | | MEISSA_PASSWORD_HASH | no | Salted scrypt hash of the access password. When present, the studio requires login. Set via the wizard or --set-password; leave unset for no gate. | | MEISSA_SESSION_SECRET | no | Optional key for signing login session cookies. Defaults to MEISSA_PASSWORD_HASH — so changing the password invalidates existing sessions. |

Environment overrides (set these in your shell, not the config file):

| Var | Default | Notes | |-----|---------|-------| | MEISSA_HOST | 127.0.0.1 | Interface to bind to. See the security note above before changing it. |

Troubleshooting

• "Could not find built server" — the install looks incomplete or corrupted; try npm uninstall -g @meissa_a/meissa-cli && npx @meissa_a/meissa-cli (or clear npx's cache) to reinstall cleanly.
• Wrong API key or namespace — run npx @meissa_a/meissa-cli --reconfigure, or edit ~/.meissa/config.env directly and restart.
• Port already in use — Meissa automatically tries the next port; check the printed URL rather than assuming 3000.

For contributors: how the package is built

The published package ships a pre-built Next.js standalone server, not source — bin/meissa.js spawns app/server.js at runtime. build.ts (run via npm run build / automatically on prepublishOnly):

1. Runs npm run build in apps/meissa-studio (Next.js output: "standalone").
2. Wipes and recreates ./app, then copies the standalone server, .next/static, and public/ into it.
3. Strips any .env* file from ./app before it can be packed.

That last step exists because of a real incident: Next's standalone output copies the source app's .env* files verbatim, and this package's "files": ["bin", "app"] in package.json ships whatever is in app/ regardless of .gitignore. Without the strip, every npm publish uploads the developer's real API key (ICA_API_KEY) and Google OAuth secret (if set) to the public registry. Runtime config for installed CLIs comes from ~/.meissa/config.env via bin/meissa.js, not a baked .env — so the app never needs one in the published package.

Pre-publish checklist

Before running npm publish, from this directory:

npm pack --dry-run

Check the output for:

• No .env* files in the listing (regression check on the secret-leak fix above).
• Unpacked/compressed size hasn't regressed. Baseline after the sharp/typescript exclusions and logo optimization in apps/meissa-studio/next.config.mjs: roughly 5-6MB compressed / 9-10MB unpacked. If a change balloons this back up, npm pack --dry-run's file listing will show which new file(s) got traced into app/ — check next.config.mjs's outputFileTracingExcludes and whether a new dependency should be added there.