awa run

run a command with caching and supervised history.

awa run [run flags] -- <command> [args...]
awa run <subcommand> [flags]   (ls, log, show, rm, explain)

Tokens after --

Tokens after -- are the wrapped command and its arguments; awa passes them through unchanged.

Global options

• --root <path> — project root override
• --config <path> — config file override
• --json — emit schema-versioned JSON
• --trust-mode <mode> / --strict — cache trust level (normal|strict|fast)

Supports --json (schema-versioned output).

Flags

• --display <mode> — terminal display: full|summary|tail:<n>|none (default: full)
• --record — execute and record evidence, never a reusable hit
• --refresh — ignore any cache hit and write a fresh entry
• --no-cache — do not read or write the cache
• --no-cache-failures — do not cache a failing command
• --scope <path> — replace the run input scope
• --include <path> — add an input path to the scope
• --exclude <path> — remove an input path from the scope
• --cwd <path> — run the command in this directory (inside the root)
• --allow-skipped-inputs — allow a cache hit when some inputs were skipped
• --allow-tty — attach the terminal to the child; forces non-cacheable

Exit status

exit code: awa run returns the wrapped command's own exit code after a hit or a miss. Because that can overlap awa's 1-6 codes, use --json (run.exit_origin) or the run log to tell an awa-origin failure from a child result.

Subcommands

awa run ls

list reusable runs for the current state.

awa run ls [--all] [--near] [-n <count>] [--command <substr>] [--time <mode>]

Tokens after --

A token after -- is a usage error: this command takes no operands.

Global options

• --root <path> — project root override
• --config <path> — config file override
• --json — emit schema-versioned JSON
• --trust-mode <mode> / --strict — cache trust level (normal|strict|fast)

Supports --json (schema-versioned output).

Flags

• --all — also list non-reusable runs, each with a reason
• --near — add the nearest near-miss section
• -n, --limit <count> — show at most <count> entries
• --command <substr> — filter to runs whose command contains <substr>
• --time <mode> — time display: relative|utc|local (human only) (default: [ui].time)

Workflow

See awa help run.

awa run log

list recorded runs, newest first.

awa run log [-n <count>] [--command <substr>] [--time <mode>]

Tokens after --

A token after -- is a usage error: this command takes no operands.

Global options

• --root <path> — project root override
• --config <path> — config file override
• --json — emit schema-versioned JSON

Supports --json (schema-versioned output).

Flags

• -n, --limit <count> — show at most <count> entries
• --command <substr> — filter to runs whose command contains <substr>
• --time <mode> — time display: relative|utc|local (human only) (default: [ui].time)

Workflow

See awa help inspect.

awa run show

show one run's metadata and stored output.

awa run show <id>|--last [--meta|--stdout|--stderr] [--tail <n>] [--grep <re>]

Tokens after --

A token after -- is a usage error: this command takes no operands.

Global options

• --root <path> — project root override
• --config <path> — config file override
• --json — emit schema-versioned JSON

Supports --json (schema-versioned output).

Flags

• --last — select the most recent readable run
• --meta — metadata only (no output)
• --stdout — write the stored stdout stream
• --stderr — write the stored stderr stream
• --tail <n> — only the last <n> lines of the selected output
• --grep <re> — only output lines matching <re>
• --time <mode> — time display: relative|utc|local (human only; [ui].time is not read here) (default: relative)

Workflow

See awa help inspect.

awa run rm

delete stored runs by id or filter.

awa run rm <id>... | (--command <substr> | --older-than <dur>) [--dry-run]

Tokens after --

A token after -- is a usage error: this command takes no operands.

Global options

• --root <path> — project root override
• --config <path> — config file override
• --json — emit schema-versioned JSON

Supports --json (schema-versioned output).

Flags

• --command <substr> — delete runs whose command contains <substr>
• --older-than <dur> — delete runs older than <dur> (e.g. 720h)
• --dry-run — report what would be removed without deleting

Workflow

See awa help inspect.

awa run explain

explain how the run cache would behave.

awa run explain -- <command> [args...]
awa run explain --last
awa run explain --from-run <id> --to-now

Tokens after --

Tokens after -- are the wrapped command and its arguments; awa passes them through unchanged.

Global options

• --root <path> — project root override
• --config <path> — config file override
• --json — emit schema-versioned JSON
• --trust-mode <mode> / --strict — cache trust level (normal|strict|fast)

Supports --json (schema-versioned output).

Flags

• --last — explain the most recent recorded run
• --from-run <id> — explain a stored run's inputs against now (needs --to-now)
• --to-now — compare the selected run's inputs to the current state
• --scope <path> — replace the run input scope (command mode)
• --include <path> — add an input path to the scope (command mode)
• --exclude <path> — remove an input path from the scope (command mode)
• --cwd <path> — resolve the key as if run in this directory (command mode)
• --refresh — model run's --refresh policy (command mode)
• --no-cache — model run's --no-cache policy (command mode)
• --no-cache-failures — model run's --no-cache-failures policy (command mode)
• --allow-skipped-inputs — model run's --allow-skipped-inputs policy (command mode)
• --allow-tty — model run's --allow-tty stdin (command mode)

Workflow

See awa help run.

Workflow

See awa help run.