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

bravenlab

v0.1.11

Published

The Braven command-line client: sign in, push files, and run the watch agent.

Downloads

2,162

Readme

bravenlab

The braven command: sign in once per machine and let the CLI and the Python SDK use the same identity.

This package owns no credential convention. The config file's path, its version-1 schema and the account naming belong to braven-identity (packages/identity), the contract every surface mirrors — so a braven login here is the same login braven.login() sees. The TypeScript implementation lives in @braven/identity-store, which this CLI and braven-agent share; the Python package stays the reference.

Nothing in this package ever prints, logs or writes a secret: secrets live in the 0600 credentials file and are handed only to the store.

Install

npx bravenlab --help
npx bravenlab agent --folder ./my-data-folder --project-id <id>

The package installs two names for one bin: npx bravenlab (the package name) and braven once it is installed globally. The old package name [email protected] is superseded by bravenlab; the OAuth client id stays braven-cli on the wire.

bravenlab and braven-agent version independently (.agents/VERSIONING.md). A v<version> tag names bravenlab — scripts/check-release-tag.ts refuses a tag that disagrees with its manifest — and the same workflow stages braven-agent at its own manifest version when that version is unpublished. The release drops the workspace: ranges npm cannot resolve (scripts/prune-workspace-deps.ts) because the build inlines those packages.

The workflow stages the release (npm stage publish) rather than publishing it: a maintainer approves the staged version with 2FA — npm stage approve <stage-id>, or the Staged Packages tab on npmjs.com — and only then does 0.1.0 become installable. A brand-new name gets a public 0.0.0-stage placeholder while its real version waits.

The published artifact is a bundle, not the source tree: braven is dist/bin.js, a plain ESM file with #!/usr/bin/env node, its third-party dependencies external and declared in dependencies. files ships dist/ and this README only; source maps embed their sources, so a stack trace still points into the TypeScript without publishing src/.

nub run --filter bravenlab build  # esbuild → dist/bin.js + dist/{cli,auth}.js
node dist/bin.js --help            # exactly what an install runs
npm pack --dry-run                 # dist/ + README.md
nub exec -F braven braven --help   # the workspace bin, after a build
nub run --filter bravenlab test   # builds in `pretest`, then the suite

src/bin.test.ts spawns dist/bin.js with an empty home directory, so a bundle that drifts from the source (or loses its shebang or a runtime dependency) fails the suite rather than a user. Development still runs the source directly — Node 24 strips its types — but braven agent resolves the braven-agent package, so build the agent once first:

nub run --filter braven-agent build
node --experimental-strip-types src/bin.ts --help

Commands

| Command | What it does | | --- | --- | | braven login [--origin URL] [--web-origin URL] | Opens the browser, waits for the signed-in session token on a loopback listener, proves it with GET {origin}/api/auth/get-session, stores it as kind="session", makes the account current, then prints whoami. This is the whole sign-in: no password is typed into the terminal. | | braven login --watcher | Uses the sign-in the Braven app already made on this machine: the app (and the agent it runs) and the CLI share one store, so this only adopts the account and makes it current — no browser, no prompt. Refuses when the app never signed in to the resolved server. | | braven login --api [--key bvn_api_…] [--email EMAIL] | Stores a long-lived API key as kind="apiKey"; the key comes from --key or $BRAVEN_API_KEY. For CI, scripts and machines that cannot open a browser. | | braven login --device [--client-id ID] | Better-auth's device authorization grant: prints a user code and verification URL, opens it, polls /api/auth/device/token on the server's interval, then proves and stores the session token exactly as the loopback flow does. For headless machines and machines without a reliable loopback callback. | | braven push <file> [--override] [--path PATH] [--project-id ID] | Uploads one local file through files.ingest (POST {origin}/rpc/files/ingest) with X-Project-Id and the stored credential as a bearer. --path defaults to the file's basename; --override reuses that path's Experiment/File instead of deduping or adding a sibling. | | braven key add [--origin URL] [--email EMAIL] [--label LABEL] <bvn_api_...> | Stores a long-lived API key as kind="apiKey". The owner comes from --email, or from GET {origin}/api/auth/get-session with the key as a bearer. | | braven whoami | The effective identity: origin, email, kind, label. Never the secret. Honours BRAVEN_SESSION_TOKEN / BRAVEN_API_KEY and says "signed in from the environment" when one is in play. | | braven config / braven config show | The stored accounts, which one is current, and the resolved company / project defaults. | | braven config set company\|project <value> | Writes one default. | | braven config use <email> | Switches current, wherever that account's origin is. | | braven init [--folder PATH] [--project ID\|NAME] [--visibility personal\|project] | Binds a folder to a Project by writing braven.toml — the binding and who may see it. Idempotent for the same Project; --force replaces another binding, --notebook adds the venv/sync hints, --print shows the file. | | braven notebooks list [--project ID\|NAME] [--json] | The folders this account may see in a Project, each with its visibility, owner and whether it is read-only. Personal folders of teammates never appear. | | braven notebooks share <repo\|folder> / unshare | Shares a synced folder with the Project (every member reads, only the owner writes) or makes it personal again. A folder's braven.toml is rewritten to match. | | braven notebooks visibility <repo\|folder> | Who may see the folder today. | | braven logout [--email EMAIL] | Forgets that account — stored secret included (default: the current one), rotating current to a survivor. A stored session is revoked server-side; a stored API key is only forgotten. | | braven agent [agent flags] | Runs the headless watch daemon (braven-agent) with the arguments handed over verbatim. Same program, same flags — braven agent --help prints the daemon's usage. | | braven agent install [--folder PATH]… [--project-id ID] | Writes the platform's login service (LaunchAgent, systemd user unit, Scheduled Task Braven agent), pointing at this binary's absolute path; macOS and Linux start it now, Windows at the next logon. | | braven agent uninstall | Stops and removes that service; a missing one is already uninstalled. | | braven mcp [mcp install flags] | Runs the MCP server over stdio. braven mcp install --client claude-code\|claude\|cursor\|opencode\|zed\|vscode [--command PATH] [--force] [--path FILE] merges an absolute-command braven entry into that client's config; Claude Code goes through claude mcp add --scope user when claude is on PATH. A commented JSONC file is never rewritten — the entry is printed instead. | | braven desktop run [--terminal\|-t] [--background] [--app PATH] | Launches the watcher: the installed app, else a checkout's build, else its src/bin.ts on bun. A window detaches and returns; --terminal keeps the TTY and waits. --background sets GPUIX_BACKGROUND=1; --app names the app. | | braven desktop install [--origin URL] [--dmg FILE\|--app PATH\|--exe FILE] [--silent] [--system] [--destination PATH] | With no flags, reads GET {origin}/desktop/version, downloads this machine's installer from /desktop/download/<platform>, verifies its SHA-256 and installs it; --dmg/--app/--exe install a local file without the network. |

--origin beats $BRAVEN_API_URL, which beats the hosted https://api.bravenlab.com. A trailing slash is normalised away, so origins never produce a doubled path. --web-origin beats $BRAVEN_WEB_URL, which beats https://bravenlab.com.

Three ways in

braven login picks the flow with a flag: --watcher (the running app's sign-in), nothing/--browser (the loopback handoff), or --api (a stored key). All three end in the same identity store, so whoami, push, agent and the Python SDK see the same account.

How login works

  1. Bind an http.Server on 127.0.0.1 with port 0, and read the real ephemeral port from HttpServer.address (narrowed to an inet address).
  2. GET /?token=<session token> resolves an Effect Deferred and answers <h1>Authenticated. You can close this window.</h1>; every other request is 400. The listener is loopback-only and lives in the command's scope, so it closes on success, on the timeout, and on Ctrl-C.
  3. Open {webOrigin}/cli-login?port=<port> with the open package. The web app redirects the better-auth session token to the loopback URL.
  4. Wait five minutes (Effect.timeoutOrElse). On timeout the listener closes and the CLI fails with one actionable line.
  5. With the token, call GET {origin}/api/auth/get-session with Authorization: Bearer <token>. Only a 200 whose body has user.email becomes an account; any other answer fails loudly and stores nothing.

How login --device works

The same identity, without the token-in-a-URL handoff. It needs better-auth's deviceAuthorization() plugin on the API — this repo configures it, along with the deviceCode table and the /device approval page.

  1. POST {origin}/api/auth/device/code with {client_id, scope}. The client id is --client-id, $BRAVEN_CLIENT_ID, or braven-cli; the scope is openid profile email.
  2. Print the user_code and open verification_uri_complete ?? verification_uri through the same Browser seam.
  3. Poll POST {origin}/api/auth/device/token with the RFC 8628 grant (grant_type, device_code, client_id) on a Schedule seeded from the server's interval. authorization_pending keeps polling; slow_down adds five seconds to every subsequent interval. expired_token, access_denied and invalid_grant stop with one actionable line.
  4. The whole wait is bounded by expires_in (30 minutes when omitted) through Effect.timeoutOrElse.
  5. On success access_token is a better-auth session token: prove it with GET /api/auth/get-session, store {origin, kind: "session", secret, email} and print whoami. Nothing is stored on expiry, denial or failure.

How push works

files.ingest is plan 015's one ingest wire, an oRPC procedure in its multipart envelope, so push, the agent and the webapp share one write path:

POST {origin}/rpc/files/ingest
Authorization: Bearer <session token or API key>
X-Project-Id: <project>
Content-Type: multipart/form-data

The input carries path, override ("true" / "false") and the bytes as file. path defaults to the file's basename; the server takes its basename as the filename that keys the Experiment and File. Every door ends at saveUpload, so hashing, dedup, versioning and --override have one implementation (packages/api/src/services/files.ts). Re-pushing the same bytes never makes a second File in that Experiment; --override reuses the path's existing Experiment instead of creating a sibling.

The project comes from --project-id, $BRAVEN_PROJECT_ID, or the store's defaults.project resolved to an id through projects.listMine (narrowed by defaults.company when both are set). An unknown or ambiguous project name fails with exit 2 instead of guessing; a server refusal is one line and exit 1.

How logout works

The stored secret is read before the account is removed, so the command can revoke it. Only a stored session is revoked — POST {origin}/api/auth/sign-out with the token as a bearer; a 200 or a 401 both mean it is dead. A kind="apiKey" account is only forgotten locally and stays valid until it is revoked under Settings → API keys.

The stored secret and config row then go, and current rotates to a survivor (or none). Because the local account is already gone when revocation runs, an unreachable API is a warning — "the session stays valid until it expires" — not a failure; there is nothing left to retry. With no stored account the command exits 3.

Identity store

Config (never a secret), at the OS convention:

| OS | Path | | --- | --- | | macOS | ~/Library/Application Support/braven/config.json | | Linux | ${XDG_CONFIG_HOME:-~/.config}/braven/config.json | | Windows | %APPDATA%\braven\config.json |

{
  "version": 1,
  "current": "https://api.bravenlab.com|[email protected]",
  "accounts": [
    { "origin": "https://api.bravenlab.com", "email": "[email protected]", "kind": "session" }
  ],
  "defaults": { "company": "Gelion" },
  "watcher": {}
}

Writes are atomic (config.json.tmp + rename) and preserve watcher and the other defaults. The secret lives in credentials.json beside it, keyed by {origin}|{email}, written atomically with mode 0600 — no OS keychain, so a freshly installed binary never prompts. A file that cannot be read or written surfaces as one line and nothing is stored.

Precedence for the secret is env var > store: BRAVEN_SESSION_TOKEN or BRAVEN_API_KEY (with BRAVEN_API_URL) win and touch neither file. The origin is flag > $BRAVEN_API_URL > hosted; --email selects a stored account.

Exit codes

| Code | Meaning | | --- | --- | | 0 | It worked. Help and --version too. | | 1 | The command failed: a rejected session, an unreachable API, an unreadable credentials file, a corrupt config file. | | 2 | The arguments cannot work: an unknown flag, a missing one, a key without the bvn_api_ prefix, a key whose owner the probe could not prove. | | 3 | Not signed in, or no stored account for the email asked about — so a script can braven login and retry. |

Failures print exactly one braven: <what to do> line on stderr.

Layout

src/
  bin.ts           # entry point: `agent` dispatch, then Node services + runMain
  cli.ts           # the effect/cli command tree and the exit-code boundary
  commands.ts      # login (browser handoff), whoami, config, logout, key add
  agent-service.ts # the login service: LaunchAgent, systemd user unit, Scheduled Task
  auth.ts          # loopback listener, device grant, session lookup + revoke
  desktop.ts       # desktop install: release manifest, download, DMG and .exe
  desktop-run.ts   # desktop run: which app to launch, and how (window or terminal)
  files.ts         # files.ingest multipart wire + project resolution
  mcp-install.ts   # mcp install: one client's JSON/JSONC config
  pipeline.ts      # pipeline compile/validate/pull/push
  testing.ts       # browser/sessions/HTTP doubles (the store's doubles come from
                   # @braven/identity-store/testing)

The config file, its schema, the credentials file (Secrets, StoreConfig, Environment) and the CliFailure vocabulary live in @braven/identity-store, so the CLI and braven-agent read one store instead of depending on each other. The seams the CLI adds are Browser, Sessions and HttpClient. Tests replace all of them, so the suite touches no real credentials file, no real browser and no network except the loopback listener the sign-in test deliberately starts.

braven agent is not an effect/cli command: bin.ts checks argv[0] first and hands the remaining arguments to runAgent from braven-agent, so the daemon's flags never have to be modelled twice. braven agent install and braven agent uninstall are the exceptions — they are the CLI's own commands and go through effect/cli like the rest.

Development

nub run --filter bravenlab check-types
nub run --filter bravenlab test
nub run lint && nub run fmt