BeansDocs

Command line

The beans CLI holds your keys and runs your bots. The desktop app is a window onto it, and a Runner needs nothing else.

beans is the program that does the work: it holds your keys, talks to the relay and the AI providers, and runs the bots. It runs on macOS, Linux, and Windows. The desktop app bundles it and runs it for you; on a computer without the app, run the CLI yourself and that computer is a Runner.

On macOS, the bundled binary lives inside the app at Beans.app/Contents/Resources/bin/beans.

Fresh accounts use format beans-v2, home ~/.beans-v2 and port 4874 (Dev: ~/.beans-dev-v2, 4875). Backups start with the separate first token beans-v2, followed by thirteen base32 groups. Restore rejects unversioned/wrong-prefix phrases before decoding. Old account directories and mixed-format pairing/sync are incompatible and are not automatically migrated or reset. The relay requires Beans-Protocol: 5 and Beans-Format: beans-v2; use your own configured relay, not a built-in production host.

Install

On an Apple silicon Mac or a Linux computer without the app:

curl -fsSL https://usebeans.app/install-cli.sh | sh

On Windows, in PowerShell:

irm https://usebeans.app/install-cli.ps1 | iex

The script downloads the latest Beans release for your computer, checks its adjacent checksum, puts beans in ~/.local/bin, and adds that folder to PATH. CLI self-update is unavailable.

Set BEANS_VERSION=1.0.0 to install that release, BEANS_INSTALL_DIR to put beans in another folder, or BEANS_NO_MODIFY_PATH=1 to leave your PATH alone: curl -fsSL https://usebeans.app/install-cli.sh | BEANS_VERSION=1.0.0 sh, or $env:BEANS_VERSION = '1.0.0' before irm in PowerShell.

On Windows, bots run their commands in Git for Windows' bash, not WSL's, so install Git for Windows too. Beans finds it in Program Files, in an install for your user only, or through git on your PATH; until it is installed, a bot's commands fail with a note that says so.

Commands

CommandWhat it does
beansLists the commands.
beans serveRuns the service.
beans identity newCreates an identity and prints the backup phrase.
beans identity restore <phrase>Restores an identity from its phrase.
beans identity showShows this device's identity.
beans pairShows a pairing string and waits for the other device.
beans pair <string>Joins an account with a pairing string.
beans provider set <kind> [api-key]Connects deepseek, anthropic, opencode, opencode-go or chatgpt. Production grok OAuth is disabled pending a verified Beans contract. The key is read from stdin when omitted; --base-url selects an API endpoint.
beans provider add <name> <base-url>Adds a custom provider: any server that speaks OpenAI's or Anthropic's API. --api picks chat-completions (the default), responses, or messages; --model names a model, once per model; --api-key-stdin reads a key.
beans provider remove <kind>Disconnects a provider on every device, or deletes a custom one (custom:openrouter, as provider list shows it).
beans provider listLists the connected providers.
beans mcp …Manages this computer's own MCP servers; see MCP servers.
beans chats listLists the chats: each one's id and bots, with a group's owner.
beans chats set-owner <group> <bot>Makes a bot the owner of a group. Name the group by its title or id, and the bot by its name or id.
beans marketplace reloadChecks the selected Beans relay's public marketplace feed now, with a bundled offline fallback.
beans models reloadChecks the selected Beans relay's public model catalog now, with a bundled offline fallback.
beans update status|prepare|cancelControls the running Runner's admission drain. Prepare/cancel require BEANS_UPDATE_TOKEN_FILE; no release is downloaded.
beans self-updateReports unavailable in Beans; use the signed Beans update mechanism.
beans service installRuns beans serve in the background, now and at every login, and starts it again if it stops. beans service uninstall stops it; beans service status says whether it runs and where its log is.
beans statusPrints this device's state as JSON: devices, bots, chats, providers.
beans doctor [--json]Reports privacy-safe setup evidence: versions, relay health, configured credentials, cached plugin setup and Runner presence. --json exports the same report. It discloses relay host/port, not keys, names, paths or messages. If account loading fails, it exits nonzero with no report and a fixed error on stderr, omitting startup logs and private error details; check storage access and account format locally. Review before sharing; nothing is uploaded. Provider health is not checked.

MCP servers

beans mcp edits mcp.json in Beans's folder, the MCP servers every bot on this computer can use. With beans serve running, the change reaches it at once; without it, the next beans serve reads the file. After editing the file by hand, run beans mcp reload.

CommandWhat it does
beans mcp listLists the servers and how each stands: its tools, a sign-in it needs, or why it did not start. Without beans serve running, it connects each one first. It exits with 1 when a server needs attention.
beans mcp get <name>Connects a server and shows its settings and tools.
beans mcp add <name> <command> [args…]Adds a server this computer runs. Everything after the command is its arguments, flags included; -e KEY=value sets a variable, once per variable, before the command.
beans mcp add <name> <url>Adds a remote server that speaks streamable HTTP. -H "Name: value" adds a header, before or after the URL.
beans mcp add-json <name> <json>Adds a server from its JSON, as a README or another app's config writes it.
beans mcp remove <name>Removes a server, with its sign-in.
beans mcp enable <name>, disable <name>Turns a server on or off. Off, bots don't see it and it never starts.
beans mcp sign-in <name>Signs in to a remote server that asks for it, in this computer's browser.
beans mcp sign-out <name>Forgets a remote server's sign-in. Its next use asks for one again.
beans mcp reloadHas the running beans serve read mcp.json again, after you edit the file by hand.
beans mcp hide <name> <tool>, show <name> <tool>Keeps one of a server's tools from bots, or offers it again. The tool can be a pattern such as delete_*.
beans mcp import [file]Adds the servers from another app's config: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, or Gemini CLI, or the file you name.
beans mcp add notes npx -y @modelcontextprotocol/server-filesystem ~/Notes
beans mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_… docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
beans mcp add linear https://mcp.linear.app/mcp
beans mcp add-json time '{"command": "uvx", "args": ["mcp-server-time"]}'

--description tells bots what a server is for, and --timeout how many seconds a call may go without an answer. add connects the server once it is saved and says whether it started.

A headless Runner

export BEANS_RELAY_URL=https://relay.example.com
beans pair 'beans://pair?v=2&…'   # from Pair a Device… or `beans pair` on an existing Device
beans service install

The computer shows up in your Device list, and you can create bots for it from the desktop app or your phone. beans service install keeps beans serve running: a launch agent on macOS, a systemd user service on Linux, and a sign-in item on Windows. On Linux it also asks systemd to keep your services running after you log out; if that needs an administrator, it prints the sudo loginctl enable-linger command to run. In a container or anywhere else without systemd, run beans serve under your own init or in tmux.

Updates

CLI self-update is unavailable in Beans, including automatic, manual and remote Device requests. BEANS_SELF_UPDATE cannot enable it. Settings › Devices reports the core version without advertising this update path.

Beans desktop apps update their bundled CLI through signed Beans readiness. The configured server updater upgrades the relay first and uses beans update status|prepare|cancel to drain standalone Runners before replacement; these commands do not discover or download releases.

Environment

VariableWhat it sets
BEANS_HOMEWhere keys, credentials, and chats live. Default ~/.beans-v2.
BEANS_PORTThe local port the app connects to. Default 4874.
BEANS_RELAY_URLThe relay.
BEANS_SHELLThe shell bots run commands in. Default /bin/bash; on Windows, Git for Windows' bash. On macOS and Linux, commands get your login shell's PATH and variables either way.
BEANS_DEEPSEEK_MODEL, BEANS_ANTHROPIC_MODEL, BEANS_CHATGPT_MODEL, BEANS_GROK_MODELThe default model for bots that do not pick one.
BEANS_MODELS_URLExplicit model catalog override. Otherwise uses the selected relay’s /models/v1.json; BEANS_MODELS_FETCH=0 disables checks. No production host is guessed.
BEANS_MARKETPLACE_URLExplicit marketplace override. Otherwise uses the selected relay’s /marketplace/v1.json; BEANS_MARKETPLACE_FETCH=0 disables checks. Bundled catalogs remain available offline.

Files

Everything is under ~/.beans-v2/, readable only by your user: identity and machine keys, provider credentials, settings, chats, attachments, plugins, mcp.json, source-bound catalog.json and marketplace.json caches, and one workspace folder per bot with its memory. The disabled CLI updater does not create update.json.

The macOS Beans app logs the service to ~/Library/Logs/Beans/cli.log. Under beans service the log is ~/Library/Logs/Beans/serve.log on macOS, journalctl --user -u beans on Linux, and serve.log in the CLI home on Windows.

On this page