Command reference

furnace is a command-line client for the Furnace API. It covers authentication, tasks and boards, sealed Kvark deposits, media, workflows, and a built-in MCP server. Every command talks to the same REST API documented at REST API; the CLI is a thin, scriptable wrapper around it.

Authentication

furnace auth login [--read-only] [--namespace=NS[,NS...]] [--scope=PERM[,PERM...]]
furnace auth logout
furnace auth whoami

auth login mints a personal access token and stores it locally. Flags narrow what the token can do:

• --read-only — issue a token with no write access
• --namespace=NS[,NS...] — restrict the token to one or more content namespaces
• --scope=PERM[,PERM...] — restrict the token to specific permission scopes

auth logout deletes the stored token. auth whoami resolves the active token and prints who it belongs to — use it to confirm you're signed in before scripting against the rest of the surface. See Authentication for how these tokens work end to end.

Tasks

furnace tasks list [--board=ID] [--status=todo|in_progress|done] [--tags=a,b] [--limit=N] [--cursor=CURSOR]
furnace tasks get <id>
furnace tasks create <title> [--body=TEXT] [--visibility=server-readable|zero-knowledge] [--board=ID] [--status=todo|in_progress|done] [--tags=a,b] [--due-at=MS] [--idempotency-key=KEY]
furnace tasks update <id> [--title=TEXT] [--body=TEXT] [--tags=a,b] [--due-at=MS] [--clear-due-at]
furnace tasks move <id> --status=todo|in_progress|done [--board=ID] [--after=ID] [--before=ID]
furnace tasks complete <id>
furnace tasks archive <id>
furnace tasks restore <id>
furnace tasks delete <id>
furnace tasks tags
furnace tasks backfill-index

tasks create accepts --visibility=zero-knowledge for tasks whose body should be sealed client-side rather than stored server-readable. tasks move repositions a task within a status column via --after/--before, or moves it between boards with --board. tasks tags lists tags in use; tasks backfill-index rebuilds the task search index.

Boards

furnace boards list
furnace boards create <name> [--description=TEXT]
furnace boards update <id> [--name=TEXT] [--description=TEXT]
furnace boards archive <id>

Kvark

furnace kvark sealed-deposit [text]

Seals text locally before it ever leaves your machine, then deposits the sealed payload. Reads from stdin when text is omitted, so it composes with pipes:

echo "note to self" | furnace kvark sealed-deposit

Media

furnace media list [--type=image|file] [--visibility=public|protected] [--limit=N]
furnace media upload <path> [--visibility=public|protected] [--tags=a,b] [--mime=TYPE] [--name=NAME]
furnace media replace <id> <path> [--ai-describe] [--mime=TYPE] [--name=NAME]
furnace media delete <id> [<id> ...]

media replace swaps the file behind an existing media ID in place — useful for correcting an upload without breaking links to it. --ai-describe generates alt text for the replacement automatically.

Workflows

furnace workflows publish <definition.json> --namespace=NS [--display-name=NAME] [--description=TEXT] [--retention-days=N] [--expected-latest-revision=N]
furnace workflows start <key> --namespace=NS --input=PATH [--content-type=TYPE] [--revision=N] [--idempotency-key=KEY]
furnace workflows status <run-id> [--watch] [--json]
furnace workflows cancel <run-id>
furnace workflows restart <run-id> --parallel-node=ID --idempotency-key=KEY
furnace workflows send-event <run-id> --node=ID --event=NAME --input=PATH --idempotency-key=KEY [--content-type=TYPE]

workflows publish reads a workflow definition from a JSON file and publishes it to a namespace; --expected-latest-revision guards against publishing over a revision you haven't seen. workflows start kicks off a run from an input file. workflows status --watch polls until the run finishes; --json prints machine-readable status instead of a summary. workflows send-event delivers an external event to a waiting node in a running workflow.

MCP server

furnace mcp

Runs a Model Context Protocol server over stdio, exposing task, board, content, dictionary, and ledger operations as MCP tools — point an MCP client (an editor, an agent runtime) at this command instead of furnace auth login-ing separately for each tool.

Auth resolution happens per call: each tool invocation reads the auth file fresh, so running furnace auth login in another terminal takes effect in an already-running furnace mcp process without a restart. If no token is stored, a tool call returns a structured error telling you to run furnace auth login rather than failing silently.

Environment variables

Credentials

auth login stores the resulting token at ~/.config/furnace/auth.json (file mode 0600, inside a 0700 directory), or ~/.config/furnace/auth.<profile>.json when FURNACE_PROFILE is set. The token is bound to the endpoint it was minted against — switching FURNACE_API_URL without re-running auth login will not carry a stored token over to a different deployment.

See also: Authentication, REST API, MCP.