Docs · CLI

Beehaven CLI

Beehaven is the command-line interface to your Clearly agent cloud — one command line for every agent and workspace you own. You connect to a target, then run actions, manage memory, and query state against it. This page is the command reference.

Install & access

One line, any OS. It installs the CLI and its daemon, so you get the whole workspace — canvas, agents, files, memory — without the desktop app.

curl -fsSL https://clearly.sh/install.sh | sh

Requires Node.js 20+. Beehaven is a Node program, not a static binary, and it has native dependencies (a pty, SQLite) that need per-platform builds — the installer fetches a versioned tarball and lets npm resolve them, which is why Node is a real prerequisite rather than a detail. It installs to ~/.beehaven/cli and links ~/.local/bin/beehaven.

On macOS the desktop app (coming soon) bundles the CLI — sign in and it’s set up for your account, nothing to install.

beehaven login                 # sign in (browser OAuth)
beehaven start --headless      # run the daemon yourself — no desktop app needed
beehaven status
# → Account: Connected

The daemon is what holds the relay connection and routes your calls. The Mac app spawns it for you; start --headless is how you own it yourself on any machine. Stop it with beehaven stop.

Connect to a target

Everything you address is a durable object. Connect once to set the active target; every subsequent command auto-routes to it. There are three address shapes:

beehaven connect home            # your home workspace
beehaven connect team/<id>       # a team's agent cloud
beehaven connect <appName>       # a locally installed app

Call actions

List what a target can do, then call an action with an optional JSON payload:

beehaven actions
beehaven call send-digest '{"to":"ops","range":"24h"}'
# → { ok: true, delivered: 1 }

Give agents memory

remember and recall are the substrate behind your company brain. Write a fact once and any agent can find it later — full-text search across your prompts, docs, decisions and facts:

beehaven call context-write '{"title":"Refund policy","body":"Refunds: 30 days, minus shipping."}'
beehaven call context-search '{"query":"refunds"}'
# → Refund policy - Refunds: 30 days, minus shipping.

Drive the canvas

Three verbs: canvas-perceive to see a composition, canvas-act to build on it, and canvas-catalog to list every action with its exact args. They work headless — no browser tab needed — so a script or an agent can build a whole page and you open the tab to find it done.

beehaven call canvas-catalog '{}' | jq .headlessActions   # what runs without a tab
beehaven call canvas-act '{"compositionId":"<id>","action":"frame.create",
                           "args":{"name":"Hero","x":0,"y":0,"w":1440,"h":720}}'
beehaven call canvas-perceive '{"compositionId":"<id>","format":"text"}'  # check your work

Full guide, node shape and the headless rules: Canvas API.

Driving an open tab

canvas-invoke is the lower-level channel: it reaches into an OPEN tab and runs a registered editor action — paste a URL, re-trace, export a bundle. Reach for it only for the things a tab genuinely owns (PNG export, the clipboard, selection); canvas-act is the path for everything else, because it runs headless and falls back to a tab when one is open. The tab must already be open — the CLI drives it, it doesn't spawn it.

beehaven call canvas-invoke '{"action":"vector.export-bundle"}'
# → { ok: true }

Command reference

Command	What it does
beehaven connect <addr>	Set the active target. Address grammar: home · <type>/<id> · <appName>.
beehaven call <action> [json]	Run an action against the connected target, one-shot.
beehaven actions	List the actions the connected target exposes.
beehaven call context-write {json}	Write a doc / decision into the company brain.
beehaven call context-search {json}	Full-text search the brain - prompts, docs, decisions, facts.
beehaven call canvas-catalog {json}	Every canvas action + its exact args, and which run headless. Generated, never stale.
beehaven call canvas-act {json}	Build on a composition - one action or a batch. Works with no browser tab.
beehaven call canvas-perceive {json}	See a composition - nodes, boxes, styles, selection. Optionally a rendered PNG.
beehaven ls · cat · grep · tree	Inspect the connected workspace like a filesystem.
beehaven sql <query>	Query the target’s state store directly.
beehaven watch	Stream live events from the connected target.
beehaven status	Show connection + auth state.
beehaven login · logout · whoami	Account management.
beehaven disconnect	Clear the active target.

How it routes

A local daemon keeps a secure connection to the Clearly relay and routes every command to the right durable object. Only one daemon runs at a time; it handles auth and the WebSocket so the CLI stays a thin, scriptable front end an agent can shell out to. That's what makes Beehaven software for agents and not just another dashboard.

Beehaven overview →Why it exists and what it powers.Company Brain →The knowledge layer remember/recall feeds.