Actions
Every capability in the workspace is an action with a name, a description and an input schema. The CLI, the app and MCP are three doors onto the same set — so anything you can do in one, you can do in the others.
7 min
Discover, then invoke
You are not expected to memorise anything. Ask what exists, read its shape, send it.
beehaven actions # everything this workspace exposes
beehaven actions --search ticket # narrow by substring
beehaven explain ticket-create # the exact arguments, from the live schema
beehaven call ticket-create '{"boardId":"<id>","title":"Ship the docs"}'explain reads the schema the server is actually validating against, not a copy in a document — so it cannot go stale. If an argument is required, it says so; if you send an unknown key, validation strips it.
ticket-create with a description field (the name is body) creates a card with a title and nothing else, and returns a key as though it worked. Read explain before guessing a field name.The same loop over MCP
Two tools stand in for the whole catalog.
clearly_workspace_catalog { "filter": "ticket" }
clearly_workspace_invoke { "action": "ticket-create", "input": { … } }About 22 tools are advertised in tools/list; the rest of the surface is reachable through those two. That is a deliberate trade — declaring every action would cost roughly 27k tokens of context on every session and measurably degrade which tool a model picks, against ~560 tokens for a filtered catalog call when one is actually needed.
The permission lists
Five lists, and each answers a different question. Counted from source.
| List | Size | What it means |
|---|---|---|
| User allowlist | 524 | What a signed-in person may call. |
| Agent grant | 470 | What an agent may call. An explicit opt-in list — adding a verb for a person no longer grants an agent. |
| Human-only | 76 | A person must do this. Chiefly the approval family — an agent approving its own edit is a self-approval hole. |
| Admin-only | 6 | Staff, in every environment. |
| Dev-build-only | 2 | Fine in a development build, dark in production. |
The agent grant is subtracted from, not filtered per surface — the CLI, the in-app agent and MCP all gate on the same set, so a capability withheld is withheld everywhere at once rather than in three places that can drift.
Why an allowlist is not the whole story
A per-verb list cannot see one action calling another. A composite verb like batch or code-run runs actions the caller names, so permission to run the multiplier would otherwise become permission to run anything — they re-gate every action they dispatch. See Scripting.
Reading a result
Failures are values, not exceptions.
Most actions return { ok: true, … } or { ok: false, code, error } rather than throwing, so a script can branch on the outcome. A code is stable and worth matching on; error is prose for a human.
Mutating actions return a diff — what actually changed, including unchanged: true when a write re-sent the value that was already there. That distinction is the most useful thing the result says: a patch that did nothing and a real edit otherwise look identical.
A name that fails silently
Verified against a live workspace, because the fixed ones are the dangerous kind of documentation.
| Send | Not | Because |
|---|---|---|
body | description | An unknown key is stripped by validation, so the card is created with a title and nothing else — and a key comes back as though it worked. |
The CLI’s typed verbs send the right names for you, which is the practical reason to prefer beehaven ticket create over a hand-built call when you are typing by hand — and explain is what settles it either way, since it reads the schema the server validates against rather than a copy in a page like this one.