@elu-labs/cli 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 ELU Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Third-party software bundled into dist/elu.mjs (undici, MIT; jsonc-parser,
+MIT) keeps its own license, reproduced in full at the end of that file.

package/README.md

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# @elu-labs/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Add ELU to your web app and connect your AI tools to ELU with one command.
+
+```sh
+npx -y @elu-labs/cli
+```
+
+On Windows PowerShell, use `npx.cmd -y @elu-labs/cli`. You need Node.js 18.17 or newer.
+
+## What it does
+
+1. Looks at the folder you run it in: the framework, any ELU tag already there, and the AI tools on this computer. It changes nothing yet.
+2. Shows you what it will do and asks once.
+3. Opens your browser to sign in to ELU. New to ELU? Sign up with your work email.
+4. Adds the ELU tag to your app.
+5. Writes an ELU key into the user config of Claude Code, Cursor and VS Code on this computer.
+6. Prints what changed and how to undo it.
+
+Session replay is on by default. You don't need to turn anything else on.
+
+## Commands
+
+| Command                               | What it does                                      |
+| ------------------------------------- | ------------------------------------------------- |
+| `npx -y @elu-labs/cli`                | Add ELU to this app, then connect your AI tools   |
+| `npx -y @elu-labs/cli web`            | Only add ELU to this app                          |
+| `npx -y @elu-labs/cli mcp`            | Only connect your AI tools                        |
+| `npx -y @elu-labs/cli mcp elu_live_…` | Connect your AI tools with a key you already have |
+
+## Options
+
+| Option         | What it does                                                          |
+| -------------- | --------------------------------------------------------------------- |
+| `-y`, `--yes`  | Go ahead without asking                                               |
+| `--no-web`     | Don't add ELU to the app                                              |
+| `--no-mcp`     | Don't connect AI tools                                                |
+| `--tools=LIST` | Only these tools: `claude`, `cursor`, `vscode`                        |
+| `--app=DIR`    | The app folder to use, for monorepos                                  |
+| `--paste`      | Sign in by pasting a code. SSH and containers use this automatically. |
+| `--reactivate` | Turn analytics back on if it was turned off                           |
+| `--json`       | Print one JSON result on stdout. Messages go to stderr.               |
+| `--version`    | Print the version                                                     |
+| `--help`       | Show help                                                             |
+
+| Environment variable                    | What it does                                                   |
+| --------------------------------------- | -------------------------------------------------------------- |
+| `ELU_API_KEY`                           | An `elu_live_` key. Connects AI tools without signing in.      |
+| `ELU_URL`                               | ELU address. The default is `https://elu.dev`.                 |
+| `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` | Your proxy. npm's `proxy` and `https-proxy` settings work too. |
+| `NODE_EXTRA_CA_CERTS`                   | Your company CA file. npm's `cafile` setting works too.        |
+| `NO_COLOR`                              | Turn colors off                                                |
+
+## Where it writes
+
+**Your app.** It adds one script tag to one file:
+
+| Framework            | File                                                               |
+| -------------------- | ------------------------------------------------------------------ |
+| Next.js App Router   | `app/layout.tsx` (or `src/app/…`)                                  |
+| Next.js Pages Router | `pages/_document.tsx`. It creates this file if you don't have one. |
+| Vite, plain HTML     | `index.html`                                                       |
+| Create React App     | `public/index.html`                                                |
+
+It never stages or commits anything. If your app already has an ELU tag, it leaves it alone. For any other framework, it prints the tag for you to add.
+
+**Your AI tools.** It writes the key into each tool's **user** config, never into your repo:
+
+| Tool        | Where                                                                                                                                   |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Claude Code | `claude mcp add --scope user` (stored in `~/.claude.json`)                                                                              |
+| Cursor      | `~/.cursor/mcp.json`                                                                                                                    |
+| VS Code     | Your user `mcp.json`: `~/Library/Application Support/Code/User` (macOS), `~/.config/Code/User` (Linux), `%APPDATA%\Code\User` (Windows) |
+
+Files that hold the key are readable only by you (mode 0600). Before it changes a file the first time, it saves a copy in `~/.config/elu/backups`. It also keeps a random device id in `~/.config/elu/device-id`, so each computer gets its own key.
+
+For Claude Desktop, add ELU under Settings → Connectors with `https://elu.dev/api/mcp`.
+
+Over SSH, in a container or in a Codespace, it only connects Claude Code. On your laptop, run `npx -y @elu-labs/cli mcp` for Cursor and VS Code.
+
+## Keys found in your repo
+
+An ELU key in a project file such as `.vscode/mcp.json`, `.cursor/mcp.json`, `.mcp.json` or `.windsurf/*.json` is never reused.
+
+- If git tracks that file, or the key is in your git history, the CLI revokes the key and removes the entry. Commit that change.
+- If git doesn't know about the file, the CLI removes the entry once the tool's user config has ELU.
+
+## Undo
+
+- **The tag.** The CLI prints the command for each file it changed. Inside git, run `git checkout -p <file>`. If it created the file, delete the file. Outside git, copy the backup back from the path it printed.
+- **AI tools.** Run `claude mcp remove elu --scope user`. Delete the `elu` entry from `~/.cursor/mcp.json` and from your VS Code user `mcp.json`.
+- **The key.** Revoke it in ELU under Settings → API & MCP. The CLI names each key `ELU CLI · <device> · <date>`.
+
+## Viewers
+
+If you are a Viewer in the organization, your key is read-only. The CLI says so when it connects your tools.
+
+## Local traffic
+
+Visits to your app on `localhost` count like any other traffic. To leave them out, go to Session Replays → Tuning → Filtered URLs and add `localhost`.
+
+## Agents and CI
+
+- When stdin or stdout isn't a terminal, the CLI never asks anything. It prints the plan and exits with code 2 unless you pass `--yes`. The sign-in link is the first line it prints, and it waits up to 9 minutes.
+- In CI it needs `ELU_API_KEY`. Without it, it exits with code 1.
+
+| Exit code | Meaning                                                                 |
+| --------- | ----------------------------------------------------------------------- |
+| 0         | Everything asked for is done, or skipped for a reason a rerun won't fix |
+| 1         | A step failed or was cancelled                                          |
+| 2         | It needs input: pass `--yes`, `--app=<dir>` or `--reactivate`           |
+
+## Upgrading from @elu-labs/mcp-setup
+
+`npx @elu-labs/mcp-setup` still works. It now runs this CLI's `mcp` command. The key argument, `ELU_API_KEY`, the prompt and the exit codes are the same. These things changed:
+
+- At the key prompt, you can press Enter to sign in with your browser instead of pasting a key.
+- VS Code gets ELU in your user `mcp.json`, not in `.vscode/mcp.json` in the current folder.
+- Claude Desktop is no longer written. Add ELU under Settings → Connectors instead.
+- Windsurf and Zed are no longer written.
+- Config files are edited in place, keeping comments. A file that isn't valid JSON is left alone instead of being replaced.
+- The key is never printed.
+
+## License
+
+MIT. The bundled third-party packages (undici and jsonc-parser, both MIT) keep their own licenses. Their full text is at the end of `dist/elu.mjs`.