| name | evidence-browser |
| description | Interact with an Evidence Browser instance via the `eb` CLI — upload bundle ZIPs, inspect bundles and workspaces, and manage API keys. Use this skill whenever an agent needs to push or query Evidence Browser artifacts programmatically. Non-interactive: authentication must be supplied via env vars or flags, not via `eb login`. The `/evidence-upload` skill delegates its upload step here. |
/evidence-browser
Low-level CLI primitive for the Evidence Browser REST API. Agents call this directly; higher-level skills (e.g. /evidence-upload) wrap it.
Installation
npm install -g evidence-browser-cli
Quick reference
eb upload <file.zip> --workspace <slug> [--bundle-id <id>] [--url <url>] [--api-key <key>]
eb bundle list <workspace>
eb bundle info <workspace> <bundleId>
eb bundle tree <workspace> <bundleId>
eb bundle download <workspace> <bundleId> --file <path-in-bundle>
eb bundle delete <workspace> <bundleId> [--force]
eb workspace list
eb workspace create <slug> <name> [--description <text>]
eb workspace update <slug> [--name <name>] [--description <text>]
eb workspace delete <slug> [--force]
eb api-key list [--admin]
eb api-key create <name> --scope <read|upload|admin>
eb api-key delete <keyId>
Interactive-only (human use, never call from agents):
eb login [url] # prompts for API key; writes ~/.config/evidence-browser/config.json
eb logout # removes config file
eb whoami # shows current auth status
Authentication priority (resolved per-command)
--api-key <key> flagEB_API_KEY environment variable~/.config/evidence-browser/config.json (apiKey field, written by eb login)
Same priority for the server URL: --url → EB_URL → config file url field.
Agents must use env vars or flags. eb login is interactive (reads from TTY) and must not be called from non-interactive contexts.
Common agent workflow — upload a bundle
zip -r /tmp/my-bundle.zip .evidence/20260427-1200-main-attempt1/
EB_URL=http://127.0.0.1:3000 \
EB_API_KEY=<key> \
eb upload /tmp/my-bundle.zip \
--workspace default \
--bundle-id 20260427-1200-main-attempt1
On success the CLI prints:
Uploaded: 20260427-1200-main-attempt1
View: http://127.0.0.1:3000/w/default/b/20260427-1200-main-attempt1
Parse the View: line for the bundle URL to return to the caller.
On non-zero exit, surface the error verbatim — do not retry automatically.
Exit codes
| Code | Meaning |
|---|
| 0 | Success |
| 1 | Runtime error (API error, auth failure, file not found) |
| 2 | Usage error (missing required argument or flag) |
Common error messages
| Message | Cause | Fix |
|---|
Missing Evidence Browser URL | No URL from any source | Pass --url or set EB_URL |
Missing API key | No key from any source | Pass --api-key or set EB_API_KEY |
Request failed (401) | Key invalid or expired | Rotate the key via eb api-key create |
Request failed (403) | Key scope insufficient | Use a key with the required scope (upload or admin) |
Request failed (400) | Bundle validation failed | Check manifest.json against the Evidence Browser schema |
Error: File must be a .zip | Non-ZIP file passed to upload | Package the session dir as a .zip first |
Bundle ID rules
The bundleId is derived from the ZIP filename (stem) when --bundle-id is omitted. The server rejects IDs containing /, .., or \0. Recommended format:
{YYYYMMDD-HHmm}-{branch-slug}-attempt{N}
Derive {branch-slug} from git rev-parse --abbrev-ref HEAD with / replaced by -.
Resources
