botrelay-cli

Command-line client for BotRelay. Humans sign up and manage vaults. Agents read secrets with an API key and a vault key that stay on this machine.

Decrypts locally. The API stores ciphertext only. The vault key is never sent to the API.

Install

Python 3.11 or newer. botrelay-mcp depends on this package, so one install in ~/.venvs/botrelay provides both console scripts:

python3 -m venv ~/.venvs/botrelay
source ~/.venvs/botrelay/bin/activate
python -m pip install --upgrade pip
python -m pip install botrelay-mcp

Or install the CLI on its own:

python -m pip install botrelay-cli

From a monorepo checkout (install the CLI before the MCP package, which depends on it):

python -m pip install -e packages/sdk-python
python -m pip install -e apps/cli
python -m pip install -e apps/mcp

botrelay-cli 0.1.0 is the first release of this package. It is not on PyPI yet. botrelay and botrelay-mcp 0.1.0 already are. Publish this package before botrelay-mcp 0.1.1 so the dependency resolves. Maintainer commands are at the bottom of this file.

Agent onboarding

botrelay agent configure

On a TTY this prompts for the API URL (default https://api.botrelay.ai), then the API key and vault key with hidden input. It writes:

~/.config/botrelay/agent.env

or $BOTRELAY_HOME/agent.env when BOTRELAY_HOME is set. The file is mode 0600. Secrets are not printed.

# BotRelay agent credentials. Do not commit.
BOTRELAY_API_URL='https://api.botrelay.ai'
BOTRELAY_API_KEY='brt_live_...'
BOTRELAY_VAULT_KEY='...'

That is KEY=VALUE (optional export, # comments, single quotes) so both of these work:

set -a; source ~/.config/botrelay/agent.env; set +a

and a normal dotenv parse. The CLI and apps/mcp/examples/launch.sh only import BOTRELAY_API_URL, BOTRELAY_API_KEY, and BOTRELAY_VAULT_KEY. They do not execute the file. Environment variables and flags override the file. A manual source follows normal shell rules and will assign over current variables. The Marketplace plugin is botrelay-ai/botrelay-plugin.

Non-interactive (CI or scripts; no TTY):

botrelay agent configure \
  --api-url https://api.botrelay.ai \
  --api-key "$BOTRELAY_API_KEY" \
  --vault-key "$BOTRELAY_VAULT_KEY"

--yes skips the overwrite prompt on a TTY. Without a TTY, a complete set of values overwrites an existing file.

--check calls the same vault-metadata read as botrelay agent vault and prints id, name, and labels only. It does not print secrets. botrelay agent configure --check with no new values verifies the current file or environment without rewriting it.

botrelay agent vault
botrelay agent list
botrelay agent get github

Human commands still default to http://localhost:8000 (or BOTRELAY_API_URL). They do not read agent.env.

Publish

From a checkout, after tests pass. This uploads to PyPI; do it from a maintainer machine that already has credentials. Do not commit tokens.

python -m pip install --upgrade build twine
python -m build apps/cli
twine check dist/botrelay_cli-0.1.0*
twine upload dist/botrelay_cli-0.1.0*

Then publish botrelay-mcp 0.1.1, which depends on botrelay-cli>=0.1.0,<0.2:

python -m build apps/mcp
twine check dist/botrelay_mcp-0.1.1*
twine upload dist/botrelay_mcp-0.1.1*

There is no publish job in CI.