The Beehaven CLI

Command your workspace, agents and canvas the way a terminal commands a filesystem. Beehaven is the name of the world Clearly runs in — the cloud, the hives, the daemon — and this is how you talk to it from a shell.

10 min

Install

A Node program with native dependencies, not a static binary.

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

Requires Node.js 20 or newer. The installer says so up front rather than failing three steps in. It resolves the current release from a signed manifest — version, tarball and a sha256 that is verified before anything is unpacked.

Then sign in. This opens a browser; there is no token to mint or paste.

beehaven login
beehaven doctor        # Node, daemon, relay, and a live workspace round-trip

If you also run the Clearly Mac app, it already bundles the CLI and owns the daemon — you do not need to install anything, and can skip to The daemon below. Download it for Mac — macOS, Apple-signed — Apple Silicon only. Windows isn't built either.

The mental model

Three words. Getting these right is most of the learning curve.

Term	What it means
`Address`	Where a workspace lives. Three shapes: `home` (your personal workspace), `<type>/<id>` for any cloud workspace (`team/abc123`, `shopifyStore/clearly-demo`), or a bare `<appName>` for a locally installed app.
`Target`	The address you are “at” right now — like `cwd` in a shell. Every other command routes to it until you move.
`VFS`	The virtual filesystem inside the target. Folders are projects, documents are `.md` files. This is what `ls` and `cat` read.

The loop is the same in every workspace, every session:

beehaven cd home            # set the target (aliases: connect, nav)
beehaven pwd                # where am I, and what can I do here
beehaven ls ~               # what is in the workspace
beehaven cat '~/CLR-42.md'  # read one, by its key

The daemon

A local process that bridges your machine to the cloud. Everything else talks to it.

The CLI never talks to the network directly. It speaks to a local daemon over a unix socket at /tmp/beehaven-ipc.sock, and the daemon holds the authenticated connection to the relay. Only one runs at a time.

	Mac app owns it	CLI owns it
Start	Open the app	`beehaven start --headless`
Stop	Tray → Quit	`beehaven stop`
Sign in	Tray → Sign in	`beehaven login`

If a daemon is already running, start --headless refuses — that is the single-instance guard, not an error. The other verbs still work; they connect to whichever daemon is up.

Three failures that look alike

beehaven status tells them apart, and so does the failing command. They have different fixes, and the most common mistake is reaching for a restart:

Daemon: NOT running                                  → beehaven start --headless
Relay:  DOWN — token expired, run `beehaven login`    → re-auth
Relay:  DOWN — token valid, run `beehaven restart`    → just bounce the socket

A restart does not refresh an expired token. If the token has expired, bouncing the process reconnects with the same dead credential and fails identically — which reads as a broken daemon. Sign in again.

Reading a workspace

Folders are projects. Documents are .md files. The commands are the ones you already know.

ls <path>— List a directory — `ls ~` for the workspace root
cat <path>— Read a document, by name or by its key
grep <pattern> <path>— Search bodies, recursing directories
tree <path>— Show the tree
head · tail · wc— The usual three
search "<query>"— Ranked search across documents (BM25)
sql "<query>"— A read-only SELECT against the workspace's own tables

A document is addressable three ways, and all three resolve: its full filename (~/Prepress/CLR-42 Pricing.md — what ls prints), its key alone (~/CLR-42.md), or its title alone (~/Pricing.md).

Quote paths with spaces. A document filename leads with its key and then its title, so most real paths contain a space and an unquoted one is re-split into several paths by the remote tokenizer.

Which search to use

These are three different mechanisms, not three spellings of one — see Search for the full picture. In short: grep and search match words, so query with the vocabulary the document itself would use; sql answers the structural questions that have no keyword at all (“which documents changed since Monday”, “how many have no body”).

Organising and working

Everything a person does by hand.

Organise

mkdir ~/<Folder>— Create a project
mv <src> <dest>— Move, or rename
cp <src> <dest>— Copy a document; -r for a folder

Work

ticket create "<title>"— File a card on a board — also list · move · edit · show · comment
board list— The boards you can file to — create · delete · report · backlog
sprint list— Plan, run and close a sprint
sheet new "<title>"— A spreadsheet — list · get · set · append · import
slides new "<title>"— A presentation — add · move · show · export
open <id>— Put a composition, document or board on screen
teleport <file>— Upload a local file into the workspace
doc add <file>— Add a local file as a searchable document
ask "<question>"— Chat with the workspace's agent
watch— Stream live events

task makes a note, not a card. For something that belongs on a board, use ticket. The two are different objects and only one of them appears in a column.

The other door — actions

Every verb above is a friendly face on an RPC. You can call the RPC itself.

beehaven actions                     # every action this target exposes
beehaven actions --search ticket     # find one by substring
beehaven explain ticket-create       # its exact arguments, from the live schema
beehaven call ticket-create '{"boardId":"<id>","title":"hello"}'

This is not a last resort — it is the better-documented door. Every action carries a description and an input schema you can read with explain, which is more than the verb list offers. A person at a terminal wants the verbs; an agent or a script wants actions → explain → call, because then nothing needs memorising.

But the verbs are not sugar

Each one encodes something the raw action does not tell you, which is the real reason to prefer them by hand:

Verb	What it knows that you would have to
`ticket`	Sends `body`, not `description` — validation strips an unknown key, so a hand-built call creates the card with a title and nothing else.
`slides`	Supplies `deck-move-slide`’s required `to`.
`sheet`	Turns TSV into the `rows` array `sheet-set` actually wants.
`ls · cat · grep`	Thread a per-target `cwd` and quote arguments a remote tokenizer would otherwise re-split.

The description trap fails silently: the key is stripped, the card is created with a title and nothing else, and a key comes back as though it worked. Verified live.

call is not a privilege. Authorisation is server-side and per-action — an action you are not entitled to refuses here exactly as it would anywhere else. See Actions.

Environments

Which backend the daemon points at.

beehaven env                 # print the active env and relay
beehaven env staging         # switch
beehaven env prod --confirm  # prod requires --confirm

--env is deploy-only and is not a per-call switch. Every call, sql and admin goes wherever the daemon points, so a command that looks like it targeted staging can read production. Use beehaven env, and run beehaven env with no argument before concluding anything surprising.

The --confirm on prod is a safety interlock, not a permission check — the config is a plain file you own, so a client cannot enforce authorization about itself. What it prevents is running a billable or destructive command against live customer data while believing you are on staging.

Agent identity

beehaven agent login jinri-claude   # mints the identity if it is new
beehaven agent whoami
beehaven agent list

An agent identity is a real workspace member with its own memory, sessions and activity log. Every action it takes is attributed to it, and it can be given a narrower tool allowlist than you have. A session survives a daemon restart — identity is bound to the process scope and persisted on disk, so a stop/start keeps both the identity and the connected workspace.

Agents, identity and attribution →

Connecting other agents

Point the AI clients on this machine at this workspace.

beehaven mcp install     # writes the server entry into every detected client
beehaven mcp status      # which clients are configured
beehaven mcp remove      # remove the entries and revoke the token

For a client that is not on this machine — claude.ai, Claude Desktop, another laptop — point it at the endpoint and let it sign you in through the browser. Nothing to install, no token to paste. See MCP.

When it is not working

One command first.

beehaven doctor

It checks Node, the daemon, the relay and a live workspace round-trip, and prints the fix rather than the symptom. Full guide: Troubleshooting.

What a workspace holds →The action surface →Connect an agent over MCP →Troubleshooting →