CLI

aura eval <file.aura>  [--strict] [--dry-run] [--frozen]
                       [--allow-read=<dir>]... [--allow-env[=A,B]] [--allow-imports-io]
                       [--hermetic] [--max-steps=N] [--max-memory=MB] [--stats]
                       [--format json|json-flat|yaml|toml] [-o out] [--registry-dir=<dir>]
aura check <file.aura> [--strict] [--hermetic]
aura docs --agent [-o <file>]
aura fmt <files...> [--check]
aura types <file.aura> --lang rust|ts|go [--out <file>]
aura add <path>@vX.Y.Z [--from <file>] [--registry-dir=<dir>]
aura --version

eval

Evaluates a manifest with all its imports and prints the result.

check

Lex, parse and static analysis only — a fast gate for pre-commit hooks and CI.

--hermetic additionally requires that the manifest performs no I/O: env() and read_file() anywhere in it, or in anything it imports, is E0505. It is decided statically, so check answers it without evaluating — including for branches that this particular run would not have taken:

$ aura check --hermetic deploy.aura
[E0505] Error: env() is not allowed in hermetic mode
   ╭─[ deploy.aura:4:11 ]

Reach for it when a manifest’s output must depend on nothing but its own text: a CI gate on a directory of manifests, or a build whose result you want to be reproducible on another machine. eval --hermetic enforces the same thing, and is the right flag when the manifest is untrusted.

A script written for an application that provides host functions (D35) imports them as import "host:geo" as geo. The CLI has no host, so eval stops with E0007; check lists what the script needs from the application that will run it, and exits 0:

$ aura check routing.aura
note: provided by the application at run time, this script calls:
  geo.region (1 argument)
  flags.enabled (2 arguments)
ok: routing.aura

docs

aura docs --agent prints the complete language reference — syntax, the standard library, every diagnostic code — assembled from the compiler’s own definitions. It is about four thousand tokens, which is small enough to hand to a coding assistant whole.

The reason to print it from the binary rather than link to a page is versions: the output describes the aura that produced it, and cannot drift the way a hosted document can.

The most useful way to use it is to let the assistant fetch it. One line in your repository’s AGENTS.md, CLAUDE.md or equivalent:

Before writing or editing .aura files, run `aura docs --agent` for the complete
language reference.

Or commit it, for assistants that read files but cannot run commands:

$ aura docs --agent -o AURA.md

The same text is published at /llms.txt for tools that fetch over the network.

fmt

The canonical formatter: indentation (two spaces per level, by token depth), intra-line spacing, and column alignment of runs of name = value, key: value and cond arms together with their trailing comments. Strings and the contents of block strings are left alone; the token stream is guaranteed not to change, and formatting is idempotent. --check only checks, exiting 1 if anything differs.

types

Generates host-language types from the type and enum declarations:

aura types config.aura --lang ts

The six built-in field types map like this:

String is the only name the language accepts for a text field — there is no Str.

Note the last two rows. A schema’s List and Object carry no element type, so the generated code cannot either: you get a sequence or a map of untyped values. Where the shape matters, declare a type for the element and let the field hold that instead.

One schema both validates the config and types the service that reads its JSON. An enum becomes a string-literal union (TypeScript), an enum with #[serde(rename)] (Rust), or a named string with typed constants (Go). Optional fields (D15) are emitted as required, because evaluation always substitutes the default. Parsing only: the manifest is not evaluated and no capabilities are involved. --out writes to a file.

The output is already canonical for the host language’s formatter — rustfmt --check, gofmt -l and prettier --check stay silent on the generated files — so it can be committed into a service’s repository without formatting churn in diffs.

add

Installs a package: downloading it (github/<owner>/<repo> → package.aura at tag vX.Y.Z; an exact version is mandatory), validating it, writing it to the cache and recording it in ./aura.lock with an integrity hash. --from <file> installs from a local file instead. This is the only command that uses the network.

Exit codes