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 suitesrc/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 --helpCommands
| 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
- Bind an
http.Serveron127.0.0.1with port 0, and read the real ephemeral port fromHttpServer.address(narrowed to an inet address). GET /?token=<session token>resolves an EffectDeferredand answers<h1>Authenticated. You can close this window.</h1>; every other request is400. The listener is loopback-only and lives in the command's scope, so it closes on success, on the timeout, and on Ctrl-C.- Open
{webOrigin}/cli-login?port=<port>with theopenpackage. The web app redirects the better-auth session token to the loopback URL. - Wait five minutes (
Effect.timeoutOrElse). On timeout the listener closes and the CLI fails with one actionable line. - With the token, call
GET {origin}/api/auth/get-sessionwithAuthorization: Bearer <token>. Only a200whose body hasuser.emailbecomes 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.
POST {origin}/api/auth/device/codewith{client_id, scope}. The client id is--client-id,$BRAVEN_CLIENT_ID, orbraven-cli; the scope isopenid profile email.- Print the
user_codeand openverification_uri_complete ?? verification_urithrough the sameBrowserseam. - Poll
POST {origin}/api/auth/device/tokenwith the RFC 8628 grant (grant_type,device_code,client_id) on aScheduleseeded from the server'sinterval.authorization_pendingkeeps polling;slow_downadds five seconds to every subsequent interval.expired_token,access_deniedandinvalid_grantstop with one actionable line. - The whole wait is bounded by
expires_in(30 minutes when omitted) throughEffect.timeoutOrElse. - On success
access_tokenis a better-auth session token: prove it withGET /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-dataThe 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