CLI
blenau is an agent-first command-line client for the Blenau API: search, repos,
docs, ingest, section edits and asset uploads. Every command supports --json,
and --agent-manifest emits the full command contract for tooling discovery.
Install
Section titled “Install”Download a release (recommended)
Section titled “Download a release (recommended)”Grab the archive for your platform from the
latest release, extract the
blenau binary and put it on your PATH.
Prebuilt binaries: macOS (Intel & Apple Silicon), Linux (amd64 & arm64), Windows (amd64).
With Go
Section titled “With Go”go install github.com/getblenau/cli@latestThis builds the latest released version. Note: go install names the binary
after the module path (cli); rename it to blenau if you want that command
name. (The release archives are already named blenau.)
Log in
Section titled “Log in”The CLI supports both auth paths — pick the one that fits:
blenau login # browser login (most secure for a person)blenau login --token blenau_tk_… # service token (best for CI/automation)blenau login opens a browser sign-in (OAuth device flow). Your refresh token
is stored in the OS keychain — never in a file — and short-lived access tokens
are rotated automatically. blenau login --token saves a blenau_tk_ to a
0600 config file; you can also set BLENAU_API_TOKEN (and BLENAU_API_URL)
via environment variables.
blenau whoami shows who you are, blenau status shows the current lane and
active workspace, and blenau logout revokes and clears the browser session.
Which authentication should I use?
Section titled “Which authentication should I use?”| Path | Best for | Notes |
|---|---|---|
Browser login (blenau login) | An interactive human — the most secure choice | Refresh token in the OS keychain (not a file); short-lived, rotated access tokens. |
Service token (blenau login --token / BLENAU_API_TOKEN) | Automation & CI | A long-lived blenau_tk_. Inject it from a secret manager rather than hard-coding it. |
Rule of thumb: a token is the right tool for anything unattended (CI, cron, scripts) — keep it in a secret manager. For an interactive human session, prefer the keychain-backed browser login.
Working across workspaces
Section titled “Working across workspaces”With a browser login your identity can span several workspaces. blenau workspaces lists them; blenau use <slug> sets the active one (where writes
go); --workspace <slug> targets one for a single command. Writing to a
workspace other than the active one asks for confirmation — in scripts, pass
--confirm-workspace <slug> (there’s no blanket “yes”). See
Working across workspaces. A service token is always pinned
to its one workspace.
Commands
Section titled “Commands”| Command | What it does |
|---|---|
blenau search <query> | Semantic search across your workspace. |
blenau workspaces | List the workspaces your identity can reach — see Working across workspaces. |
blenau repos | List connected repos and their path_prefix. |
blenau docs | List / inspect documents. |
blenau docs delete --path <p> | Delete a WHOLE document — its file on GitHub and its index. Resolves an exact path (never a glob), echoes what it resolved, and asks you to re-type the path (or pass --yes). --dry-run previews. |
blenau concept | Print Blenau’s mental model — the three tiers and how grouping works. |
blenau ingest --path <p> --title <t> | Create a document (content from --content-file or stdin). |
blenau edit-section … | Edit a section with optimistic locking. |
blenau assets upload <file> --doc <path> | Upload an image/file to a doc — see Images & assets. |
blenau audit | Audit the cross-link graph. |
Run blenau <command> --help for full flags, or blenau --agent-manifest for a
machine-readable contract of the whole CLI surface.
Output
Section titled “Output”- Human-readable by default in a terminal; JSON when piped or with
--json. - Output is UTF-8 NFC on Linux, macOS and Windows.