Home / Docs / Specification / 13. Diagnostics, Agent ABI and project files
13.5 Command line
| Command | Purpose |
|---|---|
una check [path] |
Tiers 0 and 1; --tier 0 skips the solver; --dump-core <module> prints Core IR |
una fmt [path] |
Rewrite to canonical form; --check reports U7001 without writing |
una fix [path] |
(v0.2, ADR 0084) Apply the mechanical repairs that una check reports, then format; --dry-run writes nothing; --tier 0 skips the solver in the final check |
una run [path] |
Run main of [run] entry; --grant <spec> repeated |
una build [path] |
(v0.2, ADR 0055) Compile main of [run] entry into a native executable; --out <file> (spec/16 §2); (v0.4, ADR 0124 rule 27) --debuggable (spec/16 §2 rule 9) |
una test [path] |
Run all tests (example declarations in editions 0.1 and 0.2) |
una obligations [path] |
List obligations with status |
una contract <qualified.name> |
Print the full header, declared or inferred, with doc comments and requirements |
una trace <REQUIREMENT_ID> |
Requirement to contract to obligation chain |
una core [path] |
(v0.3, ADR 0083) Check at tier 0 and print the package's Core IR: with --json, one una.core/1 document (§8); otherwise the text syntax of spec/09, every module in turn. --with-rejected (ADR 0091), with --json only, adds the declarations rejected for information flow, apart from Core (§8); without --json it is a usage error |
una report [path] |
Build report (§6) |
una explain <code> |
Explanation of a diagnostic code |
una migrate [path] |
(v0.4, ADR 0122) Move a package from una.toml and verification.lock to ita.una and ita.lock of edition 0.4; --dry-run writes nothing; --name <name> (spec/30 §8) |
una ita <command> |
(v0.4, ADR 0122) The package manager of edition 0.4: lock, update, add, remove, tree, fetch, vendor, verify, publish, yank, audit, watch, bundle and unbundle; the binary run as ita is una ita (spec/30 §6) |
una lsp |
(v0.2, ADR 0063) The language server: LSP 3.17 over stdin and stdout, for editors. It checks, formats and solves; it never runs programs |
Global flags: --json (machine output on stdout, nothing else on stdout), --color never|auto|always. (v0.4, ADR 0124 rule 3.) una __solver is internal: the solver child that una check starts (spec/12 §5); it is not listed by --help, and its interface may change in any release. (v0.2, #305.) una --version prints the version of una, the editions it serves and the Z3 version its default lock pins, one per line, as una 0.4.0, editions: 0.1, 0.2, 0.3, 0.4, 0.5, z3: 5.1.0 for v0.4.0. (v0.3, ADR 0056 amendment.) A version that serves edition 0.3 lists it, as it lists every edition it serves. (ADR 0121 rule 7.) After editions:, a line preview: lists the editions this release serves as previews, those that §7 marks "is a preview", comma separated, as preview: 0.3, 0.4, 0.5; a release with no preview prints no such line. With --json it prints {"schema":"una.version/1","version":...,"editions":[...],"preview":[...],"z3":...}, with keys in that order; preview is always present, [] when there is none, and is additive within una.version/1. Neither names a commit, so a build of a version prints the same text from any checkout. (v0.4, ADR 0124 rule 19.) A development build, one built without the solver taken by digest or (ADR 0124 step 2) without the runtime built in, prints development build as its last line, and with --json adds a last key build with the value development; a release build prints neither, and z3 names the solver built into it. una with neither a command nor --version is a usage error. (v0.4, ADR 0124 rule 6.) Every command that takes --solver-wallclock also takes --solver-memory <MiB>, the memory limit of each solver query, an integer from 256 to 1,048,576 (default 4096); another value is a usage error. Exit codes (ADR 0036): 0 success; 1 the output holds at least one error diagnostic with a registered code, or reports an obligation that is not proven (una obligations, una trace, una report) or a failed example (una test); 2 a usage error, a problem of the invocation (its flags, grants, paths or names) printed to stderr without a code, with no diagnostic document on stdout; 3 internal compiler error (U8001). A problem of the project files is a diagnostic like any other, in human and --json output: an invalid una.toml (U7002) and a missing or invalid verification.lock (U7004) exit with 1.
Output streams (ADR 0015): human-mode diagnostics go to stderr; command results go to stdout (the explain text, contracts, reports, obligation listings and the program output of una run). With --json, the JSON document goes to stdout and stderr stays empty, except for internal compiler errors (U8001). A failure to write output exits with code 2. (v0.2, #259.) Writing to a closed stdout or stderr is not a failure to write: the output is discarded, as /dev/null discards it, and the command exits as it would with the stream open. A broken pipe (EPIPE), a reader that went away, is a failure to write, exit code 2. A print whose output is discarded is traced as ok (spec/11 §5).
Grant specs: console, clock, env, keys:<keyfile>, files:<path>:read, files:<path>:write, files:<path>:read,write. (v0.2, ADR 0074.) In edition 0.2, also http:<origin> and http:<origin>:<methods>, which grant Http operations (spec/24 §2), and the flags --max-response <MiB> and --http-timeout <seconds> of una run and of executables (spec/24 §4). (Edition 0.4, ADR 0117 rule 8.) An http: spec MAY end with limit suffixes, each ; and one of <n>/second, <n>/minute, <n>/hour, <n>/once and waiting=<n> (spec/27 §9); invalid limits make the spec invalid, and a --grant with limits is a usage error for a package of an earlier edition, for an executable built without L_lim, and when the program's L_lim is above internal (spec/27 §9 rule 5). They grant Console[print], Clock[now], Env[get], Keys[hmac], and the Files operations of the modes. When una.toml names a [run] entry, una check reports each uses clause of that module's main whose capability is not a host capability, since no grant can provide it (U3012); when una.toml also lists [run] grants, a host operation of main that no grant allows is U3012 at its uses clause. A listed empty array, grants = [], is such a list: it grants no host capability, so every host operation of main is U3012 (#925). una run checks main against [run] grants and --grant flags together before the program starts (ADR 0028). (Edition 0.4 preview, ADR 0123.) Also serve:<scheme>://<address>:<port> with ;<item> suffixes, which lets the run accept connections there and grants HttpServer[next, reply, close] (spec/31 §2); in ita.una it is a serve line with its items below it, and in una.toml it is U7002 in every edition.
una run [path] runs pub main() -> Unit of the entry module: [run] entry, or the module of a single file (ADR 0032). It checks the package first, at tier 1, with the grants of [run] grants and of --grant flags together as final grants, so U3012 reports before execution every uses of main that they do not grant. A package without an entry, an entry without pub main() -> Unit, a --grant value that is not a grant spec, an unreadable or invalid key file, a --max-depth, --max-memory, --max-response or --http-timeout that is not a number, a --max-memory of 0 (#185), a --max-response or --http-timeout of 0, an --http-timeout over 86400 (a day), a --max-depth whose stack cannot be allocated, and a --workers, --task-depth, --io-threads or --file-threads that is not a number or is out of its range (spec/27 §3) are usage errors (exit code 2), on una run and una test; una run also takes --serve-threads (edition 0.4 preview, spec/31 §6 rule 1), whose value out of its range or not a number is a usage error too, as is --virtual-time with a serve: grant and no --serve-script (spec/31 §6 rule 14); una run and executables take --serve-script <file> and --serve-out <file> (edition 0.4 preview, spec/31 §8 rule 6), whose usage errors are those of that rule. (Edition 0.4 preview, spec/31 §7 rules 1, 2 and 5.) For a package with a serve section, una run reports a module without pub handle(request: internal Request) -> internal Reply, or with an on_stop that is not pub on_stop() -> Unit, then a run with no serve: grant, each a usage error before any listener is bound, and otherwise runs the driver; una build reports the first and builds the driver into an executable, which reports a missing serve: grant at its start. (v0.2, ADR 0061.) The interpreter's stack is sized from --max-depth and capped at 1 GiB, and --max-memory <MiB> (default 4096) bounds the heap a run holds (spec/11 §7); una test takes both flags. Relative paths of una.toml grants resolve against the package root, and those of flags against the current directory. A Files path is relative to the grant's prefix: it is normalized lexically, its existing part is resolved through the file system, and a path that ends outside the prefix, absolute, through .. or through a link, fails with FileError.Denied, as does an operation that the grant's mode does not allow. The key file of keys:<keyfile> is a TOML table of key names to base64 keys, loaded before the run starts; the first grant that names a key wins, and an unknown name fails with KeyError.UnknownKey. (Edition 0.4 preview, ADR 0116.) When the package's ita.una has a drive section, una run runs the driver of spec/26 §2 instead of main, and a driven module without the shapes of spec/26 §2 rule 2 is a usage error. una run and executables take --stop-after-iterations <n>, an integer from 1 to 2^63 − 1, the budget of each loop instance, which ends each for ever entered, and the driver's loop, at the start of its own iteration n + 1 (spec/26 §6 rule 1); --deadline <seconds>, from 1 to 31,536,000, a host stop request after that many seconds; and --stop-grace <seconds>, from 1 to 86,400 (default 10), the time from the first host stop request to the hard stop (spec/26 §6). Another value of any of them is a usage error. A run that the hard stop cancels ends with U6007, exit code 1, with the trace of an abort; with --json, its status is aborted. una run and executables take --virtual-time, a switch with no value: the run's clock is then virtual, from 0 at the start of the run, and only the run's own waits move it, so Clock.now and the driver's ticks are the same in every run and in both engines (spec/26 §8). A value given to it, as in --virtual-time=yes, is a usage error. una test takes no such flag: time in a test is always virtual (spec/26 §8). --deadline counts seconds of the wall clock under --virtual-time too: it is a request of the host, not a time of the program. (Edition 0.4, ADR 0117 rule 10.) una run also takes --cost-clock, a switch that needs --virtual-time (a usage error, exit code 2, without it): each check point of the interpreter then moves the virtual clock by one millisecond, the cost clock of spec/27 §8 rule 6. Executables do not take it. (ADR 0117, implementation plan step 7, #973.) una run takes --trace <file>, as executables do: the trace goes to the file as a JSON array, each event as it is written, and a file that cannot be made is a usage error before the run starts (spec/27 §8). A started task that ends alone writes its line to stderr as it ends (spec/27 §7).
In human mode, the lines the program prints go to stdout as it prints them, and U6001, U6003, U6004, U6005 and U6009 go to stderr, with exit code 1. U6001 points at the name of main, or of init for a driven program, whose message then names init of the driven module (spec/26 §2 rule 2), and names the variant, with the payload fields whose labels are public; U6003 points at the call that exceeds the depth, or that finds the run over its memory budget. (v0.2, ADR 0113, 2026-10-15.) A native executable whose program has a task construct or a for ever reports U6003 with no position before main, the threads and stacks of this run's tasks could not be made, when the system refuses its threads or the 64 task stacks it reserves, as Linux can under strict overcommit (vm.overcommit_memory=2); a lower --max-depth shrinks that reservation (spec/27 §1 rule 4). A native executable's U6003 for a reference count at its limit has no position: its one line on stderr names the code and the message, and no trace file is written. The interpreter never reports it, so una run --json has no shape for it. U6004 points at the operation of Http given a header value with a control character (spec/24 §1). U6005 points at the Files.read or Env.get whose file content or variable value is not valid UTF-8 (spec/14 §3, ADR 0086). With --json, una run prints {"schema":"una.run/1","tier":...,"status":...,"output":[...],"failure":...,"diagnostics":[...],"trace":[...]} with keys in that order: tier is the tier the checks ran at; status is ok, failed (U6001), aborted (U6003, U6004, U6005, U6009 or U8001) or rejected (the checks reported errors, which diagnostics holds, and nothing ran); failure is null or {"variant":...,"fields":{...}} with the public fields only. U6009 is reported at the start of a run whose reachable code can make a hash table, before main and before any effect, when the host's random source gives no bytes for the process key of keyed hashing (spec/28 §1, ADR 0119 rule 9); no fixed or guessable key replaces it.
una test [path] prints, in human mode, one line per example on stdout, example <module> "<name>" ... ok or ... FAILED, followed for a failed example by the file, line and text of the expectation to blame, when there is one, and the reason; then a blank line and <n> examples: <p> passed, <f> failed. It exits with code 1 when an example fails. With --json it prints {"schema":"una.test/1","tier":...,"diagnostics":[...],"examples":[...],"passed":p,"failed":f}: diagnostics holds the errors of the checks when nothing ran, or U6003 and U8001 of aborted examples; each example has module, name, outcome (pass or fail), reason (null, or why it fails), expectation (null, or {"file":...,"line":...,"text":...}), result ({"kind":"ok","value":...}, {"kind":"fail","variant":...,"value":...} or {"kind":"aborted"}) and trace (spec/11 §5). (v0.2, ADR 0078.) The document also holds redacted, after tier: true when the results and reasons of its examples redact labeled fields, as in a package of edition 0.1, and false when they show every field, as in a package of edition 0.2 (spec/11 §5). The key is additive, and the schema stays una.test/1. (v0.3, ADR 0105.) For a package of edition 0.3 or later, where the declaration is written test, each line reads test <module> "<name>" ... ok or ... FAILED and the summary <n> tests: <p> passed, <f> failed, and --json prints {"schema":"una.test/2","tier":...,"redacted":...,"diagnostics":[...],"tests":[...],"passed":p,"failed":f}, the schema una.test/2: the document of una.test/1 with the key examples renamed tests, holding the same objects in the same order with the same keys. Packages of editions 0.1 and 0.2 keep una.test/1 byte for byte. A consumer that reads both dispatches on schema.
(v0.2, ADR 0084.) una fix [path] applies, in rounds, the mechanical repairs of the package.
- Candidates. Of each diagnostic, only its first repair (by
escape_cost, thenrank) is a candidate. It is applied when all of these hold:- its
editis notnull; - its
escape_costis 0; - it does not widen authority or visibility (§3), with no flag to change that;
- its file is a module of the package, never
una.tomlorverification.lock, nor (edition0.4)ita.una,ita.lockoritaty.una, and holds valid UTF-8; - it is not U7001;
- (v0.3, ADR 0093 rule 6.) of U3020, its edit is one narrowed grant added to the statement,
with @x = @y[ops]or, @x = @y[ops], which the checker writes only within the boundary's ceiling (§3); an edit of U3021 or U3024 is never applied. Any other is skipped aswidens authority. - (ADR 0084, amendments of 2026-10-14 and 2026-10-15.) Of tier 1, only the first repair of a refuted
effect_conditionobligation (U5001) or of a refutedcontract_lockobligation (U3023) can be a candidate (spec/05 §3); never an unknown one (U5002), and never a U3023 of tier 0 for a binding or an operation that the lock does not grant, which carries no edit. (v0.3, ADR 0094.) A U3023 of tier 0 for a locked label (spec/05 §3 rule 6, "Locks") is a tier-0 candidate: its edit raises the header's label on that operation to the join with the lock's. The body then reads the operation at the higher label, so its flows are checked against more; the header's callers may pass a binding labeled up to it, so fewer of their calls are U3022. It adds no binding and no operation, so it widens no authority, and it changes the module only, neveruna.toml.
- its
- (v0.3, ADR 0105 rule 3 and its amendment of 2026-11-05.) The rewrite of
exampletotestis a candidate in packages of edition0.3only, the migration from editions0.1and0.2: only there isexampleat column 1 a U0103 that carries it (spec/01 §5). In editions0.1and0.2exampleis the declaration keyword, and in edition0.4it is an identifier, souna fixnever offers the rewrite there. - Rounds. Each round checks the package at tier 0, in memory. (ADR 0084, amendment of 2026-10-14.) When that check reports nothing and the requested tier is 1, the round also checks tier 1 and takes its candidates; with
--tier 0, no round does. Within a file it takes candidates in order of start, end and diagnostic. An edit that overlaps one already taken, or touches it at a point where either inserts, waits for the next round; an identical edit is merged. Rounds stop when one takes no edit (done), when the texts return to an earlier state (cycle), or after 16 rounds (limit). - Format and write. Every module that parses is then formatted, as
una fmtdoes. Each changed file is written once, through a temporary file and a rename;--dry-runwrites nothing. - Final check. The package is checked at the requested tier, 1 by default, and its diagnostics are those that remain.
- Human output. On stdout, one line per applied edit,
fixed <file>:<line>:<col> <code> <description>, at its position in the text of its round. Then one line per first repair with an edit that remains and was not applied,skipped <file>:<line>:<col> <code> <description>: <reason>. Then, when the rounds did not finish, astopped:line. The remaining diagnostics go to stderr. --json. It prints{"schema":"una.fix/1","dry_run":...,"rounds":n,"stopped":"done"|"cycle"|"limit","applied":[...],"skipped":[...],"formatted":[...],"diagnostics":[...]}, with keys in that order:- each applied edit is
{"round","file","code","description","start","end","replacement"}; - each skipped repair is
{"file","code","start","description","reason"}, wherereasoniswidens authority,escape cost,not a module,invalid UTF-8orround limit; formattedlists the files the format step changed;diagnosticsholds the remaining diagnostics.
- each applied edit is
- Exit codes. As for
una check, from the remaining diagnostics.
una obligations [path] prints one line per obligation, <status> <id> <kind> <file>:<line>:<col> <goal>, with (cached) for a cached result, and exits with code 1 when an obligation is not proven (ADR 0033).
Every command prints one JSON document with --json, its schema key first (ADR 0034). una explain --json <code> prints {"schema":"una.explain/1","code":...,"domain":...,"meaning":...,"text":...}. When the checks reject the package, una contract, una trace, una obligations and una report print the diagnostic list of una check and exit with code 1; una run and una test carry the diagnostics in their own documents. Usage errors stay on stderr, with exit code 2.
una contract <qualified.name> reads the package in the current directory and checks it at tier 0 (ADR 0029). The name is the module path followed by the function's name, as in events.checkin.check_in, and names a function. When the package has diagnostics, those of its project files included, una contract reports them as una check does and exits with code 1 before it resolves the name, since an inferred header is defined only for a package that checks (ADR 0036); in a package without diagnostics, an unknown name is a usage error (exit code 2). Otherwise it prints the doc comments, then the header in canonical form with every clause, declared or inferred, in canonical order, each inferred clause followed by the comment -- inferred, then one line per requirement of derived from: -- requirement ID (status): "text". With --json it prints una.contract/1, compact, with keys in this order:
{
"schema": "una.contract/1",
"function": "events.checkin.check_in",
"public": true,
"docs": ["Looks up a registration by phone, shows its availability, and records it."],
"header": "pub check_in(phone: secret[PII] Phone) -> Availability",
"constraints": [],
"requires": [],
"ensures": [],
"uses": [ { "cap": "registrations", "capability": "Registrations", "ops": ["find"], "inferred": false } ],
"fails": { "kind": "CheckInError", "inferred": false },
"diverges": false,
"derived_from": [ { "id": "EVENTS_3", "status": "active", "text": "..." } ]
}fails is null for a function that cannot fail, ops lists the operations in the declaration order of the capability, and docs holds the doc comments without their --- marker. (v0.2, ADR 0066.) The document also holds constraints, after header: the constrained type parameters, as {"param": "T", "constraint": "Ord", "inferred": false}, or [] (spec/20 §8). The key is additive, and the schema stays una.contract/1. (v0.2, ADR 0067.) The document also holds result_labels, after constraints: for a generic function, each position of its result whose summary is not empty, as {"position": "top", "from": ["T"]}, in the order of the positions in the declared type, or [] (spec/07 §7 rule 8). A position is written as its path: top, element, arg N, param N and result, joined by .. The human output prints them on one line after the header, positions separated by ; and type parameters by , , as -- result labels: top from T; element.arg 1 from T, U; a function with none prints no line. The key is additive, and the schema stays una.contract/1. (v0.2, ADR 0067 amendment.) The document also holds of_raises, after result_labels: each parameter that an of clause names whose calls depend on decisions on type parameters, as {"param": "k", "from": ["T"]}, or []; callers run their argument for it under the labels of those type arguments (spec/07 §7 rule 8). The human output prints them after the result labels as -- of raises: k from T. The key is additive. (Edition 0.4 preview, ADR 0116.) The document also holds diverges, after fails: true for a function whose header says diverges, else false. The key is additive, and the schema stays una.contract/1. (v0.3, ADR 0094 rule 3.) Each entry of uses also holds gives, after ops, when an operation of the binding gives a label, declared or inferred: {"op": "owner", "label": "internal[Service]"} for each such operation, in the order of ops. The key is left out when no operation gives a label, so the document of a package that labels none, every package of editions 0.1 and 0.2 among them, does not change. The human output prints an inferred clause's labels as a header writes them, uses @files: Files[owner gives internal[Service], create_link] -- inferred. The key is additive, and the schema stays una.contract/1.