DunneFlow · Reference
The command line
Every dunneflow command and its flags, for making maps, asking questions without a browser, managing snapshots and serving the dashboard.
Everything the dashboard does, DunneFlow also does from a terminal, and a few things only the terminal does. That makes it scriptable: you can gate CI on it, or run the same question across many programs.
Where the program is#
Examples here are written uv run dunneflow …, for a source checkout.
With the application, drop uv run and use the program directly:
| Platform | Command-line program |
|---|---|
| macOS | /Applications/DunneFlow.app/Contents/MacOS/dunneflow |
| Windows | dunneflow-cli.exe, beside DunneFlow.exe in the folder you unzipped |
| Linux | dunneflow in ~/.local/bin once installed, or dunneflow/dunneflow where you unpacked it |
Commands at a glance#
uv run dunneflow analyze <path> --name <program> # extract, resolve, write the map
uv run dunneflow serve [dir] # the dashboard
uv run dunneflow touches <path> --routine <name> # what does this reach?
uv run dunneflow impact <path> --routine <name> # what breaks if I change it?
uv run dunneflow check <path> # anomalies; non-zero exit on BROKEN
uv run dunneflow glossary <path> # what its words mean, and who says so
uv run dunneflow naming <path> # the naming standard: derived, and quoted
uv run dunneflow mirror <path> # words the docs define that the code never uses
uv run dunneflow query <path> --sql "..." # ask the graph directly
uv run dunneflow revisions <dir> [--seal] # list snapshots; keep the current one
uv run dunneflow render <dir> # rewrite a snapshot's Markdown
uv run dunneflow migrate <dir> # stored paths: absolute to relative
uv run dunneflow mcp [dir] # answer the map to an AI agent
Two further commands, ingest-schema and ingest-conform, are for people writing a new
language reader and are not covered here. uv run dunneflow <command> --help lists every
flag.
The arguments most commands take#
uv run dunneflow <command> <path> [--name <program>] [--output <dir>]
analyze, touches, impact, check, glossary, naming, mirror and query take
these.
<path>is the source tree foranalyze. For the other commands it names a program: DunneFlow takes its last segment and looks for a program of that name under the maps root. Sotouches output/dunneflowandtouches src/dunneflowfind the same map.--nameis the program directory the map lives in. Leave it off and the last segment of<path>is used.--outputis the maps root. Without it, a source checkout uses./outputand the application uses its platform folder, and the command prints which on the way past (no --output given; maps go to output).--dbnames a graph file directly, skipping the program lookup.--limitcaps how many rows a report prints (on every command exceptanalyze).
Status and summary lines are written to standard error; report output to standard output.
Making a map#
uv run dunneflow analyze <path> --name <program>
| Flag | Effect |
|---|---|
--docs <path> | Where the documentation is. Defaults to the package root. |
--no-docs | Skip documentation entirely. |
--recheck-docs | Hash every document rather than trusting its modification time. |
--standards <dir> | Measure against somebody else's naming standard, read into its own store. Repeatable. |
--include-tests | Include test files. |
--without <lang> | Do not read that language, and record that you declined it. Repeatable. |
--part-of <tree> | This directory is part of a larger tree; judge skip and test rules from there. |
--jobs <n> | Number of parallel workers. |
--timings | Print what each phase of the run cost. |
--no-render | Build the graph; write no Markdown. |
--no-source / --no-doc-source | Do not keep copies of the code / the documents beside the map. |
--quiet | Say nothing but failures. |
--progress-json | One JSON object per line on standard output instead of the summary. |
It is incremental: unchanged files are not re-parsed, so a second run costs a fraction of the first.
Asking questions#
What does this reach? Every routine reachable from one routine, and every boundary any of them touches, grouped by kind and quoted as written.
uv run dunneflow touches src/dunneflow --name dunneflow --routine cmd_serve
What breaks if I change it? Everything that depends on a routine, directly or transitively, and which ways in are affected.
uv run dunneflow impact src/dunneflow --name dunneflow --routine _emit
What do its words mean, and who says so? Every definition carries its source and the line that proves it.
uv run dunneflow glossary src/dunneflow --name dunneflow
What is its naming standard? Two lanes: STATED quotes rules somebody wrote down; MEASURED counts what the code actually does.
uv run dunneflow naming src/dunneflow --name dunneflow
What does the documentation define that the code never uses? Four bands (Named, Borne, Spoken, Absent), where Absent is the strongest sign of drift between docs and code.
uv run dunneflow mirror src/dunneflow --name dunneflow
What looks wrong?
uv run dunneflow check src/dunneflow --name dunneflow
check exits 1 only when a finding is BROKEN, so it can gate CI without failing a build
over things that merely look odd. It exits 2 if it cannot read the map (missing, from a
different version, or unfinished), and 0 otherwise. --all includes informational findings,
--broken-only narrows to the ones that fail, --verbose prints each finding's detail and
blind spot, and --include-tests says the map was analysed with tests included. See
Gate CI with dunneflow check.
Ask the graph directly#
uv run dunneflow query src/dunneflow --name dunneflow \
--sql "select kind, count(*) n from boundaries group by kind order by n desc"
query is read-only. --docs attaches the document store as docs for cross-store joins
(--docs-db names it explicitly). Every show the query button in the dashboard gives you
a statement that runs here unchanged. Unlike the other commands, query reads an unfinished
map, with a warning.
Managing snapshots#
List what a program holds:
uv run dunneflow revisions output/dunneflow
Keep the current snapshot, so the next analysis lands beside it rather than on it:
uv run dunneflow revisions output/dunneflow --seal --label "a name you will recognise"
--at supplies when the bodies were measured, if the graph cannot say.
Rewrite a snapshot's Markdown from the stores already on disk, without re-analysing:
uv run dunneflow render output/dunneflow [--revision <rev>]
This is how a sealed snapshot whose Markdown was lost gets it back.
Rewrite stored paths from absolute to relative, in place:
uv run dunneflow migrate output/dunneflow
Deleting a snapshot is done by hand; DunneFlow has no command that deletes one. Remove
its graph@….db and docs@….db files, then its rows in the paths and revisions tables
of both sidecars (source.db and docsource.db). Stored bodies are shared by content and
are left alone.
Serving#
uv run dunneflow serve [dir] [--revision <rev>] [--port 8787] [--no-open]
serve takes a program directory, a maps root, or nothing at all. It tells a program from a
root by whether the directory holds a map, never by its name. With nothing open it serves the
start page. --revision chooses which point in time opens as the base (default: the
newest). --no-open skips opening a browser.
Answering an agent#
uv run dunneflow mcp [dir] [--revision <rev>]
Serves the same map to an AI agent over the Model Context Protocol. See The MCP server.
Something unclear or out of date? Tell us.