beehaven
The command line for Beehaven — the Clearly cloud. Command your workspace, agents, canvas and apps the way a terminal commands a filesystem, through the local daemon that bridges your machine (and your AI agents) to it.
Beehaven is the name of the world Clearly runs in — the cloud, the hives, the daemon, the bees. It isn't a separate product you buy; it's where Clearly lives, and this is how you talk to it from a shell.
Requirements
- Node.js >= 20 (the CLI is a Node program; the published archive includes its runtime dependencies)
Install
For a one-off agent session with Node.js 20 or newer, run the npm package directly:
npx --yes beehaven@latest guide
guide works before sign-in. It explains when Clearly is useful, gives the
human a signup link, and shows the authenticated first artifact. npx uses an
ephemeral npm install; it does not create a Clearly account or upload anything.
Public builds send one anonymous, content-free cli:guide usage event unless
BEEHAVEN_NO_TELEMETRY or the local telemetry-off file disables telemetry.
The package also provides the beehaven binary for a global npm install:
npm install -g beehaven@latest
beehaven guide
The identical release is also listed under the Clearly npm organization as
@clearlysh/beehaven.
Hand work to someone without an account
When an agent's work is ready before the person has signed up, handoff needs
no login and prints one private link:
npx --yes beehaven@latest handoff plan.md
npx --yes beehaven@latest handoff plan.md --tasks todo.md --csv budget.csv --wait
The person previews it, signs in or creates a free account, and saves it. A
document alone becomes a private draft; with --tasks (a Markdown checklist or a
JSON array) or --csv files it becomes a private project with a ticket per task
and a sheet per CSV. The link is a credential — the first person to save it owns
the work — so send it only to the person you are working with. Unsaved handoffs
expire after 7 days. --wait returns when they save it.
The self-contained installer remains the recommended persistent install. It does not require npm to resolve dependencies on the user's machine:
curl -fsSL https://clearly.sh/install.sh | sh
That fetches a versioned tarball and writes beehaven to ~/.local/bin. Published
archives include their dependencies; older archives may require npm. Add the bin
directory to your PATH if the installer says it isn't there.
Verify:
beehaven --version
beehaven doctor # environment + daemon + relay checks
Working inside the monorepo instead?
cd packages/cli && npm install && npm run build && npm link
npm link may not win: the installer writes ~/.local/bin/beehaven, and that
directory usually precedes the npm prefix on PATH. Check which beehaven and
beehaven --version before concluding a local change didn't take.
Both npm and the installer ship the public CLI build. The installer downloads
a versioned archive from downloads.clearly.sh and verifies the SHA-256 in its
update manifest. npm verifies package integrity through the registry.
Updates
Run beehaven --version to see both the version and the file being executed.
The CLI checks the published version on command startup at most once an hour and
prints a notice when it finds a newer version. This is a notice, not an interactive
prompt. A curl-installed CLI (~/.beehaven/cli) can be updated by a person or an
agent with beehaven update; it verifies the release archive's SHA-256 before
installing. No workspace agent login is needed for this local command.
An npm install updates with npm; an npx run can request @latest again.
When a curl-installed CLI owns a standalone daemon, that daemon checks at startup and hourly, installs a verified update, and restarts itself. A daemon started by the Mac app leaves updates to the app. Production and staging Mac apps check on launch and every four hours, download in the background, and install on quit by default; the tray also offers Check for updates. A linked development build is updated by rebuilding its checkout. Clearly Dev.app also has no release updater; rebuild and reinstall that app to update its bundled CLI.
Quick start
beehaven login # authenticate (browser OAuth)
beehaven connect home # set the active target — your default workspace
beehaven agent login codex --label "my task" --client cli # identity + one work session + brief
beehaven actions # what can I call here?
beehaven call canvas-catalog '{}' # every canvas verb + its args
Three commands cover almost everything: connect to a target, ask what
actions it has, call one. See beehaven help for the full surface, or
beehaven help <command> for any single verb.
Agent avatar expressions
The local avatar is addressable by the active agent identity. Use the short flags for the primary expression surface:
beehaven --mood curious
beehaven --emote cheer "tests passed"
Persistent moods are: neutral, happy, sad, surprised, angry, confused, curious,
and flirty. Lifecycle values are wake and sleep, set with --lifecycle; thinking and
celebrating are activity poses. One-shot emotes are: wave, cheer, hearts, laugh, dance, buzz, nod,
shake, think, surprise, and sleep. An optional reason after an emote is capped
at 200 characters.
--emote think is the one-shot reaction. The compatibility command
beehaven avatar think is the persistent thinking state.
An active agent token routes the call to that agent's avatar; without one, the house avatar is used. Compatibility commands remain available:
beehaven avatar emotion curious
beehaven avatar react cheer "tests passed"
The daemon MCP surface exposes avatar_emote for persistent emotion and avatar_react for one-shot reactions. Both surfaces require the avatar:emote permission for signed agents.
See AVATAR_EXPRESSIONS.md for the complete cross-surface contract and source-of-truth locations.
Talking to the cloud — daemon + DO
The CLI talks to a local daemon that holds the relay connection to the Beehaven cloud and routes RPCs to the right Durable Object.
beehaven login # authenticate (browser OAuth) — required
beehaven status # connection + auth state
beehaven connect home # set the active target (default workspace alias)
beehaven actions # list callable actions on the target
beehaven call <action> '{…}' # invoke one
For scripts that need more than one workspace action, the CLI also exposes the server's scripting primitives without a second execution engine:
beehaven batch @steps.json --json # {"steps":[{"action":"…","input":{}}]}
beehaven code-run @script.mjs --json # source file; use `-` for stdin
batch runs up to 25 sequential steps (400 actions total) and is not
transactional; stopOnError defaults to true. code-run is a sandbox for
computation between workspace calls (200 calls, 20 seconds, 100k source
characters). Both adapters use the same active target, agent attribution,
permission checks and non-zero failure semantics as beehaven call.
batch also accepts the worker-native {method,params} spelling and normalizes
both forms before dispatch.
The daemon normally runs inside the Hive desktop app. For CI / servers / agents with no desktop, run it headless:
beehaven daemon start # spawn a headless daemon (requires a prior `beehaven login`)
beehaven daemon status
Driving the canvas (agent surface)
The CLI can review and drive the Clearly editor canvas in an open browser tab — the same actions a human performs in the UI, exposed to agents over the daemon.
beehaven canvas status [id] # compact health summary (tab connected? nodes? tool?)
beehaven canvas perceive [id] # read the live "room": gaze, contents, focus, chrome
beehaven canvas actions # discover every callable editor action
beehaven canvas invoke <action> '{…}' # drive one action (returns the handler result)
beehaven canvas verify [--composition id] # self-test EVERY canvas action, then clean up after itself
canvas verify creates scratch nodes, exercises each action against the live
tab, asserts the result, then deletes everything it created (it diffs against a
baseline snapshot, so it never touches pre-existing content) and restores print
settings. It is the smoke test for the agent/canvas surface.
Security
- Authentication is required. Every cloud call carries an authenticated
identity;
canvas-invoke/canvas-perceivereject unauthenticated callers and only reach the caller's own connected clients (no cross-account access). - Allowlisted actions only. Remote canvas control dispatches by action id against a fixed registry — there is no arbitrary code execution path.
- Local IPC is token-guarded. The CLI authenticates to the daemon with a
per-launch token from
~/.beehaven/ipc-auth.
Documentation
- Per-command help:
beehaven help <command>
License
MIT © Clearly (clearly.sh)