الصفحات · Zekra

CLI

Install the zekra CLI, log in, connect MCP clients, manage brains and tokens, use hooks, and install the Claude Code plugin.

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

It is the MCP server (zekra mcp), a stdio adapter over the Zekra REST API.
It wires that server into MCP clients (zekra mcp:install <client>).
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):

$ npm i -g zekra-cli

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:

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.

text

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.