---
title: "una run"
url: https://una-lang.org/en/docs/cli/run/
release: v0.4.0
---

# una run

Run `main` of the `[run] entry` module.

```text
una run [OPTIONS] [PATH]
```

## Examples

```sh
una run .
```

Run the package's `main` with the grants its manifest lists.

```sh
una run . --grant console
```

Grant a capability from the command line.

## Arguments

| Argument | What it does | Default |
| --- | --- | --- |
| `[PATH]` | The package directory, or a single file | `.` |

## Options

| Option | What it does | Default |
| --- | --- | --- |
| `--grant <SPEC>` | Grant a host capability: `console`, `clock`, `env`, `keys:<file>`, `files:<path>:<access>`, `http:<origin>[:<methods>]` (edition 0.4: with `;<limit>` suffixes), or, from edition 0.4, `serve:<scheme>://<address>:<port>` with `;<item>` suffixes |  |
| `--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` |
| `--max-depth <N>` | The maximum call depth | `10000` |
| `--max-memory <MIB>` | The memory a run may hold, in MiB: 4096 by default, or the package's declared max_memory, which it may lower and never raise |  |
| `--max-response <MIB>` | The largest HTTP response body, in MiB | `16` |
| `--http-timeout <SECONDS>` | The total time of each HTTP request, in seconds | `30` |
| `--workers <N>` | The threads that run tasks, from 1 to 1024; by default one per core |  |
| `--task-depth <N>` | The depth limit of the tasks of `first of` and `start`, from 1 to --max-depth; by default 1000 |  |
| `--io-threads <N>` | The helper threads of `Http`, from 1 to 4096; by default 64. A run granted `Http` starts 2 x N + max(2, N / 4) threads for its requests before `main`, besides --workers and --file-threads, so a large N can pass the system's limit on a process's threads, and the run then stops with U6003 |  |
| `--file-threads <N>` | The helper threads of `Files` and `Console`, from 1 to 256; by default 4 |  |
| `--serve-threads <N>` | The threads that serve the connections of `serve:` grants, from 1 to 256; by default one per core. Accepted and unused by a run that does not serve |  |
| `--solver-wallclock <SECONDS>` | Stop a solver query after this many seconds; the obligation is then unknown | `60` |
| `--solver-memory <MIB>` | The memory limit of each solver query in MiB, from 256 to 1048576 | `4096` |
| `--stop-after-iterations <N>` | A budget of this many iterations for each `for ever` loop, the driver's loop included: each loop instance ends at the start of its iteration N + 1; no host stop request |  |
| `--virtual-time` | Run on a virtual clock that starts at 0 and never waits |  |
| `--cost-clock` | With --virtual-time: each check point (call, operation, loop iteration) moves the virtual clock by one millisecond, so time follows the run's work; the security hunt's cost-clock oracle |  |
| `--deadline <SECONDS>` | Request a host stop after this many seconds, from 1 to 31536000 |  |
| `--stop-grace <SECONDS>` | The seconds from the first host stop request to the hard stop, from 1 to 86400 | `10` |
| `--trace <FILE>` | Write the trace to this file as a JSON array, each event as it happens |  |

## Specification

The normative rules, from spec/13 §5:

| Command | Meaning |
| --- | --- |
| `una run [path]` | Run `main` of `[run] entry`; `--grant <spec>` repeated |

`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`).


## Help text

As `una run --help` prints it at v0.4.0:

```text
Run `main` of the `[run] entry` module

Usage: una run [OPTIONS] [PATH]

Arguments:
  [PATH]
          The package directory, or a single file

          [default: .]

Options:
      --grant <SPEC>
          Grant a host capability: `console`, `clock`, `env`, `keys:<file>`, `files:<path>:<access>`, `http:<origin>[:<methods>]` (edition 0.4: with `;<limit>` suffixes), or, from edition 0.4, `serve:<scheme>://<address>:<port>` with `;<item>` suffixes

      --json
          Print machine output as JSON on stdout, and nothing else on stdout

      --color <WHEN>
          When to use colors in human output

          Possible values:
          - never:  Never use colors
          - auto:   Use colors when the output is a terminal
          - always: Always use colors

          [default: auto]

      --max-depth <N>
          The maximum call depth

          [default: 10000]

      --max-memory <MIB>
          The memory a run may hold, in MiB: 4096 by default, or the package's declared max_memory, which it may lower and never raise

      --max-response <MIB>
          The largest HTTP response body, in MiB (`spec/24 §4`)

          [default: 16]

      --http-timeout <SECONDS>
          The total time of each HTTP request, in seconds (`spec/24 §4`)

          [default: 30]

      --workers <N>
          The threads that run tasks, from 1 to 1024; by default one per core (ADR 0117)

      --task-depth <N>
          The depth limit of the tasks of `first of` and `start`, from 1 to --max-depth; by default 1000 (ADR 0117)

      --io-threads <N>
          The helper threads of `Http`, from 1 to 4096; by default 64 (ADR 0117). A run granted `Http` starts 2 x N + max(2, N / 4) threads for its requests before `main`, besides --workers and --file-threads, so a large N can pass the system's limit on a process's threads, and the run then stops with U6003

      --file-threads <N>
          The helper threads of `Files` and `Console`, from 1 to 256; by default 4 (ADR 0117)

      --serve-threads <N>
          The threads that serve the connections of `serve:` grants, from 1 to 256; by default one per core (ADR 0123). Accepted and unused by a run that does not serve

      --solver-wallclock <SECONDS>
          Stop a solver query after this many seconds; the obligation is then unknown

          [default: 60]

      --solver-memory <MIB>
          The memory limit of each solver query in MiB, from 256 to 1048576 (ADR 0124)

          [default: 4096]

      --stop-after-iterations <N>
          A budget of this many iterations for each `for ever` loop, the driver's loop included: each loop instance ends at the start of its iteration N + 1; no host stop request (ADR 0116)

      --virtual-time
          Run on a virtual clock that starts at 0 and never waits (ADR 0116)

      --cost-clock
          With --virtual-time: each check point (call, operation, loop iteration) moves the virtual clock by one millisecond, so time follows the run's work; the security hunt's cost-clock oracle (ADR 0117, `spec/27 §8`)

      --deadline <SECONDS>
          Request a host stop after this many seconds, from 1 to 31536000 (ADR 0116)

      --stop-grace <SECONDS>
          The seconds from the first host stop request to the hard stop, from 1 to 86400 (ADR 0116)

          [default: 10]

      --trace <FILE>
          Write the trace to this file as a JSON array, each event as it happens (ADR 0117)

      --serve-script <FILE>
          Toolchain test builds only: a shipped `una` reads and checks the file, then refuses the run as a usage error. Replace the listeners of the `serve:` grants with the connections this file describes, one JSON object per line; needs --virtual-time (ADR 0123, `spec/31 §8`)

      --serve-out <FILE>
          Toolchain test builds only, as --serve-script is. Write what each scripted connection received to this file; needs --serve-script (ADR 0123)

  -h, --help
          Print help (see a summary with '-h')
```
