@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 productionThe 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 flagThe source column is one of flag, env:<NAME>, ci:<provider>, git, default or generated.
unhandled sourcemaps upload
unhandled sourcemaps upload ./dist --release 1.8.2The 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:writeThe 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 stagingA deterministic setup with no LLM involved. In the app's directory it:
- Reads
package.jsonand picks the stack from the dependencies: AdonisJS, Next.js, NestJS, React Native, Fastify, Hono, Express, a Vite app (browser), or else plain Node.js.--stackoverrides it. - Signs you in through the browser unless
UNHANDLED_TOKENis set or your login already haskeys:write, which creating a service needs. - Calls
setup_serviceto create the service, named after the package unless--servicesays otherwise, or to add a key to the existing one. An app that already runs a Sentry SDK gets the Sentry-compatible DSN instead. - Runs the stack's installer with the package manager your lockfile names (
pnpm add,yarn add,bun addornpm install).--no-installlists the command instead. - Writes the DSN and environment to
.env(or.env.localfor Next.js) with mode 0600, keeping every other line. - 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 --headlessStarts 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 5Polls 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 --printConnects 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 failedFor 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@unhandledCodex, 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.
