brain

CLI for the brain — upload content, list workspaces, manage your token.

Install

npm install -g substantial-brain-cli

Requires Node.js 18+.

Quick start

brain login                              # save your API token
brain whoami                             # confirm the token
brain workspaces                         # list workspaces in your org
brain upload notes.md                    # upload a single file
brain upload docs/                       # upload a folder of supported content
brain upload call.vtt                    # upload a transcript
brain upload docs/ --workspace Atlas     # assign uploads to a workspace
brain upload docs/ --workspace Atlas --create-workspace

Generate an API token at https://substantial-brain.vercel.app/settings/connections.

Commands

brain login

Prompts for an API token, verifies it against https://substantial-brain.vercel.app, and writes credentials to ~/.config/brain/config.json (mode 0600).

Override the config location with BRAIN_CONFIG=/path/to/config.json or XDG_CONFIG_HOME.

brain whoami

Prints the email and organization the saved token belongs to. Useful for confirming you're pointed at the right brain instance.

brain workspaces

Lists every workspace in your organization, alphabetically. Archived workspaces are tagged [archived].

brain upload <path...> [opts]

Uploads one or more content files. Directories are walked recursively; any file that looks like text is uploaded, regardless of extension. Binary-looking files are skipped. Hidden files and directories (anything starting with .) are skipped during recursion — pass them explicitly to upload anyway.

The server infers each upload's content kind from the filename and body. Ordinary text/markdown uploads become documents; transcript-shaped uploads such as .vtt, .srt, or files with transcript in the name become transcripts.

Re-uploading an unchanged file is a no-op. Re-uploading a changed file (same filename, same workspace) replaces the previous version.

Options:

• --workspace <name> — assign the uploaded content to this workspace. Workspace lookup is by name.
• --create-workspace — create the workspace if it doesn't already exist. Requires --workspace.

Path identity: the server deduplicates by (workspace, filename). The CLI normalizes typed paths so that docs, docs/README.md, and ./docs/README.md all map to the same upload name (docs/README.md), regardless of invocation style.

License

Proprietary. © Substantial.