# The command line

> The lines worth knowing on the machine itself, one each, in plain English. You can use beafk without ever opening this page.

Almost everything here has a screen in the panel, and the panel is the point.
This page is for the times you have an `ssh` session open anyway.

Add `--json` to most of them when something is going to read the answer back,
and `beafk --help` prints the full list, including the verbs nobody needs on an
ordinary day.

**`beafk` on its own is not a list.** It opens a screen you can move around in —
what is running on this machine right now, which agents are working, what they
are in. It wants a real terminal, so it is the one line here that does nothing
useful in a script.

> [!NOTE]
> On a Mac, drop `sudo`. Root is not needed, and for Tailscale it is refused:
> the app talks to a daemon that belongs to the person who is logged in. The
> same verbs work; they just run as you.

## Setting the machine up

| | |
| --- | --- |
| `sudo beafk install` | prepare this machine — account, service, address, agents, storage. Safe to run again |
| `sudo ./beafk install --connect <cabinet> --code XXXX-XXXX` | the same, and spend the panel's code as soon as the machine exists. The connect screen pastes one curl of install.sh instead, which is this plus the download |
| `sudo beafk net tailscale` | give the machine an address on your private network, or redo it. On a Mac, drop sudo |
| `sudo beafk update` | take the newest release |
| `sudo beafk uninstall` | tell the cabinet, then take beafk off this machine |
| `sudo beafk packages add …` | Linux only — install apt packages. A Mac refuses and names `brew` |

## Belonging to a workspace

| | |
| --- | --- |
| `sudo beafk cloud connect <cabinet> --code XXXX-XXXX` | join a workspace, using a code the panel showed you |
| `beafk cloud status` | which workspace this machine answers to |
| `beafk identity` | this machine's fingerprint — the line to compare with the one the panel shows |
| `beafk tokens list` | the devices that can reach this machine, from the machine's own side |
| `beafk tokens revoke <id>` | cut one of them off |
| `sudo beafk cloud forget` | stop answering to any workspace, and shut every browser out. Asks you to type the machine's name; `--yes` in a script |

## Is it all right

| | |
| --- | --- |
| `beafk status` | what is installed, who is signed in, and what is live |
| `beafk doctor` | whether a browser can reach this machine, in sentences. Changes nothing |

## The record

| | |
| --- | --- |
| `beafk obs logs -q <word> --since 2h` | search what this machine said |
| `beafk obs traces --since 1h` | what took how long |
| `beafk obs status` | whether the store is there, and what is in it |

## Variables

| | |
| --- | --- |
| `beafk env adopt --all` | take the `.env` files this repository already has |
| `beafk env set KEY=value` | set one, for this folder |
| `beafk env set KEY=value --everywhere` | …for every project on this machine |
| `beafk env explain KEY` | which layer wins here, and what it is shadowing |
| `beafk env sync` | write them onto this machine |

## Work

| | |
| --- | --- |
| `beafk projects` | what projects are on this machine |
| `beafk tasks list` | what is open here |
| `beafk tasks add "…"` | write one down |
| `beafk tasks show BFC-12` | one task, its note and its chats |
| `beafk tasks draft BFC-12 --agent codex --brief "…"` | line a CLI up on it, with what it should open with |
| `beafk tasks done BFC-12` | tick it off |
| `beafk tasks reopen BFC-12` | put it back on the list |

## Tool servers

| | |
| --- | --- |
| `beafk mcp list` | the tool servers on this machine |
| `beafk mcp add --name <id> --url <url>` | describe one once, for every CLI that can read it. `--command` instead of `--url` for one that runs locally |

## Skills

| | |
| --- | --- |
| `beafk skills` | what this machine can be asked for, and how |
| `beafk skills show <name>` | one of those pages, in full |
| `beafk skills show index` | the map of everything beafk does |
| `beafk skills load` | hand the pointer to the agents on this machine |
| `beafk skills load --files` | …and commit the pages into this repository |

## Where things are

State lives in `~/.beafk` — the database, the machine's key, the variables.
Anything holding a secret is readable only by the account that needs it.

## The HTTP API

These lines and the panel are the two supported ways to drive a machine. The
machine's HTTP interface is not a third — see
[what beafk does not do](https://beafk.app/docs/what-beafk-does-not-do.md).

---

beafk documentation · Reference · https://beafk.app/docs/every-command

In this section:
- When something is wrong — https://beafk.app/docs/when-something-is-wrong.md
- When a machine will not open — https://beafk.app/docs/a-machine-will-not-open.md
- Glossary — https://beafk.app/docs/glossary.md
- The command line — https://beafk.app/docs/every-command.md (this page)
- Legal — https://beafk.app/docs/legal.md
- The licence — https://beafk.app/docs/license.md

Every page, one line each: https://beafk.app/docs/llms.txt
All of it in one file: https://beafk.app/docs/llms-full.txt