Reference

What you can do

Everything you can do with DarkPrint, and where: the darkprint command line, an MCP server your coding agent connects to, and a skill your agent installs to write blueprints. Each row says whether it works today.

live: works as printed · by design: built, and declines that step on purpose

By intent

Find one for a task
find_blueprints { task: "…" }
live
Find a node for a task
find_cards { task: "…" }
live
Read a card before you depend on it
read_card { ref: "…@1.0.0" }
live
Fetch an exact release by its digest
inspect_provenance for the digest, then get_blueprint at it
live
Get the files on disk
get_blueprint from your agent, or darkprint clone from your terminal, for a release or for one card
live
Check a folder is valid
darkprint validate
live
Run one
nothing here runs a blueprint: your own harness does, and get_blueprint returns the contract for running it
by design
Bring a foreign pipeline in
darkprint import
live
Write one from nothing
follow the tutorial: the DarkPrint skill interviews you in your agent, and a live page here draws the graph as you answer
live
Have your agent write one
install the DarkPrint skill with one npx line; it interviews you and writes the folder
live
Check a version bump matches the change
darkprint bump
live
Say what a run cost
darkprint report
live
Publish a release from your agent
POST /api/bundles with a write-scoped API key; Settings prints the exact call when you mint one, and the Publish page does the same from a browser
live
Publish one card on its own
POST /api/cards with a write-scoped API key, or drop the YAML on Publish
live
Change who can see a blueprint
PATCH /api/bundles/<owner>/<slug>/visibility, or the switch on each row of your own shelf
live
Read a private blueprint over MCP
send your API key as a bearer token; get_blueprint, read_card, inspect_provenance and fetch_release then reach your own private blueprints, while the two find tools search public blueprints only
live

Every verb below runs as npx -y darkprint <verb> on any machine with Node. The first run has npx fetch the darkprint package from npm and keep it in its own cache, so nothing lands in your project. The table below is what each command takes. Exit code 0 on success, 1 on anything else.

Verb	Does	Status
clone (<owner>/<slug> [--version <v> \| --digest <d>] \| <id>@<version>) [--out <dir>]	Fetches a release into a directory, byte for byte as the registry exported it. Given a card reference <id>@<version> instead, writes that one card as cards/<id>@<version>.yaml under --out.	live
validate [<dir>]	Runs the registry's own bundle checks offline, and exits 1 only when a finding is an error.	live
export [<dir>] --attractor	Writes a bundle as Attractor-compatible DOT on stdout, keeping every finding on stderr so the graph can be redirected into a file.	live
import <pipeline.dot> --as <handle> --out <dir>	Reads an Attractor pipeline into a draft bundle on disk, listing what it wrote on stdout and every finding on stderr.	live
bump [<dir>] --declare <version> --target <owner>/<slug>	Holds a version you have already declared against what actually changed since the last release, and writes nothing.	live
report <run-dir> --target <owner>/<slug> --cost <units>	Sends a finished Attractor run to the registry. Prints what was claimed on stdout; on stderr, which manifest key the start time came from and how each node ended.	live
skill install [--codex] [--dir <parent>]	Copies the DarkPrint skill this package carries into ~/.claude/skills/darkprint, or ~/.agents/skills/darkprint with --codex, replacing an earlier copy, and prints where it landed and the version from its frontmatter.	live
mcp	Serves the registry over MCP on stdio, for a client that cannot reach the remote server at /api/mcp.	live

One of the eight needs more than the package. report is the only verb that writes. It needs a signed-in session cookie, passed through the session variable below, or a write-scoped API key from Settings. It also refuses offline until five facts about the run are supplied or found in the run manifest.

DARKPRINT_URL
registry base URL (default https://www.darkprint.io)
DARKPRINT_API_KEY
an API key, which raises the rate limit ceiling
DARKPRINT_SESSION
a signed-in session cookie. report is the only verb that writes, and it sends this cookie. The run route also takes a write-scoped API key, which report does not send.

A remote MCP server at https://www.darkprint.io/api/mcp, nothing to install. Two tools search the public registry by task, one returns a whole blueprint with notes for instantiating it under your harness, three read one thing by its address, and one compiles a release into a pipeline for Attractor, the runner DarkPrint compiles to. Every tool reads. Without a key every call reads as anonymous and sees public blueprints and cards only; a key sent as a bearer token raises the rate limit and lets the four addressed tools reach your own private blueprints. Ranking is a similarity between your task and each document, and a score says nothing about quality. Nothing here runs a blueprint.

Tool	Takes	Returns	Status
find_blueprints	task	Search the public registry for blueprints that fit a task described in your own words. Write a sentence or two about the work and its constraints; prose finds more than keywords. Results come back ranked by how close each blueprint's document is to the task, best first: the cosine similarity between the two plus a small bonus for words that match. Each hit carries its `ref`, written `owner/slug`, its `author`, the `digest` of its current release, a `score`, the `similarity` when the vector channel was available, the `evidence` naming every field a word matched, and a scorecard summary: node count, the human-gate node ids, autonomy class, security level and covered phases. The response's `encoder` field reads `absent` when the order is lexical coverage alone, and `ordered` reads false whenever any hit came back without a `similarity`, which happens to a blueprint published while the encoder was down. Read an unordered answer as a set of candidates and rank it yourself on the evidence. Call this first, then `get_blueprint` on the ref you choose. A score is a similarity and says nothing about quality.	live
find_cards	task	Search the public card library for single nodes that fit a task described in your own words, ranked the same way as `find_blueprints`. Each card id appears once: the highest-scoring version, and on a tie the highest version number. Each hit carries its `ref`, written `id@version`, plus `digest`, `name`, `type`, `action`, `phases`, `tools`, `riskMarkers`, the blueprints that pin it in `usedIn`, a `score`, the `similarity` when available and the `evidence`. The response carries `encoder` and `ordered` with the same meaning they have on `find_blueprints`. Use `read_card` on a ref to get the whole document.	live
get_blueprint	owner, slug	Return one blueprint in a single call: every file of the release (topology.dot, cards/*.yaml, README.md, and ontology/extensions.yaml when the blueprint declares local terms), its manifest, its scorecard, its provenance, and numbered notes for instantiating it under the harness you name. Without `digest` you get the current release; with one you get exactly those bytes, and they keep answering after a newer release is cut. The answer also carries `run`: the contract for executing the graph, which every caller gets whether or not they name a harness, because a card's ports, prohibitions and retry bound mean the same thing whoever runs them. Show the graph and the scorecard to your user and get their agreement before running any of it. Call this once `find_blueprints` has found the blueprint you want. With an API key sent as a bearer token, your own private blueprints are reachable here too.	live
read_card	ref	Fetch one node card as published, verbatim YAML. `ref` is `id@version`, always pinned and never `latest`, and an id may be namespaced, as in `berti/solver-a@1.2.0`.	live
inspect_provenance	owner, slug	Who published a blueprint, what it was forked from, and every release with its version and digest. Take a digest from here to pin a release that will not move.	live
fetch_release	owner, slug, digest	List the files of one exact release, addressed by digest. A slug names whatever the registry holds today; a digest names the bytes you tested against and keeps naming them after a newer release is cut. Fetch each file's contents from `/api/files/blueprints/<owner>/<slug>/d/<digest>/<path>`, or call `get_blueprint` to get every file in one answer.	live
export_pipeline	owner, slug, digest	Compile one published release into a DOT pipeline for Attractor, the runner DarkPrint compiles to, and return it as text. Addressed by digest like `fetch_release`, so the pipeline is compiled from the bytes you pinned. Read the header: it lists every Attractor attribute a DarkPrint blueprint has no way to set, including goal gates, timeouts and every part of the retry policy above `max_retries`, and each of those falls back to the runner's own default. A node's prompt is all the runner gets from its card, so the card's ports and its declared prohibitions are not enforced by anything in this file. A release DarkPrint reports errors on is refused rather than compiled.	live

Claude Code

claude mcp add --transport http darkprint https://www.darkprint.io/api/mcp

Codex

codex mcp add darkprint --url https://www.darkprint.io/api/mcp

Claude Desktop
```
https://www.darkprint.io/api/mcp
```

Cursor

{
  "mcpServers": {
    "darkprint": {
      "url": "https://www.darkprint.io/api/mcp"
    }
  }
}

VS Code

{
  "servers": {
    "darkprint": {
      "type": "http",
      "url": "https://www.darkprint.io/api/mcp"
    }
  }
}

Gemini CLI

{
  "mcpServers": {
    "darkprint": {
      "httpUrl": "https://www.darkprint.io/api/mcp"
    }
  }
}

Copy the one for your client. The same server also runs on your own machine over stdio, as npx -y darkprint mcp, out of the same package that carries the CLI and the DarkPrint skill; the remote address above needs no package at all.

One command installs the DarkPrint skill into your agent, which then interviews you and writes a blueprint folder. A card’s skill: field points at a document for one node, while the DarkPrint skill writes the whole graph.

npx -y darkprint skill install

The line has npx fetch the darkprintpackage from npm and copy the DarkPrint skill it carries into your agent’s skills folder; nothing else is installed and no account is created. The DarkPrint skill is also served on this site, file by file. Assisted Design explains it and gives the Codex form, and the tutorial walks a first blueprint through it, with a live page here drawing the graph as the interview runs.

Asks

the outcome
what exists at the end that does not exist now
the check
the command that exits non-zero when the work is wrong
the registry
whether a published blueprint or card already does part of the job, searched before you describe a node
the nodes
who does each part, and whether that is an agent, a command, a check or a person
the boundaries
what has to reach each node, and what must never reach it
the loop
where it closes, how many attempts it may take, and which way each fork goes

Some of the questions it asks. The full interview is longer, walks a risk sheet for each node, and picks every name and version itself.

Writes

topology.dot
who is wired to whom
cards/<id>@<version>.yaml
one per node the graph pins
README.md
for a person opening the folder

This site does not check what the DarkPrint skill writes. It is a document your agent follows.

What you can do

By intent

The three surfaces

The command-line surface

The MCP server

The DarkPrint skill