Problem: `herdr server start` does nothing / background server is not started (no such subcommand in v0.8.2) —— Trove problem library

What you will run into

You installed herdr and want its background server running — so you type herdr server start. Nothing starts: it just prints the server subcommand help text. herdr status keeps saying server: not running, and there is no herdr.sock under ~/.config/herdr/. It looks like "the server won't start", but the truth is simpler: v0.8.2 has no server start subcommand at all — the entry point is simply different.

Why this happens

Start with the conclusion: herdr's process model is "client + background server over a socket". The TUI client herdr starts the background server on demand; only headless use needs you to launch herdr server yourself in the background. There is no symmetrical start/stop command surface — two ways to start, one way to stop:

Chain: command parsing -> server process -> socket files. The break is at step one: server means "run the server", not "manage the server". Since start does not exist, herdr server start just prints help and exits without an error — for this class of mild "command does not exist" entry mistakes, reading error text gets you nowhere.

Measured (2026-08-29, WSL Ubuntu, isolated HOME): headless herdr server starts -> status shows server: running -> all four files appear under ~/.config/herdr/ (socket mode srwx-------) -> herdr server stop -> status returns to not running and the socket is no longer reachable.

Conclusion: to tell whether the server is up, don't judge by which command you typed — check two hard signals: the herdr status output and the socket files under ~/.config/herdr/. In scripts, treat "status says running + sockets exist" as the success criterion.

Step by step

1. Check the command surface — Required

Run herdr --help: the subcommand list only has herdr (TUI) and herdr server (headless) — there is no server start.

2. Interactive use: open the TUI — Required

herdr starts the TUI and auto-starts the background server; herdr status should now show server: running.

3. Scripted use: headless in the background — By scenario

nohup herdr server > /tmp/herdr-server.log 2>&1 &
herdr status

4. Stop and re-verify — By scenario

herdr server stop, then herdr status should show not running.

5. Check the write surface — Diagnostic

ls -la ~/.config/herdr/: you should see .plugins.lock, herdr-client.sock, herdr.sock, herdr-server.log. Missing sockets = the server is not up.

How to confirm it works

• herdr status prints server: running;
• herdr.sock and herdr-client.sock exist under ~/.config/herdr/ (mode srwx-------);
• after herdr server stop, status returns to not running and the socket is unreachable.

Other environments

• Servers / CI (no desktop): use the headless path (nohup herdr server &); do not expect the TUI;
• Isolated-HOME test setups: config paths follow $HOME, so ~/.config/herdr/ moves with it;
• Zero workspace writes: herdr only writes under ~/.config/herdr/ and ~/.local/state/herdr/, never the cwd (verified by cli-smoke, 2026-08-28).

Symptom

Running herdr server start does not start a server — it only prints the server subcommand list (help text). herdr status reports server: not running, and no herdr.sock appears under ~/.config/herdr/.

Cause

There is no server start subcommand in the v0.8.2 command surface. There are two proper start entries:

• herdr (full TUI client) — the normal path; it auto-starts the background server;
• herdr server (headless) — runs the server in the foreground; for scripts use nohup herdr server &;
• stop surface = herdr server stop (via the API socket); status surface = herdr status (server: running / not running).

Solution

1. Interactive: just run herdr (TUI; the server starts automatically) — no explicit start needed.
2. Scripted: nohup herdr server > /tmp/herdr-server.log 2>&1 &, then confirm running with herdr status.
3. Stop: herdr server stop; confirm not running with herdr status.
4. Write-surface check: ~/.config/herdr/ should contain .plugins.lock, herdr-client.sock, herdr.sock, herdr-server.log.