Documentation

behalf CLI

Install the BehalfID CLI to manage agents, verify actions, enforce permissions via MCP, and launch AI tools with enforcement active.

Install

The CLI ships as a self-contained binary. No Node.js required after install.

curl (macOS / Linux)

curl -fsSL https://behalfid.com/install.sh | sh

Homebrew

brew install potatobeyonddefeat/tap/behalf

npm

npm install -g @behalfid/cli

Verify the install:

terminal

behalf --version

Setup wizard

Run behalf init to walk through base URL, authentication, and API key configuration interactively.

terminal

behalf init

The wizard stores config at ~/.behalf/config.json and session at ~/.behalf/session.

Auth

terminal

behalf login         # log in with email and password
behalf whoami        # show current authenticated user
behalf logout        # clear the session

Agents

terminal

behalf agents list
behalf agents create --name "My Bot"
behalf agents create --name "Ollie" --type connected --provider ollie --save

Pass --save to write the new agent ID and API key directly to ~/.behalf/config.json. The API key is only returned once.

Permissions

terminal

behalf permissions create agent_xxx \
  --action access_data \
  --resource gmail.com \
  --allowed "read labels,summarize messages" \
  --blocked "send email,delete messages" \
  --requires-approval

behalf permissions create agent_xxx \
  --action purchase \
  --resource amazon.com \
  --max-amount 50 \
  --template purchase

Verify an action

Use behalf verify to run a one-off action check. The command exits with code 0 on allow and 1 on deny — safe to use in scripts.

terminal

behalf verify agent_xxx --action browse_web --vendor web
behalf verify agent_xxx --action purchase --vendor amazon.com --amount 25

Pass --json to get machine-readable output. The exit code still reflects the allow/deny decision.

terminal

behalf --json verify agent_xxx --action purchase --vendor amazon.com --amount 100

denied response

{
  "requestId": "req_xxx",
  "allowed": false,
  "reason": "Amount exceeds the maximum permitted for this permission.",
  "risk": "high"
}

Logs

terminal

behalf logs agent_xxx

MCP enforcement

BehalfID ships a Model Context Protocol (MCP) server that makes real-time verify_action and get_permissions available to any AI tool that supports MCP. Run behalf mcp init once per project to wire it in.

terminal

behalf config set agent-id agent_xxx
behalf config set api-key bhf_sk_xxx
behalf mcp init

mcp init writes two files to the current directory:

.mcp.json — registers the behalfid MCP server (merged with any existing config)
.behalf/context.md — a markdown brief of the agent's active permissions

If a CLAUDE.md or AGENTS.md file is present, the CLI offers to append @.behalf/context.md so the AI tool loads the context automatically on startup.

.mcp.json

{
  "mcpServers": {
    "behalfid": {
      "type": "stdio",
      "command": "behalf",
      "args": ["mcp", "start"]
    }
  }
}

The MCP server exposes get_permissions for inspection and verify_action for enforcement. The context file instructs the AI to call verify_action before risky or permissioned actions, stop on denied decisions, fail closed if verification is unavailable, and pause when approval is required.

terminal

behalf mcp status           # show config and cached permissions for this directory
behalf mcp init --refresh   # force-refresh the permissions cache from the server
behalf mcp init --dry-run   # preview what would be written without writing
behalf doctor               # diagnose CLI and MCP setup

Launch AI tools with enforcement

The behalf claude, behalf codex, and behalf run commands fetch the latest permissions, write .behalf/context.md and .mcp.json, and then launch the tool — so enforcement is always current when the session starts. The launcher prints the agent, base URL, context file, MCP config, and command it is about to run. It does not print API keys.

terminal

behalf claude              # launch Claude Code with enforcement active
behalf codex               # launch Codex CLI with enforcement active
behalf run cursor          # launch Cursor with enforcement active
behalf claude --resume     # pass extra flags straight through to the tool

For a runnable local walkthrough with allowed, denied, and approval-required examples, see docs/MCP_DEMO.md.

Config

terminal

behalf config set api-key bhf_sk_xxx
behalf config set agent-id agent_xxx
behalf config set base-url https://behalfid.com
behalf config get api-key
behalf config list

Global --json flag

Add --json before any subcommand to get machine-readable output. Errors are also emitted as JSON. Works with every command.

terminal

behalf --json agents list
behalf --json verify agent_xxx --action purchase -v amazon.com