carrel

Command-line client for a hosted Carrel desk — publish and read artifacts (markdown + HTML), run the comment loop, all over the hosted HTTP API.

carrel is the tool agents and people install (like gh) to work with a Carrel desk from a terminal. It talks only to the desk's hosted /api/desk/* HTTP API over fetch — it never touches your database and holds no credential other than an API key you mint in the app.

Install

npm install -g carrel-cli

Requires Node.js >= 18 (uses the built-in global fetch). Zero runtime dependencies.

Log in

Mint an API key in your desk under Settings (it is shown once), then:

carrel login --token <your-key>

carrel points at the hosted Carrel desk by default, so you normally only pass a key. login verifies it against GET /api/desk/whoami and, on success, stores { host, token } in ~/.carrel/config.json (the directory is created 0700 and the file is chmod 600). You can also pipe the key on stdin or set CARREL_TOKEN:

echo "$MY_KEY" | carrel login

Point at a different desk with --host <url> (or CARREL_HOST) — e.g. a self-hosted instance.

Commands

| Command | What it does | | --- | --- | | carrel login | Verify a host + key and save them to ~/.carrel/config.json | | carrel whoami | Show the owner the current key resolves to | | carrel publish <file> | Publish a markdown/HTML file as a new artifact | | carrel list | List your artifacts (compact table; --json for JSON) | | carrel get <id> | Show one artifact (--body for full content) | | carrel update <id> | Update title/summary/body/format/tags/collection | | carrel delete <id> | Soft-delete an artifact (recoverable for 30 days) | | carrel comments <id> | List an artifact's comment threads | | carrel apply <id> <file> | Apply agent-edited CriticMarkup to close the loop | | carrel collections | List your collections |

Run carrel --help for the overview, or carrel <command> --help for a command's options. Add --json to most commands for machine-readable output.

Publishing

# Format is inferred from the extension when --format is omitted.
carrel publish brief.md --title "Q3 Brief"
carrel publish report.html --title "Report" --summary "weekly" --collection briefs --tag q3 --tag draft

.md / .markdown infer markdown; .html / .htm infer html. Pass --format md|html to override. Publishing prints the new id and the reader URL.

The comment loop

carrel comments <id>                 # read human feedback
carrel apply <id> edited.criticmarkup  # post agent-edited CriticMarkup back

Configuration & auth resolution

For every request the host and token are resolved in this order (highest precedence first):

1. --host / --token flags
2. CARREL_HOST / CARREL_TOKEN environment variables
3. ~/.carrel/config.json (host, token)
4. the built-in default host (the hosted Carrel desk) — host only

So in the common case you only need a key; the host is filled in for you. If no token can be resolved, the CLI tells you to run carrel login.

| Variable | Purpose | | --- | --- | | CARREL_HOST | Desk API base URL (defaults to the hosted Carrel desk) | | CARREL_TOKEN | API key minted in Desk → Settings |

Errors & exit codes

Commands exit non-zero on failure with a one-line error: message:

• 401 → "your key is missing or invalid — run carrel login or mint a new key in Desk → Settings"
• 404 → "not found"
• Network / non-JSON responses → a clear "could not reach …" message

License

MIT