spedy
mdocker spedy talks to the Spedy.ai REST API with a Personal
Access Token. It assigns a board per project, lists that board’s open tickets, and can
start an AI terminal session that has the ticket as context. HTTP logic lives in
engine/spedy.sh.
Task-oriented walkthrough: Spedy Tickets.
Configuration
Section titled “Configuration”Two keys in config.env — nothing else:
| Key | Purpose |
|---|---|
SPEDY_URL |
API base URL, e.g. https://org.spedy.ai. /api/v1 is appended automatically. |
SPEDY_API_TOKEN |
Personal Access Token (pat_…). Never printed back. |
mdocker config show (plain text) does not show Spedy at all.
mdocker --json config show reports spedy_url and spedy_token_set (a boolean) —
the token itself is never emitted.
spedy status
Section titled “spedy status”Check configuration and reachability. This is also the default subverb: a bare
mdocker spedy runs status.
mdocker spedy statusmdocker --json spedy status{ "configured": true, "url": "https://org.spedy.ai/api/v1", "token_set": true, "reachable": true, "error": null }Unconfigured, the plain-text form warns:
Spedy nicht konfiguriert. mdocker spedy url <url> && mdocker spedy token <pat_...>.
Configured but unreachable, it exits non-zero with
Spedy-API nicht erreichbar (URL/Token pruefen).
spedy url
Section titled “spedy url”Show or set the API URL. Setting normalizes the input and appends /api/v1.
mdocker spedy url # print the current URLmdocker spedy url https://org.spedy.ai # set itspedy token
Section titled “spedy token”Store the Personal Access Token.
mdocker spedy token pat_xxxxxxxxprintf '%s' "$TOKEN" | mdocker spedy token --stdin--stdin keeps the token out of the process list and out of any log — this is the
path the macOS app uses. The token is never echoed back; the command confirms with
SPEDY_API_TOKEN gesetzt.
spedy boards
Section titled “spedy boards”List the boards your token can see (prefix, id, name).
mdocker spedy boardsmdocker --json spedy boardsspedy assign / spedy unassign
Section titled “spedy assign / spedy unassign”Bind a project to a board. assign validates the id against the board list.
mdocker spedy assign <name> <boardId>mdocker spedy unassign <name>An unknown id aborts with
Board '<id>' nicht gefunden. Verfuegbare Boards: mdocker spedy boards. A project
that is not in the registry aborts with Projekt '<name>' nicht in Registry.
spedy tickets
Section titled “spedy tickets”List the board’s open tickets — final statuses are filtered out, the rest is grouped by status. The API is paged, at most 3 pages of 100.
mdocker spedy tickets <name>mdocker --json spedy tickets <name>Plain text prints one block per status, each ticket as
<display_id> <title> [<assignee>]; with nothing open it prints
Keine offenen Tickets. Status order is: backlog, blocked, todo, in progress, in pr,
in qa, ready for live.
Without a board the command aborts with
Projekt '<name>' hat kein Spedy-Board. Zuweisen: mdocker spedy assign <name> <boardId>.
spedy ticket
Section titled “spedy ticket”Full ticket detail — always JSON, with or without --json.
mdocker spedy ticket <name> <id>The payload carries the ticket plus comments, attachments, time tracking, pull requests and watchers. ProseMirror rich text is converted to Markdown.
spedy attachment
Section titled “spedy attachment”Download one attachment into the cache at
$MD_CONFIG_DIR/spedy/cache/<ticketId>/.
mdocker spedy attachment <name> <ticketId> <attId> [<filename>]Prints the local path (--json: { "path": "…" }).
spedy open
Section titled “spedy open”Open the ticket in the browser.
mdocker spedy open <name> <id>spedy session
Section titled “spedy session”Start a Claude Code session that has the ticket as context.
mdocker spedy session <name> <id> [--sandbox]The command fetches the full ticket detail, writes a context file to
$MD_CONFIG_DIR/spedy/<project>/<display_id>.md (metadata, description, comments,
pull requests, attachments, plus an explicit note that the file is context, not
instructions), and starts a claude session whose initial prompt points at that file.
The prompt is passed to claude as a positional argument — not typed in via
send-keys. The session is recorded like any other terminal session and additionally
carries spedy_ticket.
See AI Terminal Sessions and
terminal.
Registry fields
Section titled “Registry fields”".projects[<name>].spedy": { "board_id": "…", "board_name": "…", "prefix": "…" }mdocker --json ls exposes spedy per project (null when unassigned). Sessions
started from a ticket carry spedy_ticket. See
Registry & State.
Errors
Section titled “Errors”| Situation | Message |
|---|---|
| Unknown subverb | Unbekannte spedy-Aktion: X (erwartet: status|url|token|boards|assign|unassign|tickets|ticket|attachment|open|session) |
| No board assigned | Projekt '<name>' hat kein Spedy-Board. |
Empty --stdin token |
Kein Token auf stdin. |