CLI reference
Every command and flag, the environment variables, and the exit codes.
You mostly do not need this page. Run brainlyy with no arguments and it
opens the dashboard, where setup, connecting sources and writing claims all
live. The commands below exist for scripting and for people who prefer them.
Every command reads its instance from $BRAINLYY_HOME, defaulting to
~/.brainlyy. Set that variable to run more than one instance on a machine.
brainlyy init
Set up an instance: write config, generate secrets, render templates, register with your MCP client, and verify.
brainlyy init
| Flag | Does |
|---|---|
--force |
Overwrite an existing config and rotate tokens. Rotating breaks every registered client. |
--no-register |
Skip registering with the MCP client. Use in CI. |
Asks three questions, all defaulted; a non-interactive shell takes every default. Finishes by running the property suite and refuses to report success if it fails.
Safe to re-run. Existing tokens are never regenerated and existing SOULs are never overwritten, because they get hand-edited and those edits matter.
brainlyy doctor
What works, what is missing, and what the next tier would add.
brainlyy doctor
Probes every dependency rather than reading config, so the result reflects the machine rather than your intent. Never raises: a failed probe means absent.
brainlyy connect
Pair this machine with the web app, then answer for it.
brainlyy connect A7K2QM94 # pair, then stay connected
brainlyy connect # reconnect a machine already paired
| Flag | Does |
|---|---|
--url URL |
Control plane to pair with. Defaults to the hosted one. |
--pair-only |
Pair and exit, instead of staying connected. |
The connection is dialled out from here. Nothing on this machine is exposed, no port is opened, and the control plane cannot reach in. It can only answer on a connection this machine chose to make. That is why it works behind NAT, on hotel wifi, and on a laptop that moves.
Only /api/ paths are relayed, and only read methods, unless
ui.remote_writes is set. See Security.
brainlyy verify
Re-check every claim in your vault and record what was observed.
brainlyy verify
brainlyy verify --strict # in CI
| Flag | Does |
|---|---|
--strict |
Exit 1 if any claim is unverified. For CI. |
--json |
Machine-readable output. |
--dry-run |
Classify without running any check. |
Prints only what needs attention, since verified claims are the boring case, then a count, and how long the longest-lived false claim read VERIFIED before a run caught it.
The status is computed here and nowhere else. A note declares a claim and the evidence it rests on; it never says how it is doing. See Claims.
brainlyy ui
Open the dashboard in a browser.
brainlyy ui
| Flag | Does |
|---|---|
--no-open |
Start the server without launching a browser. |
--print-url |
Print the one-time authenticated URL and exit. |
Binds loopback unless ui.bind: mesh is set. Write controls render only when
the request arrived on 127.0.0.1; see Security.
brainlyy passphrase
Set the passphrase that signs in to the dashboard at /login.
brainlyy passphrase
| Flag | Does |
|---|---|
--stdin |
Read the passphrase from stdin instead of prompting. For scripts; nothing is echoed either way. |
Prompts twice without echo and refuses anything under 10 characters. Stores
an scrypt hash in passphrase.json, never the passphrase itself. Session
and lockout details live in Security.
brainlyy serve
Run a server in the foreground.
brainlyy serve # read server, binds hosts.brain_mesh_ip
brainlyy serve --write # write server, binds 127.0.0.1 only
The write server exits at startup if its bind address is not loopback. That is an exit code, not a preference.
brainlyy search
Query your notes without a browser.
brainlyy search on-ramp fee
brainlyy search --limit 12 settlement
| Flag | Does |
|---|---|
--limit N |
Maximum excerpts to return. Default 6. |
Works at tier 0 over plain markdown, with no vector store running.
brainlyy docs
Build the documentation site.
brainlyy docs # where the markdown lives
brainlyy docs --build --open # render it and open it
brainlyy docs --build --output ~/brainlyy.html # somewhere specific
| Flag | Does |
|---|---|
--build |
Render docs/*.md into one page. Without it, docs only reports where the sources are. |
--open |
Open the result in a browser. |
--output PATH |
Where to write it. Default ./brainlyy-docs.html. Never into docs/, which stays pure markdown, and never into the install, which is not a build target. |
Output is self-contained: the stylesheet and both fonts are inlined, so it reads identically offline. The markdown ships inside the wheel, so this works on a machine that has never seen the repository.
Environment variables
| Variable | Effect |
|---|---|
BRAINLYY_HOME |
Where config, secrets and instance data live. Default ~/.brainlyy. |
BRAINLYY_CONFIG |
Path to a specific config file, bypassing discovery. |
BRAINLYY_READ_HOST / BRAINLYY_READ_PORT |
Override the read server's bind. |
BRAINLYY_READ_TOKEN |
Override the read token. |
BRAINLYY_WRITE_HOST / BRAINLYY_WRITE_PORT |
Override the write server's bind. Non-loopback hosts are refused. |
BRAINLYY_WRITE_TOKEN |
Override the write token. |
Exit codes
0 success · 1 a check failed and the reason was printed · a SystemExit
message on startup means a boundary refused, not a crash.