CLI

The bugotter CLI does the three things you'd otherwise do by hand: add the script and keys to a project, upload source maps after a build, and mark a deploy. Run it with npx; there's nothing to install.

In 30 seconds

create a token at Settings → Agent access, then run npx bugotter init --token bo_… in your project.

Commands

Terminal

npx bugotter init --token bo_… [--app example.com] [--proxy]   # script tag + keys
npx bugotter sourcemaps [dir] [--release sha] [--delete] [--url-prefix /assets/] [--verbose]
npx bugotter deploy [--version sha] [--message "…"] [--url https://…]
npx bugotter help

init

Run it in your project's folder:

It finds your app: from --app, from homepage in package.json, or the only app on your account. If it can't tell, it lists your apps; run it again with --app.
It adds the script tag to your layout: app/layout.tsx (Next.js App Router), pages/_document.tsx (Pages Router) or index.html.
It writes BUGOTTER_DSN, BUGOTTER_PROJECT and BUGOTTER_KEY to .env.local (or .env). Values already there aren't touched.
It prints what's left: the Sentry SDK for server errors, source maps, deploys and revenue by source.

Add the BUGOTTER_* values to your host's production environment too.

--token: an agent token from Agent access. With a read-only token, BUGOTTER_KEY (the upload key) isn't written; copy it from the app's Setup tab, or use a token with Allow changes.
--proxy: load the script from your own domain, past ad blockers, and print the three rewrites to add. Replace YOUR_PROXY_KEY in them with the key from the app's Settings → Ad blockers.

sourcemaps

Uploads every .js.map in the build (default: .next or dist).

--release: the release to tag the maps with. Without it, the CLI uses the commit from Vercel, GitHub Actions, Cloudflare Pages or Netlify, or git.
--delete: removes the maps after upload, so your source isn't public.
--url-prefix: where the browser loads the files from, if not /_next/ (Next.js) or /.
--verbose: lists every file uploaded.

deploy

Marks a deploy. The version defaults to the current commit, the message to its subject line. --url adds a link to the deploy.

Keys

Keys come from flags (--token, --project, --key) or BUGOTTER_TOKEN, BUGOTTER_PROJECT and BUGOTTER_KEY (environment, .env.local or .env). --api points at another BugOtter address.

In CI, set BUGOTTER_PROJECT and BUGOTTER_KEY as secret environment variables. Both are in the deploy webhook URL on the app's Setup tab.

Common questions

"Missing --project and --key"

sourcemaps and deploy need your project number and upload key. Run init first, or set BUGOTTER_PROJECT and BUGOTTER_KEY.

"Unknown token. Create one at /app/agent."

The token is wrong or was revoked. Create a new one at Agent access.

"No apps in your account yet"

Add the app in BugOtter first, then run init again.

"No .js.map files" or "Is source map output turned on?"

Your build didn't write source maps. Next.js: productionBrowserSourceMaps: true. Vite: build.sourcemap: true. Then build again.

"Couldn't place it in app/layout.tsx"

Your layout has no <head> the CLI could find. Paste the tag it prints into the <head> yourself.