npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@unhandled/cli

v0.6.3

Published

Command line client for Unhandled: declare deployments, upload source maps, and hand issues to your coding agent

Readme

@unhandled/cli

Command line client for Unhandled. It declares deployments and uploads source maps from CI, and it hands issues to the coding agent you already use (Claude Code, Codex, opencode, Gemini CLI, Cursor or Amp). It needs Node 24 or later.

Every command sends to the Unhandled API, https://unhandled.net unless --url or UNHANDLED_URL says otherwise. A self-hosted instance sets UNHANDLED_URL to its APP_URL. The DSN host is the ingest receiver, which accepts telemetry only, so the CLI never sends to it.

By default deploy and sourcemaps upload never fail your pipeline. Missing credentials and failed requests print a warning and exit 0. Pass --strict to exit 1 instead. Usage errors, such as a missing --service or an invalid --status, always exit 1.

unhandled deploy

unhandled deploy --service api --environment production

The command sends one POST to <url>/api/v1/deployments. It detects the commit, actor, CI run URL, repository URL and an external ID from GitHub Actions, GitLab CI, CircleCI, Buildkite, Bitbucket Pipelines and Cloudflare Workers Builds. Outside CI it reads the commit from the local .git directory without running git, and it generates a fresh external ID for every call.

The detected commit is sent as commitSha only, never as version. If neither a version nor a commit can be found, the command warns and sends nothing.

Calls from the same CI run share one external ID, so a started call followed by a succeeded call updates a single deployment. A rerun on GitHub Actions gets a new attempt number and creates a new deployment. If two calls would derive different IDs, pass the same --external-id to both.

| Flag | Default or fallback | Notes | | ---------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------ | | --service <name> | none | Required. | | --environment <slug> | UNHANDLED_ENVIRONMENT | Required unless the variable is set. | | --version <version> | UNHANDLED_VERSION | | | --commit <sha> | CI variables, then local .git | | | --previous-commit <sha> | the previous deploy's commit, from the API | Inside a git checkout, the commits since it go out as commits. | | --status <status> | succeeded | started, succeeded, failed or canceled. | | --started-at <time> | none | ISO 8601 with Z or an offset such as +02:00. | | --finished-at <time> | none | Same format as --started-at. | | --external-id <id> | derived from the CI run | | | --actor <actor> | the CI user who triggered the run | | | --ci-url <url> | the CI run URL | | | --metadata <json> | none | A JSON object stored with the deployment and shown on its page. | | --meta <key=value> | none | Repeatable. Adds a string value on top of --metadata. 4 KB of JSON at most. | | --api-key <key> | UNHANDLED_API_KEY | | | --url <url> | UNHANDLED_URL, then https://unhandled.net | | | --strict | off | Turn warnings into exit code 1. | | --dry-run | off | Print the payload and each field's source. Sends nothing and needs no API key. |

Explicit flags always win over detected values. A flag with an empty value is a usage error.

Each request has a 5 second timeout, except a source map batch, which gets 30 seconds plus 10 seconds per MB. After a network error, a timeout or a 5xx response the command retries once. It does not retry 4xx responses.

Dry run

dry run: no request sent
POST https://unhandled.net/api/v1/deployments

service      api         flag
environment  production  env:UNHANDLED_ENVIRONMENT
version      1.8.2       env:UNHANDLED_VERSION
commitSha    abc1234     flag
status       succeeded   default
externalId   deploy-1    flag

The source column is one of flag, env:<NAME>, ci:<provider>, git, default or generated.

unhandled sourcemaps upload

unhandled sourcemaps upload ./dist --release 1.8.2

The command finds every *.map file under the directory and sends them in one multipart POST to <url>/api/v1/sourcemaps. File names are sent relative to the directory with / separators.

| Flag | Default or fallback | Notes | | --------------------- | ------------------------------------------------- | --------------------------------------------------- | | --release <release> | UNHANDLED_VERSION, platform and CI commits, then local .git | Same order as @unhandled/browser/vite, so maps match the bundle's release. | | --api-key <key> | UNHANDLED_API_KEY | A project deploy key (dk_). DSN keys are refused. | | --dsn <dsn> | UNHANDLED_DSN | Provides the service ID. Its host is not used. | | --url <url> | UNHANDLED_URL, then https://unhandled.net | | | --strict | off | Turn warnings into exit code 1. | | --dry-run | off | List the endpoint, release and its source, and files. | | --delete-after-upload | off | Delete the found maps afterwards, even when the upload fails or is skipped, so they never ship. A dry run deletes nothing. |

Finding no source maps or having no deploy key is a warning. Finding no release is a usage error.

For Astro, upload the client output: dist/client with the Node or Cloudflare adapter, dist with no adapter.

unhandled dsyms upload

unhandled dsyms upload ./build/MyApp.xcarchive/dSYMs --release "[email protected]+12"

Sends each *.dSYM/Contents/Resources/DWARF/* file under the path (a .dSYM bundle, a folder of them, or one DWARF file) to <url>/api/v1/dsyms, named from the bundle down. Same flags as sourcemaps upload. The server keeps one symbol table per architecture slice and matches Swift frames to it by image UUID.

unhandled mappings upload

unhandled mappings upload app/build/outputs/mapping/release/mapping.txt --release "[email protected]+12"

Sends an R8 or ProGuard mapping.txt to <url>/api/v1/mappings. Same flags as sourcemaps upload. The release must match the one the app reports.

dSYMs and mappings share the source map quota, retention and deletion.

Coding agents

These commands make no LLM calls of their own, init included. They sign in to Unhandled, read issues over the MCP endpoint, and start the agent CLI you already have installed. The agent then reads the issue through its own Unhandled MCP connection, so set that up first with unhandled mcp install.

| Command | macOS and Linux | Windows | | --- | --- | --- | | login, logout, init, issues | Yes | Yes | | mcp install | Yes | Yes. Edits the config file where the agent has one, and prints the command for you to run where it has only a command (claude). | | fix, watch | Yes | No. Run them in WSL. Agent CLIs install as .cmd shims on Windows, which only start through cmd.exe and its quoting rules. |

unhandled login

unhandled login
unhandled login --url https://unhandled.net --no-browser
unhandled login --scope issues:write

The CLI registers itself as an OAuth client, listens on http://127.0.0.1:<random port>/callback and opens the consent page in your browser. It uses the authorization code flow with PKCE (S256) and rejects a callback whose state or issuer does not match. --no-browser prints the link instead of opening it. It asks for org:read, projects:read and issues:read, plus each --scope you add, and you can narrow the organizations on the consent page.

Tokens go to ~/.config/unhandled/credentials.json (or $XDG_CONFIG_HOME/unhandled/) with mode 0600, one entry per server. The CLI refreshes the access token when it expires. Refresh tokens rotate, so concurrent commands take a lock before refreshing. Logging in again revokes the previous grant.

unhandled logout

Revokes the refresh token on the server and removes the server's entry from the credentials file.

Signing in: a login or an agent token

Every command that reads from Unhandled needs one of two credentials:

  • UNHANDLED_TOKEN, an agent token (unh_agent_…) an admin creates under Settings > MCP. It needs no browser, so it suits CI, cloud agents and containers. It wins over a stored login.
  • A login from unhandled login.

The DSN is never one of them. A DSN is a public ingest key that ships in browser bundles, so it never authorizes a read. With only a DSN, every read command fails with sign in or set UNHANDLED_TOKEN before it sends anything, and a DSN or ingest key set as UNHANDLED_TOKEN is refused the same way.

The DSN still helps pick the project. When you pass no --project, the CLI reads UNHANDLED_DSN or VITE_UNHANDLED_DSN from the environment, then from .env.local and .env in the current directory, and selects the project that owns that service among the projects your credential already reaches. Only the service ID is used and it never leaves your machine. If your credential cannot see that project, the command stops with not authorized for the project behind UNHANDLED_DSN.

unhandled init

unhandled init
unhandled init --project shop --service api --environment staging

A deterministic setup with no LLM involved. In the app's directory it:

  1. Reads package.json and picks the stack from the dependencies: AdonisJS, Next.js, NestJS, React Native, Fastify, Hono, Express, a Vite app (browser), or else plain Node.js. --stack overrides it.
  2. Signs you in through the browser unless UNHANDLED_TOKEN is set or your login already has keys:write, which creating a service needs.
  3. Calls setup_service to create the service, named after the package unless --service says otherwise, or to add a key to the existing one. An app that already runs a Sentry SDK gets the Sentry-compatible DSN instead.
  4. Runs the stack's installer with the package manager your lockfile names (pnpm add, yarn add, bun add or npm install). --no-install lists the command instead.
  5. Writes the DSN and environment to .env (or .env.local for Next.js) with mode 0600, keeping every other line.
  6. Adds the Unhandled plugin to vite.config.* for a Vite app.

It prints the steps it could not apply safely, such as the line that loads the SDK before your app, then says how to check the result with verify_setup. It never prints the DSN. Only Node.js and browser apps are supported; other stacks follow the setup page or get_setup_guide.

unhandled issues

unhandled issues --project shop --status open
unhandled issues context @top --json
unhandled issues resolve 42 --resolution in_next_release --comment "Fixed in #812"

| Command | Reads with | Prints | | --- | --- | --- | | issues or issues list | list_issues | A table of the most recent issues, or the page as JSON. | | issues view <issue> | get_issue | The issue's number, status, title and URL, or the full result as JSON. | | issues context <issue> | get_fix_context | The fix brief as markdown, or with --json exactly what get_fix_context returns. | | issues resolve <issue> | update_issue | The resolved issue. |

<issue> is an issue ID, an issue URL, or a selector: @top (the first issue of the For review tab), @most_users, @latest_regression, @since_last_deploy or @mine. An issue URL names its own project.

| Flag | Commands | Default | Notes | | --- | --- | --- | --- | | --org <slug> | all | the only organization that has the project | | | --project <slug> | all | the project behind the DSN, else the only project you reach | Required when neither decides. | | --status <status> | list | open | open, resolved, archived or all. | | --environment <name> | list, view, context | production | | | --detail <detail> | context | summary | full allows a longer brief. | | --resolution <resolution> | resolve | now | now, in_next_release, in_release (with --release) or in_commit (with --commit). | | --comment <text> | resolve | none | | | --json | all | off | Print the result as JSON. |

resolve needs issues:write: run unhandled login --scope issues:write, or give the agent token that scope.

Issue titles and the fix brief come from your app's errors. The CLI strips control and formatting characters from them so a crafted message cannot rewrite your terminal. The JSON output keeps the server's fencing of untrusted text.

unhandled fix

unhandled fix https://unhandled.net/o/acme/projects/shop/issues/42 --agent claude
unhandled fix 42 --project shop --agent codex --headless

Starts the agent in the current directory with your terminal attached and exits with the agent's exit code. The task it passes names the issue ID and URL and tells the agent to call get_fix_context. Issue titles and telemetry never go on the command line, and the CLI starts the agent without a shell. An issue URL needs no login. A bare ID resolves the project through your login.

--headless uses the agent's non-interactive mode (claude -p, codex exec, opencode run, gemini -p, cursor-agent -p, amp -x).

unhandled watch

unhandled watch --agent claude --project shop --interval 2m --max-runs 5

Polls list_issues for issues first seen or regressed since the last poll and runs the agent headless on each, one at a time, oldest first. The first run starts from the current time, so it ignores the existing backlog.

| Flag | Default | Notes | | --- | --- | --- | | --agent <agent> | none | Required. | | --org, --project, --environment | as for issues | | | --interval <duration> | 60s | 30s, 5m, 1h or bare seconds. At least 5s. | | --max-runs <n> | unlimited | Stop after this many agent runs. | | --dry-run | off | Print the commands it would run. Writes no state. | | --agent-args "<args>" | none | See the warning below. |

The state lives in ~/.local/state/unhandled/watch-<org>-<project>-<hash>.json (or $XDG_STATE_HOME), where the hash covers the server URL, organization and project. It holds the cursor and the issues the watcher has handled with their outcome, up to the newest 1000 from the last 30 days. An issue is recorded before its run starts, so it never runs twice for the same trigger, even if the watcher crashes mid-run. Entries are keyed on the issue ID, plus regressedAt for a regression, so an issue already handled runs once more each time it regresses. Delete its entry to allow another run. Only one watcher per project and server can run at a time. A poll reads up to 20 pages; if there is more, the cursor stays where it was so the next poll reads the rest.

A failed poll waits twice as long each time, up to 15 minutes, and goes back to --interval after the next success. An expired login stops the watcher.

Each headless run gets its own process group with no terminal input, so Ctrl-C in your terminal reaches only the CLI. The first Ctrl-C (or SIGTERM) stops polling and waits for the running agent to finish, then records its outcome. A second one is sent on to the agent's process group. A run that ends that way, or fails after the first Ctrl-C, is not recorded, so the issue runs again next time. The watcher exits 130 when it was interrupted.

fix --headless behaves the same way. Interactive fix keeps the agent in your terminal's foreground, so Ctrl-C goes straight to the agent, as if you had started it yourself, and the CLI waits for it and exits with its exit code.

Agent permissions and --agent-args

fix and watch never pass flags that widen what the agent may do. A headless agent therefore stops at its usual permission prompts, or works only within what its own config already allows. Configure that in the agent itself, or pass extra flags explicitly:

unhandled watch --agent claude --agent-args "--permission-mode acceptEdits"

--agent-args is split like a shell would split it, without expanding variables or globs, and appended after the task. Warning: flags such as --dangerously-skip-permissions, --yolo or --dangerously-allow-all let an agent run any command while it works on text that came from your production errors. Use them only in a sandbox you can throw away. Amp's interactive mode reads its task from a pipe, so --agent-args needs --headless there.

unhandled mcp install

unhandled mcp install --agent cursor
unhandled mcp install --agent codex --file
unhandled mcp install --agent vscode --print

Connects the agent to <url>/mcp, which lists the debug toolset. For claude, codex, gemini, amp and vscode it runs the agent's own mcp add command (on Windows it edits the config file instead, or prints the claude command for you to run). For opencode, cursor, zed and windsurf, or with --file, it adds an unhandled entry to the agent's config file. It changes only the keys it sets on that entry, keeps every other key, including ones you added to the unhandled entry, and copies the old file to <file>.<timestamp>.bak first. A file that already has the same entry stays untouched. It refuses to rewrite a file it cannot parse, such as a Zed settings.json with comments, or a Codex config.toml that defines the server inline or twice, and prints the snippet to add by hand. A symlinked config is written where the link points. On Windows the files are %USERPROFILE%\.cursor\mcp.json, %USERPROFILE%\.codex\config.toml, %USERPROFILE%\.gemini\settings.json, %USERPROFILE%\.config\amp\settings.json, %USERPROFILE%\.config\opencode\opencode.json, %APPDATA%\Zed\settings.json and %APPDATA%\devin\mcp_config.json. --print shows the command, the snippet, a one-click link where the agent has one, and the docs link, and changes nothing.

Environment variables

| Variable | Used by | | ----------------------- | ----------------------------- | | UNHANDLED_API_KEY | deploy, sourcemaps, dsyms and mappings upload | | UNHANDLED_ENVIRONMENT | deploy | | UNHANDLED_VERSION | deploy, sourcemaps, dsyms and mappings upload | | UNHANDLED_URL | every command | | UNHANDLED_TOKEN | init, issues, fix, watch: an agent token used instead of a login | | UNHANDLED_DSN | sourcemaps, dsyms and mappings upload; for reads, only a hint that picks the project | | XDG_CONFIG_HOME, XDG_STATE_HOME | credentials and watch state |

GitHub Actions

Mark the deployment as started before the rollout, then report the outcome.

name: deploy
on: workflow_dispatch
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      UNHANDLED_API_KEY: ${{ secrets.UNHANDLED_API_KEY }}
      UNHANDLED_ENVIRONMENT: production
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npx --no-install unhandled deploy --service api --status started
      - id: rollout
        run: npm run deploy
      - if: success()
        run: npx --no-install unhandled deploy --service api --status succeeded
      - if: failure() && steps.rollout.outcome == 'failure'
        run: npx --no-install unhandled deploy --service api --status failed

For AI agents

A coding agent can install this package, check that its data arrives and fix the errors it reports through the Unhandled MCP server at https://unhandled.net/mcp. In Claude Code, the Unhandled plugin adds that server plus skills for instrumenting a service, fixing a production error with a failing test first and verifying a deploy:

claude plugin marketplace add treboryx/unhandled
claude plugin install unhandled@unhandled

Codex, Cursor, Gemini CLI and other agents connect to the same URL. Coding agents has the setup for each one and an AGENTS.md section to add to your repository.