The tools
Everything in this guide was done with one program, vishy. This page lists its commands in the order a developer meets them, one line each. Every option, and every command’s exact output, is in docs/toolchain.md.
| command | what it answers |
|---|---|
vishy check <inputs> | Does the program make sense? Types, names, examples, and a count of what it declares. With --from=<old>, also the migration from the program that wrote the store; with --interface, whether every contract is still a stub. |
vishy run <inputs> | What do the scenarios do? Each step’s outcome, then each unit’s state. |
vishy verify <inputs> [seed] [iterations] | Does every rule hold? Examples, scenarios, then sampled calls from random and reachable states. |
vishy graph <inputs> | Which units are joined, by flows and by rules across units, and what the verifier re-checks after each flow. --json for other tools. |
vishy tree <file> | The file’s declarations as the compiler parsed them, one per line in a bracketed form. |
vishy tokens <file> | The words the compiler reads the file as, one per line with their kind and position. |
vishy ir <inputs> | Counts of the compiler’s internal form of the program; it can write that form to a file, and verify --from-ir runs the verifier from such a file with no program read. |
vishy schema <inputs> | The SQLite tables of every unit with caps storage. |
vishy service <inputs> <dir> [sqlite] | A Rust crate that runs the program as a stored, served application; --from=<old> makes its migrate carry an older store forward. |
vishy client <inputs> <dir> | A typed TypeScript client, an OpenAPI description and a Rust client crate, from the program’s routes. |
vishy serve <inputs> [addr] --db <file> | The development door: the routes served from source against a store, reloaded on every save. |
vishy interface <inputs> | The public surface: rows, enums, events, signatures with their outcomes, flows, routes, effects. |
vishy brief <inputs> <Unit> | What the writer of one unit is shown: the language, the shared declarations and the unit’s stubs. |
vishy part <inputs> <Unit> <part.vish> | One part checked alone against its interface: its examples and sampled checks. |
vishy write <inputs> --out <dir> | The writer stage: every unit’s part requested from a model at once, checked as it lands, assembled, verified and repaired. |
vishy assemble <inputs> <out.vish> | The interface and its parts written as one file; refused while any contract is a stub. |
vishy diff <old> <new> | Whether a package’s change is a patch, minor or major, and whether its new version number covers it. |
vishy blocks <part.vish> | The contract blocks found in a part, with their byte ranges; for debugging a part that will not split. |
<inputs> is any mix of files, directories and packages, as the chapter on many files describes. One command reaches outside the machine: vishy write sends requests to a model endpoint with a key, and the toolchain page says where it looks for both.
Every promise is a script
The repository keeps one check script per feature under tests/, 75 of them on 30 Sept 2026. Each runs the commands its feature’s documentation states, on a real program, and fails when an answer changes: the door’s status codes, a migration carried forward exactly once, a delivery retried with the same key, a refusal’s wording. The documentation pages are held the same way, so a command written on a page is a command that was run. This guide is one more of them: tests/check_book.sh regenerates every answer these chapters include, builds and calls the door of every program with a POST route, and fails on the first line that differs.
A front end written in the language
The part of the compiler that reads a program and checks it is being written a second time, in Vishy. --front vishy on tree, check, verify or any command that reads a program runs the parser and the checker written in Vishy beside the ones written in Rust, and refuses when they disagree, naming the file and the first line that differs. On the storage chapter’s shelf program the answer is the ordinary one:
$ vishy check --front vishy book/programs/storage-shelf.vish
ok: 1 row(s), 1 event(s), 0 fn(s), 2 unit(s), 2 contract(s), 2 flow(s)
The two parsers are held equal on every program file in the repository, 2,632 files on 30 Sept 2026, and the two checkers the same way. The front end exists twice, once in the language it reads, and every file checked is a test of both.
Try
Run vishy tree book/programs/storage-shelf.vish and then the same with --front vishy. The two print the same lines: the first is the Rust parser’s reading of the program, the second the Vishy parser’s, compiled from the language this guide teaches.