# mde — the Workbench CLI

Zero dependencies, one file. Install (no sudo — picks /usr/local/bin or ~/.local/bin):

    curl -fsSL https://workbench.md/install | sh

(`GET /cli` is the raw executable itself, `GET /install` the installer script.)

```
mde — collaborative markdown docs, from the terminal

Setup
  mde --version              print the CLI build version
  mde login [url]            sign in — approve in your browser, no token hunting
                             (scripts: mde login --token <token>; token in the account menu)
  mde whoami                 show who you are

Documents
  mde ls [--json]            list your documents
  mde search <query> [--folder name]  search titles and markdown, ranked
  mde new <title> [-f file]  create a doc (markdown from -f or stdin)
                             works logged-out too: creates an anonymous doc at a secret link
  mde cat <doc>              print a doc as markdown (pending suggestions excluded)
  mde pull <doc> [-o file]   fetch a doc and remember its version for safe pushes
  mde push <doc> -f file     replace a doc's content (also reads stdin)
                             refuses if the doc changed since your last pull,
                             and refuses empty input (an empty source file is
                             usually an accident, not an intended clear)
                             --force  overwrite/clear anyway    --label "msg"  name the version
  mde open <doc>             open a doc in the browser
  mde share <doc> [role]     get a share link (view|comment|suggest|edit, default view)
                             works on an edit-key share URL too, not just your own docs
  mde rm <doc>               delete a doc (by id, share URL, or exact title)
                             anonymous docs delete via their edit-key share URL

Folders and skills
  mde folders                print your recursive folder tree
  mde folder new <name> [--parent id]  create a root or child folder
  mde move <doc> <folderId|none>       file or unfile a document
  mde skill manifest <url|slug> [--v N]  print an install manifest
  mde skill release <folderId> [-m "notes"]  cut an immutable release

Collaboration
  mde ask <doc> <text>                   create an open ASK
  mde claim <doc> <askId> [--as name]    atomically claim an ASK
  mde resolve <doc> <askId> [-m note]    resolve an ASK (or an existing comment id)
  mde comments <doc> [--json]           list comments (and suggestions)
  mde comment <doc> <text> [--line N]   add a comment
  mde reply <doc> <commentId> <text>    reply to a comment
  mde chat <doc> <text> [--fence <id>]  post a message to a doc's chat fence
                             (--fence picks a chat block by its #id when a doc
                             has several; @name mentions of the owner notify)
  mde suggest <doc> --replace <old> --with <new>   propose an edit (creates a delete+insert pair)
  mde suggest <doc> --delete <text>                propose removing text
  mde suggest <doc> --append <text>                propose adding text at the end
  mde accept <doc> <id...>              accept suggestion(s)
  mde reject <doc> <id...>              reject suggestion(s)
  mde history <doc> [--json]            list saved versions
  mde events <doc> [--since N] [--json]   list recent activity (comments, suggestions, edits, versions)
  mde watch <doc> [--since N] [--json]    follow activity live (long-polls; Ctrl-C to stop)
                             retries network/5xx blips; exits non-zero on a permanent
                             error (auth, not found, bad request)
    --exec <cmd>             run a command per event batch (env: MDE_EVENTS json,
                             MDE_DOC, MDE_LATEST) — re-read doc state in the command,
                             don't replay events
    --skip-self              drop your own echoes (agent name, username,
                             --author name, or writes labeled "you: …")
    --cursor                 persist the last-seen seq per doc; restarts resume
    --daemon                 install all of the above as a background service
                             (launchd on macOS, systemd --user on Linux) with logs
                             in ~/.config/mde/logs; remove with --daemon-off

Agent presence
  mde register <name> [--role chief] [--harness x]  register this process
  mde heartbeat <name>                              refresh its presence
  mde activity <name> [--harness x]                 stream the agent's live activity
                             downloads and runs the right adapter for the agent's
                             harness (auto-detected from the registry; --harness
                             overrides), with URL/token/name wired from your mde
                             config — the /chief surface shows the work live.
                             Tails the harness transcript where one exists, or
                             tee a pipe through it:
                               cursor-agent -p --output-format stream-json "…" | mde activity <name>
                             Ctrl-C to stop. Adapter contract: /adapters.md

Chief supervision
  mde chief-supervisor <cmd> [...]   run the between-conversations chief daemon
                             (heartbeat, cursor-deduped sweeps, durable reminders,
                             reconnect prompts) — see: mde chief-supervisor help
                             and docs/CHIEF-SUPERVISOR.md

Feedback
  mde papercut <doc> <summary> [--category api|cli|docs|handoff|other]
                             privately report concrete Workbench friction to maintainers
                             --operation ID  identify the affected handoff operation

<doc> may be a doc id, a share URL, or a (partial) title.
Share URLs work without login: mde cat "https://host/d/abc?key=…"

Environment
  MDE_URL, MDE_TOKEN         override the saved server/token (great for CI and agents)
  MDE_AUTHOR                 attribution name when acting via a share URL without a token
                             (also: --author <name> on push/comment/reply/suggest)
                             with no name set, mde asks once and saves it; in scripts it
                             signs as "agent". Names are marked "guest" and can't match an
                             account username — use the account's token to write as it.
```

Full agent API (HTTP): [/agents.md](/agents.md)