---
title: "13.5 Command line"
url: https://una-lang.org/en/docs/spec/13-diagnostics-and-abi/5-command-line/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/spec/13-diagnostics-and-abi.md
---

# 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`, then `rank`) is a candidate. It is applied when all of these hold:
  - its `edit` is not `null`;
  - its `escape_cost` is 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.toml` or `verification.lock`, nor (edition `0.4`) `ita.una`, `ita.lock` or `itaty.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 as `widens authority`.
  - (ADR 0084, amendments of 2026-10-14 and 2026-10-15.) Of tier 1, only the first repair of a refuted `effect_condition` obligation (U5001) or of a refuted `contract_lock` obligation (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, never `una.toml`.
- (v0.3, ADR 0105 rule 3 and its amendment of 2026-11-05.) **The rewrite of `example` to `test`** is a candidate in packages of edition `0.3` only, the migration from editions `0.1` and `0.2`: only there is `example` at column 1 a U0103 that carries it (`spec/01 §5`). In editions `0.1` and `0.2` `example` is the declaration keyword, and in edition `0.4` it is an identifier, so `una fix` never 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 fmt` does. Each changed file is written once, through a temporary file and a rename; `--dry-run` writes 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, a `stopped:` 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"}`, where `reason` is `widens authority`, `escape cost`, `not a module`, `invalid UTF-8` or `round limit`;
  - `formatted` lists the files the format step changed;
  - `diagnostics` holds the remaining diagnostics.
- **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:

```json
{
  "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`.
