Skip to content

BERD TASK · 0018 · AUTOMATE AND DELEGATE

Drive Berd from the command line

berdctl is the command-line tool that drives the visible app: berdctl <noun> <verb>. It is described in Berd's own docs as the CLI agents use, and that is the surprising part — the main reason to know it exists is that your agent can change Berd for you, and you can read what it did. The outcome of this task is knowing what the tool can do, when to reach for it, and which one of its verbs acts without asking.

Steps at a glance

  1. Ask the tool what exists
  2. Learn the nouns
  3. Add --json when a result must be parsed
  4. Choose the CLI or the click path on purpose
  5. Expect every verb to show in the app
  6. Treat feedback open and feedback submit as different acts

1. Ask the tool what exists

berdctl --help prints the noun tree; berdctl <noun> --help the verbs; berdctl <noun> <verb> --help the flags, bounds and behaviour. That last one is the reference — the help is hand-authored and tested, and Berd's own guidance is to trust it over anything remembered, including this page. Flags move between releases.

[SCREENSHOT: T18-01 — berdctl --help]

Whether berdctl is on your PATH in a normal Terminal, or reachable only from inside an agent session, is not stated in any source. Try it; if the command is not found, step 4 is your route.

2. Learn the nouns

At v0.6.4 the command registry defines seven: session (create, send, open, list, get, rename, move, clear-project, fork, archive, and a few more), folder (attach, detach, replace, set-cwd, list — a session's workspaces), project (create, list, get, attach-folder, detach-folder, set-startup-mode, archive), agent (create, list), skill (create, list, get), feedback (open, submit — compiled out of the public build; see step 6) and info (harnesses, models, context). In the public release berdctl --help therefore lists six. Attaching and detaching project folders after creation arrived in v0.6.3.

Two verbs matter more than the rest. session send puts a prompt into another session without opening it; the message shows in that transcript marked as sent by Berd from another session, and --from gives it a label. session archive also cleans up Goose-created worktrees and branches, and refuses when that would discard local changes unless you pass the flag that names the loss.

3. Add --json when a result must be parsed

Every command takes --json for machine-readable output. Use it when the result feeds something else — a script, an agent, a note — and skip it when you are reading.

4. Choose the CLI or the click path on purpose

Berd's rule for its own help agent: prefer berdctl when the user wants something done now, when the task repeats, or when precision matters more than a walkthrough; prefer the click path when the user is learning the interface. Morgan, Berd's design lead, on Block's On The Block (September 2026): the CLI gives the agent the ability to change the app itself, so ask the agent rather than clicking through — "I promise I'm gonna be less helpful than your own agent."

5. Expect every verb to show in the app

By design a verb exists only if what it does is visible in the app: a session appears, a project is created, a message lands. There are no auth tokens and no confirmation dialogs; that is acceptable to the design only while every mutation is visible and reversible, or is a plain product action you asked for. Destructive behaviour is behind explicit flags that default to refusal. If a command claims something you cannot see reflected, check --help rather than trust it.

6. Treat feedback open and feedback submit as different acts

The feedback noun is not in the public build: the registry drops it unless the build sets VITE_FEEDBACK=1, and the v0.6.4 public release sets it to 0. In the public build you report a problem through the GitHub issue tracker, with the version from Settings → system and the sanitised logs you gathered yourself — see Keep Berd current and report problems. If an agent tells you it "submitted feedback" on a public build, it did not; check berdctl --help.

In distributions that enable feedback (Block's internal build), the two verbs are different acts. berdctl feedback open --title … --description … opens the same feedback form as the in-app action, prefilled; nothing is sent until you review and submit it yourself. berdctl feedback submit files the report the moment it runs, with no review step and no confirmation. Logs and diagnostics are attached only with --include-logs, on either command, and exclude prompts, responses, tool payloads and session databases.

[SCREENSHOT: T18-02 — the result of feedback open (distributions with feedback enabled)]

Watch out

Where feedback submit exists, it creates a real ticket with no confirmation screen. An agent that runs it because you said "send the feedback" has done exactly what it should. Say "open" when you mean to read it first.

Practitioner decision

Two approaches, both documented. Agent-first: the consultant never types berdctl; the agent runs it on request, and this page is read to understand what the agent did. Consultant-direct: the consultant runs berdctl from Terminal for repetitive set-up — creating projects for each engagement, attaching folders, sending a prompt into a session — and treats the agent route as the fallback. Recommendation: agent-first as the house standard, because the PATH question is unresolved and the tool's own author expects agents to be its main user; revisit after A4 question 7 (does berdctl --help run in a plain Terminal on the consultant's laptop).

Last checked: Berd v0.6.4, 2026-09-11 — read from source and release notes, not yet tested in the app.

Learn more

Reference

Moment
apply
Takes
untimed
Steps
6
Verified
Berd v0.6.4 · 2026-09-11 · source-read
NEVER BESTUCK AGAINCLICK ME

Guide built with Berd, Claude and Codex · verified against Berd v0.6.4, 2026-09-11 · read from source, not yet tested in the app · Buzz Guide · About · not affiliated with Block