Skip to content

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.

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.

Check configuration and reachability. This is also the default subverb: a bare mdocker spedy runs status.

mdocker spedy status
mdocker spedy status
mdocker --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).

Show or set the API URL. Setting normalizes the input and appends /api/v1.

mdocker spedy url
mdocker spedy url # print the current URL
mdocker spedy url https://org.spedy.ai # set it

Store the Personal Access Token.

mdocker spedy token
mdocker spedy token pat_xxxxxxxx
printf '%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.

List the boards your token can see (prefix, id, name).

mdocker spedy boards
mdocker spedy boards
mdocker --json spedy boards

Bind a project to a board. assign validates the id against the board list.

mdocker spedy assign
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.

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
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>.

Full ticket detail — always JSON, with or without --json.

mdocker spedy ticket
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.

Download one attachment into the cache at $MD_CONFIG_DIR/spedy/cache/<ticketId>/.

mdocker spedy attachment
mdocker spedy attachment <name> <ticketId> <attId> [<filename>]

Prints the local path (--json: { "path": "…" }).

Open the ticket in the browser.

mdocker spedy open
mdocker spedy open <name> <id>

Start a Claude Code session that has the ticket as context.

mdocker spedy session
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.

".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.

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.