Home / Docs

Command line

Release v0.4.0

Una, a verification-first programming language for machine-generated software.

text
una [OPTIONS] <COMMAND>
una --version [--json]

Commands

Command What it does
una check Check a package: tiers 0 and 1
una trace List the functions derived from a requirement, their contracts and their obligations
una core Print the package's Core IR; with --json, as una.core/1
una report Print the build report: proofs, authority, information flow, trust and coverage
una obligations List every proof obligation with its status
una fix Apply the mechanical repairs of una check, then format, and report what remains
una fmt Rewrite files in canonical form, or report where they differ from it
una ita The package manager of edition 0.4: dependencies, ita.una and ita.lock
una migrate Move a package from una.toml to ita.una and ita.lock, edition 0.4
una run Run main of the [run] entry module
una build Compile main of the [run] entry module into a native executable
una test Run every test (example in editions 0.1 and 0.2)
una contract Print the full header of a function, declared or inferred, with doc comments and requirements
una explain Explain a diagnostic code
una lsp Serve the language server on stdin and stdout, for editors

Options

Option What it does Default
--json Print machine output as JSON on stdout, and nothing else on stdout
--color <WHEN> When to use colors in human output. Values: never: Never use colors; auto: Use colors when the output is a terminal; always: Always use colors. auto
--version Print the version, the editions and the pinned Z3 version, and exit

Specification

The normative rules, from spec/13 §5:

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.

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.

View the Markdown