Metadata-Version: 2.4
Name: botrelay-cli
Version: 0.1.2
Summary: Command-line client for BotRelay agent and human vaults
Author: BotRelay
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://botrelay.ai
Project-URL: Documentation, https://github.com/chouseknecht/botrelay/tree/main/apps/cli#readme
Project-URL: Repository, https://github.com/chouseknecht/botrelay
Keywords: botrelay,secrets,vault,cli,zero-knowledge
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: botrelay==0.1.0
Dynamic: license-file

# botrelay-cli

Command-line client for [BotRelay](https://botrelay.ai). 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. Install the CLI on its own. `botrelay-mcp` is deprecated (the local daemon was removed) and is not required:

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

From a monorepo checkout:

```bash
python -m pip install -e packages/sdk-python
python -m pip install -e apps/cli
```

`botrelay-cli` 0.1.2 is the release the deprecated `botrelay-mcp` package depends on (`botrelay-cli>=0.1.1,<0.2`). Maintainer commands are at the bottom of this file. This change does not publish to PyPI.

## Agent onboarding

```bash
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:

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

and a normal dotenv parse. The CLI reads `BOTRELAY_API_URL`, `BOTRELAY_API_KEY`, and `BOTRELAY_VAULT_KEY`. It does not execute the file.

**Precedence for `botrelay agent` commands:** explicit flags (`--api-url`, `--api-key`, `--vault-key`), then `agent.env`, then the process environment. A value set in the file wins over the process environment. The process environment is used only for a key the file omits. Human commands do not read `agent.env`. A manual `source` follows normal shell rules and will assign over current variables. Hosted MCP does not read this file; it uses the agent API key on the request. The vault key stays local.

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

```bash
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.

```bash
botrelay agent vault
botrelay agent list
botrelay agent get github
```

`botrelay agent get` still fetches one secret by label and opens it locally. Its flags and output are unchanged. Credential loading is the shared rule above (file wins over the process environment).

### `botrelay agent decrypt`

Opens a sealed secret on this machine. It does not call the API. It reads JSON from stdin, or from a file path (`-` is stdin):

```bash
botrelay agent decrypt < secret.json
botrelay agent decrypt secret.json
```

Pipe hosted MCP `get_secret` output straight in. The command accepts:

- the sealed row (`id`, `vault_id`, `label`, `secret_type`, `ciphertext`, `nonce`, …)
- an MCP tool result (`structuredContent`, or `content[0].text` containing that JSON)
- a JSON-RPC envelope whose `result` is one of those

Stdout is the same typed JSON `botrelay agent get` prints:

- password: `username`, `password`, `label`, `secret_type`
- api_key: `key`, `id`, `label`, `secret_type`
- contact: the contact fields, plus `label` and `secret_type`

The vault key comes from `--vault-key`, otherwise `agent.env`, otherwise `BOTRELAY_VAULT_KEY`. A missing key, a key that is not 32-byte standard base64, malformed JSON, a row missing ciphertext fields, or a failed open prints `{"error": "..."}` on stderr and exits non-zero. A `vault_key` field inside the JSON is ignored.

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.

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

`botrelay-mcp` 0.3.0 is a deprecated tombstone (daemon removed). Do not publish it as a supported server. If a maintainer still uploads the tombstone so old installs resolve:

```bash
python -m build apps/mcp
twine check dist/botrelay_mcp-0.3.0*
twine upload dist/botrelay_mcp-0.3.0*
```

There is no publish job in CI.
