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

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

go install github.com/getblenau/cli@latest

This 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.)

Staying up to date

blenau update          # update in place, or print exactly how to
blenau update --check  # only report current-vs-latest

An outdated binary fails in a misleading way: a command added in a later release reports unknown command, which reads as “this feature does not exist” rather than “I am behind”. So the CLI volunteers the fact through whichever channel you are actually reading:

Interactive terminal — a one-line notice on stderr after a command runs.
unknown command / unknown flag errors — the error names your version and the newer one, so a missing capability is never mistaken for an absent one. Only these errors carry it; everything else has its own explanation.
blenau --agent-manifest — an update object next to version:
```
{ "version": "0.14.0", "update": { "latest_version": "v0.16.0", "stale": true } }
```
The object is omitted when the check is disabled or GitHub is unreachable. Absent means unknown, never up to date.

The check hits GitHub at most once a day (cached, 2s timeout) and fails silently when offline. Set BLENAU_NO_UPDATE_CHECK=1 to switch off all three.

A binary built from source rather than installed from a release reports version 0.0.0-dev and is never flagged as stale — it is ahead of every release, not behind one. It still reports latest_version, so you can see what the current release is.

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?

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

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

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.
`blenau access`	Admit your own people to a workspace someone delegated to you — see Delegated access.
`blenau delegation`	Owner side: who you delegated to, what they did with it, and their allowance.

Run blenau <command> --help for full flags, or blenau --agent-manifest for a machine-readable contract of the whole CLI surface.

Output

Human-readable by default in a terminal; JSON when piped or with --json.
Output is UTF-8 NFC on Linux, macOS and Windows.