RFC-012: CLI

1. Abstract

This RFC defines the unified aura CLI (implemented in Rust): the single entrypoint for create, build, run, test, check, format, package, and toolchain management. Subcommands delegate to compiler, package manager, build, and test subsystems while presenting a consistent UX, exit codes, and machine-readable output modes.

Toolchain today (2026-07-21, C12r): shipped subcommands — new, init, version, check, build, run, test, emit-c on files or package dirs (aura.toml). aura run / aura test forward args after -- to the process (C12c); programs read argv via std.io.args(). Pretty diagnostics with line:col snippets. Not yet: fmt, registry/add/publish, JSON machine output, release profiles beyond basic link.

2. Motivation

2.1 Problem statement

Fragmented tools (fmt, build, pkg as separate binaries with divergent flags) harm onboarding. One CLI is part of the language product (RFC-000 P5).

2.2 Why now

All toolchain RFCs need a user-facing contract.

2.3 Success metrics

Metric	Target
Discoverability	`aura --help` covers daily verbs
Scriptability	Stable exit codes + JSON modes
Speed	`aura check` optimized path (no full link)

3. Goals

One binary: aura.
Daily workflow verbs with Cargo/Go-like familiarity.
Consistent global flags (--verbose, --color, --dir).
Extensibility via subcommands; avoid plugin free-for-all in MVP.

4. Non-goals

Interactive TUI IDE replacement.
Cross-language task runner (Make/npm scripts platform).
Guaranteed stable output formatting of human text (JSON is stable).

5. Prior art & alternatives

CLI	Notes	Take
cargo	Subcommand UX	Primary
go	Simple verbs	Inspiration
npm	Scripts culture	Contrast
git	Ubiquity	Help style

6. Design

6.1 Command map

Command	Purpose
`aura new <name>`	Scaffold project
`aura init`	Manifest in existing dir
`aura build`	Compile & link
`aura run [path] [-- args…]`	Build (if needed) + execute bin; args after `--` go to the process
`aura check`	Typecheck/parse without full link
`aura test [path] [-- args…]`	Build & run tests; same `--` pass-through as `run`
`aura fmt`	Format sources
`aura fix`	Apply machine-applicable fixes (later)
`aura doc`	Generate docs (later)
`aura add` / `remove`	Dependencies
`aura update`	Update lock within constraints
`aura tree`	Dep graph
`aura publish`	Publish package
`aura clean`	Remove target/
`aura version` / `aura toolchain`	Version & install (RFC-013)

6.2 Global flags

code

--help, -h
--version, -V
--verbose, -v
--quiet, -q
--color auto|always|never
--directory, -C <path>
--offline

6.3 Output & exit codes

Code	Meaning
0	Success
1	General / test failure / compile error
2	CLI usage error
>2	Reserved (signals-related)

--format json on check/test where supported for tooling.

6.4 Configuration

Project: aura.toml
User: ~/.aura/config.toml (proxy, registry, defaults)
Env: AURA_* overrides documented

6.5 Formatting (`aura fmt`)

Deterministic formatter; CI --check mode.
Config subset in aura.toml [fmt] (line width, etc.).

6.6 UX principles

Prefer sensible defaults over required flags.
Errors: compiler diagnostics passthrough with summary.
Never delete src/ on clean.

6.7 Examples