Command line
The lorca CLI holds your keys and runs your bots. The desktop app is a window onto it, and a Runner needs nothing else.
lorca 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/lorca.
Install
On an Apple silicon Mac or a Linux computer without the app:
curl -fsSL https://usebeans.app/install-cli.sh | shOn Windows, in PowerShell:
irm https://usebeans.app/install-cli.ps1 | iexThe script downloads the latest release for your computer, checks it against the release's checksums, puts lorca in ~/.local/bin, and adds that folder to your PATH. Run it again to update; a running lorca serve keeps the old version until it restarts.
Set LORCA_VERSION=1.0.0 to install that release, LORCA_INSTALL_DIR to put lorca in another folder, or LORCA_NO_MODIFY_PATH=1 to leave your PATH alone: curl -fsSL https://usebeans.app/install-cli.sh | LORCA_VERSION=1.0.0 sh, or $env:LORCA_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
| Command | What it does |
|---|---|
lorca | Lists the commands. |
lorca serve | Runs the service. |
lorca identity new | Creates an identity and prints the backup phrase. |
lorca identity restore <phrase> | Restores an identity from its phrase. |
lorca identity show | Shows this device's identity. |
lorca pair | Shows a pairing string and waits for the other device. |
lorca pair <string> | Joins an account with a pairing string. |
lorca provider set <kind> [api-key] | Connects deepseek, anthropic, opencode, opencode-go, chatgpt, or grok. The key is read from stdin when omitted; --base-url sets a custom endpoint. |
lorca 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. |
lorca provider remove <kind> | Disconnects a provider on every device, or deletes a custom one (custom:openrouter, as provider list shows it). |
lorca provider list | Lists the connected providers. |
lorca mcp … | Manages this computer's own MCP servers; see MCP servers. |
lorca chats list | Lists the chats: each one's id and bots, with a group's owner. |
lorca 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. |
lorca marketplace reload | Checks lorca.app for a newer marketplace now. Beans also checks on its own when it starts, when an app connects, and when you or a bot look through the marketplace, at most once an hour, so new plugins and bots arrive without an update. |
lorca models reload | Checks lorca.app for a newer model catalog now. Beans also checks on its own when it starts and when an app connects, at most once an hour, so new models arrive without an update. |
lorca status | Prints this device's state as JSON: devices, bots, chats, providers. |
lorca doctor | Checks the home folder, identity, port, relay, and mcp.json, and says what is wrong. |
MCP servers
lorca mcp edits mcp.json in Beans's folder, the MCP servers every bot on this computer can use. With lorca serve running, the change reaches it at once; without it, the next lorca serve reads the file. After editing the file by hand, run lorca mcp reload.
| Command | What it does |
|---|---|
lorca mcp list | Lists the servers and how each stands: its tools, a sign-in it needs, or why it did not start. Without lorca serve running, it connects each one first. It exits with 1 when a server needs attention. |
lorca mcp get <name> | Connects a server and shows its settings and tools. |
lorca 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. |
lorca mcp add <name> <url> | Adds a remote server that speaks streamable HTTP. -H "Name: value" adds a header, before or after the URL. |
lorca mcp add-json <name> <json> | Adds a server from its JSON, as a README or another app's config writes it. |
lorca mcp remove <name> | Removes a server, with its sign-in. |
lorca mcp enable <name>, disable <name> | Turns a server on or off. Off, bots don't see it and it never starts. |
lorca mcp sign-in <name> | Signs in to a remote server that asks for it, in this computer's browser. |
lorca mcp sign-out <name> | Forgets a remote server's sign-in. Its next use asks for one again. |
lorca mcp reload | Has the running lorca serve read mcp.json again, after you edit the file by hand. |
lorca 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_*. |
lorca 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. |
lorca mcp add notes npx -y @modelcontextprotocol/server-filesystem ~/Notes
lorca mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_… docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
lorca mcp add linear https://mcp.linear.app/mcp
lorca 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 LORCA_RELAY_URL=https://relay.example.com
lorca pair 'lorca://pair?…' # from Pair a Device… or `lorca pair` on an existing Device
lorca serveThe computer shows up in your Device list, and you can create bots for it from the desktop app or your phone.
Environment
| Variable | What it sets |
|---|---|
LORCA_HOME | Where keys, credentials, and chats live. Default ~/.lorca. |
LORCA_PORT | The local port the app connects to. Default 4862. |
LORCA_RELAY_URL | The relay. |
LORCA_SHELL | The 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. |
LORCA_DEEPSEEK_MODEL, LORCA_ANTHROPIC_MODEL, LORCA_CHATGPT_MODEL, LORCA_GROK_MODEL | The default model for bots that do not pick one. |
LORCA_MODELS_URL | Where Beans checks for a newer model catalog. Default https://lorca.app/models/v1.json; LORCA_MODELS_FETCH=0 turns the checks off. |
LORCA_MARKETPLACE_URL | Where Beans checks for a newer marketplace. Default https://lorca.app/marketplace/v1.json; LORCA_MARKETPLACE_FETCH=0 turns the checks off. |
Files
Everything is under ~/.lorca/, readable only by your user: your identity and machine keys, provider credentials, settings, chats, attachments, plugins, your MCP servers in mcp.json, the last model catalog fetched in catalog.json, the last marketplace fetched in marketplace.json, and one workspace folder per bot with its memory.
The macOS app logs the service to ~/Library/Logs/Beans/cli.log.