oatbox CLI

Install the Oatbox widget in your web app with one command.

Quick start

# 1. Authorize the CLI (device-code flow, opens your dashboard)
npx oatbox@latest login

# 2. Link this project to a workspace (writes .oatbox/config.json)
npx oatbox@latest link

# 3. Inject the widget <script> into the right file
npx oatbox@latest init

login authorizes the CLI against https://app.oatbox.io and stores a key in ~/.oatbox/credentials.json. link fetches your workspaces/agents and writes the workspace client key to .oatbox/config.json. init then embeds the widget loader using that client key.

The embedded snippet loads the widget from the Oatbox CDN:

<script async src="https://cdn.oatbox.io/widget/loader.js" data-client-key="YOUR_CLIENT_KEY" data-mode="in-app"></script>

Single-agent (legacy) install

If you just want to embed one agent without logging in, pass its agent ID. This uses the legacy data-agent attribute and is kept for backward compatibility:

npx oatbox@latest init YOUR_AGENT_ID

Find the agent ID (and your client key) in your Oatbox dashboard at /admin/install.

What it does

1. Reads your package.json to detect your framework automatically.
2. Locates the right file (app/layout.tsx, index.html, nuxt.config.ts, etc.).
3. Inserts the Oatbox <script> tag idempotently — running it twice won't duplicate the tag.
4. Prints a confirmation with the file path changed.

Supported frameworks

| Framework | Target file edited | |------------|---------------------------| | Next.js | app/layout.tsx | | React | index.html / public/index.html | | Vue | index.html | | Nuxt | nuxt.config.ts | | Angular | src/index.html | | SvelteKit | src/app.html | | Svelte | index.html | | Plain HTML | index.html (auto-detected) |

Options

--widget-host=<url>   CDN host that serves the widget loader
                      (default: https://cdn.oatbox.io)
--origin=<url>        Oatbox API host used by login/link
                      (default: https://app.oatbox.io)
--dry-run             Preview changes without writing files
--force               Skip git-dirty check
--framework=<name>    Override framework detection

--widget-host controls the host in the embedded <script src="…/widget/loader.js">. --origin only affects the login/link API calls — the two are intentionally separate.

Examples

# Install using the linked workspace client key
npx oatbox@latest init

# Preview what would change
npx oatbox@latest init --dry-run

# Override framework detection
npx oatbox@latest init --framework=react

# Single-agent (legacy) install
npx oatbox@latest init cmnwd9d5w0000aw9kjolkro60

# Self-hosted widget CDN
npx oatbox@latest init --widget-host=https://cdn.my-oatbox.example

What this does NOT do

• Install or update npm dependencies
• Start your dev server
• Commit or push any changes to git
• Modify any file other than the single template/entry file listed above

Manual installation

If the CLI can't detect your setup, add this to your HTML <body> manually. Use your workspace client key:

<script async src="https://cdn.oatbox.io/widget/loader.js" data-client-key="YOUR_CLIENT_KEY" data-mode="in-app"></script>

To embed a single agent instead, use data-agent:

<script async src="https://cdn.oatbox.io/widget/loader.js" data-agent="YOUR_AGENT_ID"></script>

For Next.js, use the next/script component:

import Script from "next/script"

// Inside your layout <body>:
<Script
  src="https://cdn.oatbox.io/widget/loader.js"
  data-client-key="YOUR_CLIENT_KEY"
  data-mode="in-app"
  strategy="afterInteractive"
/>

More

Full installation docs: https://app.oatbox.io/admin/install

Security

This CLI has zero install-time scripts and zero runtime dependencies. It only modifies one file per run (the one your framework's docs point to). Use --dry-run to preview before any change.

Report security issues privately to [email protected] — see the Security Policy.

Troubleshooting

"The globals are there but no bubble appears" (automated browsers). The loader deliberately skips automation agents (navigator.webdriver, headless Chrome / Playwright / Puppeteer user-agents) so crawlers don't burn agent sessions. It installs window.__oatboxWidget / window.oatboxIdentify before that check, so a probe sees the globals present with zero network activity and no bubble — which looks like a broken install but isn't. To let the widget load under automation (e.g. a CI smoke test), set window.__oatboxAllowAutomation = true before the loader runs, or add data-allow-automation to the script tag.

"It works for me but my colleague sees nothing" (holdout experiments). If the agent is running an attribution holdout, a deterministic fraction of visitors are shown no widget by design (the control arm), so the same install renders for one person and not another. Check the agent's experiment settings in the dashboard.

Changelog

See CHANGELOG.md.

License

MIT