@bugsee/cli
The Bugsee CLI — a cross-platform Rust binary that collects debug information files (dSYM, ELF, Windows PDB, R8/ProGuard mappings, JS source maps), resolves build-environment metadata, and uploads symbols to Bugsee.
# Run once, without adding it to a project:
npx @bugsee/cli --version
# Or add it to a project, then run the `bugsee-cli` binary it provides:
npm install --save-dev @bugsee/cli
npx bugsee-cli --version
npx bugsee-cli only works where @bugsee/cli is installed. Anywhere else npx
looks for an unscoped package named bugsee-cli, which does not exist, and fails
with E404. Use the scoped npx @bugsee/cli there.
How the binary gets here
The binary is not in this package. It ships in six per-platform packages,
declared as optionalDependencies:
| Package | os / cpu |
|---|---|
@bugsee/cli-darwin-arm64 | darwin / arm64 |
@bugsee/cli-darwin-x64 | darwin / x64 |
@bugsee/cli-linux-arm64 | linux / arm64 |
@bugsee/cli-linux-x64 | linux / x64 |
@bugsee/cli-win32-x64 | win32 / x64 |
@bugsee/cli-win32-arm64 | win32 / arm64 |
npm installs only the one matching your machine and skips the rest. Nothing is
downloaded at install time, so this works with --ignore-scripts, with a
lockfile-pinned CI install, and offline from a warm cache.
The Linux builds link glibc and are marked "libc": ["glibc"]. On musl (Alpine)
the install still succeeds, and bugsee-cli reports that plainly if invoked —
use a glibc base image, or build from source.
If the platform package is unavailable — --omit=optional (or the deprecated
--no-optional), or a registry mirror that carries only this package — a
postinstall fallback downloads the release archive for your host and verifies
its SHA-256 before unpacking it into vendor/. On a platform with no published
binary there is nothing to download, so it only warns. That fallback never fails the install:
if it cannot fetch the binary it warns and exits 0, and the error surfaces only
if you actually invoke bugsee-cli.
| Variable | Effect |
|---|---|
BUGSEE_CLI_SKIP_DOWNLOAD=1 | Skip the fallback download entirely. |
BUGSEE_CLI_BASE_URL=<url> | Fetch <url>/bugsee-cli-<triple>.<ext> (+ .sha256) instead of the GitHub release — point it at an internal mirror, or at https://download.bugsee.com/cli/v<version>. |
Programmatic use
const { spawnSync } = require("node:child_process");
const { binaryPath } = require("@bugsee/cli");
const out = spawnSync(binaryPath(), ["vcs-metadata"], { encoding: "utf8" });
const metadata = JSON.parse(out.stdout);
binaryPath()— absolute path to the binary; throws with a diagnostic if there is none for this platform.resolveBinaryPath()— the same lookup, returningnullinstead of throwing.version— the CLI version this package carries.
Exit codes
bugsee-cli exits with a
stable, documented code
and the launcher forwards it unchanged (0 success, 1/2 structural — the
caller should fall back, 10–39 substantive failures, 40 a deliberate build
gate, 50 an internal error after a request may have been sent). A launcher
that cannot find a binary at all exits 1, which is the "structural, fall back" case by that same contract.
Other install channels
@bugsee/bugsee-cli was the same CLI published by cargo-dist as a single
package that downloads its binary in a postinstall. It is deprecated and no
longer published (last version 0.8.2); use @bugsee/cli, which also works under
--ignore-scripts. See the
Distribution section for
the shell installer, Homebrew tap, and the per-build-system bundles.
License
MIT © Bugsee, Inc.