CLI

zekra is a single binary with no dependencies. It does three jobs:

1. It is the MCP server (zekra mcp), a stdio adapter over the Zekra REST API.
2. It wires that server into MCP clients (zekra mcp:install <client>).
3. It drives Zekra from the shell: brains, tokens, recall and retain.

Source: github.com/fadymondy/zekra-cli (MIT).

Install

Install script (macOS, Linux; Windows through Git Bash or WSL):

npm (Node 16 or later; downloads the native binary for your platform):

Go:

The install script puts zekra in /usr/local/bin if it can write there, and otherwise in ~/.local/bin. If it cannot download a prebuilt binary, it builds from source with go install. It reads these optional variables:

Variable	Meaning
ZEKRA_URL	Endpoint to log in to (default https://app.zekra.dev)
ZEKRA_TOKEN	If set, runs zekra auth login for you
ZEKRA_CLIENT	claude-desktop, claude-code, codex, gemini or cursor: runs zekra mcp:install for you
ZEKRA_BIN_DIR	Install directory
ZEKRA_VERSION	Release tag (default latest)

Install, log in and connect a client in one line:

Upgrade

The upgrade script detects whether you installed with npm, Go or the binary installer and updates in place. There is no zekra upgrade subcommand. Check your version with zekra version.

Log in

This saves the endpoint and token to ~/.zekra/config.json and pings the server to check that it is reachable. Get a token from the console (see Quickstart) or from an admin. auth login takes a token. It does not open a browser sign-in flow.

Flag	Meaning
--url URL	Zekra endpoint (default https://app.zekra.dev; use your own for self-hosting)
--token TOKEN	Access token (cbt_…)
--agent ID	Agent label sent as X-Agent-Id
--brain NS	Default brain for recall, retain and the MCP session

Configuration is resolved in this order, highest first: flags, then environment variables (ZEKRA_API_URL, ZEKRA_TOKEN, ZEKRA_AGENT_ID, ZEKRA_DEFAULT_NAMESPACE), then ~/.zekra/config.json. Legacy CABRAIN_* names are also read.

Command reference

Colon and space forms are the same command: zekra mcp:install is zekra mcp install.

Auth

Command	What it does
zekra auth login [--url U] [--token T] [--agent ID] [--brain NS]	Save credentials and check reachability
zekra auth logout	Remove the saved token (the endpoint is kept)
zekra auth whoami	Show the endpoint and the brains your token can reach
zekra auth token new <agentId> [--admin] [--brain NS]	Mint a token (needs an admin token), optionally granting it a brain
zekra auth token list	List tokens and their grants (admin)

Top-level shortcuts: zekra login, zekra logout, zekra status (also whoami, ping) and zekra token.

MCP

Command	What it does
zekra mcp	Run the stdio MCP server. Clients launch this.
zekra mcp:install <client> [--brain NS] [--name N] [--user]	Add Zekra to a client's MCP config
zekra mcp:print <client> [--brain NS]	Print the config snippet without writing anything
zekra mcp:uninstall <client> [--name N]	Remove the Zekra entry from a client

--brain sets ZEKRA_DEFAULT_NAMESPACE for the session. --name changes the server entry name (default zekra), so you can install several entries bound to different brains. --user applies to Claude Code only: it writes ~/.claude.json instead of the project's .mcp.json. zekra install <client> is a shortcut for mcp:install.

Client	File written	Format
claude-code	./.mcp.json, or ~/.claude.json with --user	JSON
claude-desktop	claude_desktop_config.json in the Claude config directory (macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\, Linux ~/.config/Claude/)	JSON
codex	~/.codex/config.toml, table [mcp_servers.zekra]	TOML
gemini	~/.gemini/settings.json	JSON
cursor	~/.cursor/mcp.json	JSON
print	stdout only	JSON

Installs merge into the existing file and keep your other MCP servers. They are idempotent: running the command again replaces only the Zekra entry. The entry points at the absolute path of the zekra binary you ran, with your endpoint and token in its env block.

Brains and memory

Command	What it does
zekra brain list	List the brains you can read
zekra brain create <name> [--description D] [--token]	Create a brain. With --token, also mint a non-admin token that can read and write only this brain, and print a ready-to-share MCP snippet (needs an admin token).
zekra brain delete <name> --confirm	Delete a brain and all of its memories
zekra recall <brain> <query...> [--limit N]	Hybrid recall
zekra retain <brain> <content...>	Store a memory

Example:

Hooks

zekra hook reads Claude Code hook JSON on stdin and prints context to inject. Hooks fail open: on any error they print nothing and never block the session.

Command	Hook event	What it does
zekra hook rules (alias session-start)	SessionStart	Injects the recall, answer, retain rules. On by default; set ZEKRA_HOOK_RULES=0 to turn it off.
zekra hook recall (alias user-prompt)	UserPromptSubmit	Recalls the top memories for each prompt from your default brain and injects them. Opt-in: set ZEKRA_HOOK_AUTORECALL=1 and a brain in ZEKRA_AUTORECALL_BRAIN (or ZEKRA_DEFAULT_NAMESPACE, or the saved config).

To use the hooks without the plugin, add them to your Claude Code settings.json:

Writing to the brain stays model-driven on purpose, so that stored memories are selective and distilled. For automatic capture of turns, see the capture hook.

Other

Command	What it does
zekra version	Print the version
zekra help	Print usage

Claude Code plugin

The CLI repository is also a Claude Code plugin. It bundles the MCP server, slash commands, two agents, a skill and the hooks above.

The plugin needs the zekra binary on your PATH, because its MCP server runs zekra mcp. When you enable it, Claude Code asks for these settings:

Option	Meaning
api_token (required)	Your Zekra token
api_url	Endpoint (default https://app.zekra.dev)
default_namespace	Bind the session to one brain
auto_recall	Turn on the auto-recall hook (default off)
inject_rules	Inject the memory-first rules at session start (default on)

What it adds:

Kind	Name	What it does
command	/zekra:recall [brain] <query>	Recall and answer from memory
command	/zekra:retain [brain] <content>	Store a memory
command	/zekra:brains [name]	List brains, or show one brain's details
command	/zekra:new-brain <name>	Create a brain
command	/zekra:connect [client]	Wire the MCP server into another client
command	/zekra:status	Endpoint and reachable brains
command	/zekra:doctor	Check that the CLI is installed and current, you are logged in, and the MCP server responds
agent	zekra-curator	Memory-first Q&A: recall, answer, retain
agent	zekra-connector	Setup: install, tokens, brains, data sources
skill	memory-first	The recall, answer or act, retain routine
hook	SessionStart	Runs zekra hook rules
hook	UserPromptSubmit	Runs zekra hook recall (opt-in)

There is no zekra doctor shell command. Diagnostics are the /zekra:doctor slash command.