aura status

The cockpit: tracked logic nodes, active session, pending saves, team sync, and impact alerts.

Synopsis

aura status [--short] [--json] [--team] [--impacts] [--no-fetch]

Description

aura status is the command you run first and most often. It prints a structured view of your repository's Aura state and the parts of the outside world Aura cares about: your session, your pending saves, the strict-mode configuration, the Mothership sync queue in both directions, the current team zones, any unread messages, and any unresolved cross-branch impact alerts.

By default, aura status performs a fast read from local state and makes one lightweight call to the Mothership to refresh sync counts. Use --no-fetch to skip that call if you are offline or in a loop.

Output walkthrough

A full status output, section by section:

aura status  (repo: aura-cli, branch: feat/account-rename, v0.12.6)

Semantic index
  tracked logic nodes:     1,842
  indexed files:             127
  index age:                 12s
  last full reindex:         2026-04-20 09:14

Session
  id:                       ses_019ff3
  started:                   2026-04-21 08:42  (2h 14m)
  agent:                     claude-opus-4.6
  intents logged:            5
  snapshots taken:           11
  saves created:             3  (all pushed)

Working tree
  modified files:            4
  staged for save:           2
  semantic changes pending:  6 nodes  (+1 ~4 1-renamed)

Strict mode
  enabled:                   true
  locked:                    true   (passcode required to disable)
  last violation:            none in this session

Team sync            (mothership: origin-mothership  status: online)
  peers online:              3   (jamie, li, rohan)
  incoming queue:            7 deltas pending  -> run: aura pull
  outgoing queue:            0
  last push:                 11:40 (sv_019abc)
  last pull:                 09:58

Team zones
  src/payments/**            owned by: jamie   (BLOCKED for you)
  src/api/accounts.rs        claimed by: you

Cross-branch impacts
  2 unresolved:
    4a1  fn auth::verify_token was modified on feat/auth-rewrite
         your branch calls it from: fn api::middleware::require_auth
    4a2  fn db::User was deleted on feat/account-rename
         your branch references it from: fn api::users::handler

Messages
  TEAM:     1 unread  — jamie: "heads up, I'm taking over payments for a bit"
  SENTINEL: 0 unread

Checkpoints
  last checkpoint:           11:12  (sv_019a91, "Before merging account rename")

Plans
  active plan:               none
  saved proofs:              4 registered; last run 09:58, all PROVED

Each section is optional — if there are no incoming deltas, no impacts, no messages, and no plans, those sections collapse. The --short mode collapses aggressively and fits in one screen.

Section meanings

Semantic index. The cache of tracked nodes. A stale index (age > 10 min) is refreshed on next aura save. You can force it with aura doctor --reindex.
Session. An Aura session starts with your first command and ends on explicit aura session end or after several hours of inactivity. Saves, snapshots, and intents are grouped under it.
Working tree. modified files and staged for save mirror Git. semantic changes pending is the more useful count: how many logic nodes would be written by the next save.
Strict mode. locked: true means this setting cannot be disabled from the CLI without a passcode. This is how teams prevent --no-verify escape hatches.
Team sync. The Mothership side. incoming queue is the teammate work you have not pulled; outgoing queue is your work waiting to ship. A healthy workflow keeps both near zero.
Team zones. File globs other developers have claimed. BLOCKED means your saves touching those paths will be rejected; WARNING means they go through but with a notification to the owner.
Cross-branch impacts. Alerts when a function you depend on was modified or deleted on another branch. Each alert has an id you can pass to aura live resolve.
Messages. TEAM channel (human and agent mixed) and SENTINEL (AI-to-AI). Unread counts trigger a reminder; read them with aura msg list and aura sentinel inbox.
Checkpoints. Manual save markers you can rewind toward.
Plans. Set by aura plan discover. A live plan shows the current wave.

Flags

| Flag | Description | | --- | --- | | --short | One-line-per-section summary. Good for shell prompts. | | --json | Machine-readable, full detail. | | --team | Only the team-related sections (sync, zones, messages, impacts). | | --impacts | Only the cross-branch impact section; exit 2 if any are unresolved. | | --no-fetch | Skip the Mothership refresh. Print cached state. |

Examples

1. The default

aura status

2. Fit it in a shell prompt

aura status --short

aura: 1842 nodes · 4 files dirty · 6 pending nodes · strict · sync 7 in/0 out · 2 impacts · 1 msg

3. JSON for tooling

aura status --json | jq '.team_sync.incoming_queue'

The full schema is documented in the JSON output itself under $schema.

4. CI gate on unresolved impacts

aura status --impacts

Exits 0 if there are no unresolved cross-branch impacts, 2 otherwise. Useful as a pre-merge check in CI.

5. Offline status

aura status --no-fetch

Skips Mothership; useful on flaky networks. The team sync section is labelled status: cached with the age of the cached data.

Exit Codes

| Code | Meaning | | --- | --- | | 0 | Status printed successfully. | | 1 | Generic failure (repo not initialized, index corrupt). | | 2 | --impacts was set and unresolved impacts exist. |

Using status in shell prompts

Many teams wire aura status --short into their shell prompt via the prompt-hook or starship. A dirty working tree, a pending impact, or a non-zero incoming queue becomes visible at a glance. The --no-fetch variant is appropriate for this use case because a shell prompt must not block on the network.

Example starship snippet:

[custom.aura]
command  = "aura status --short --no-fetch"
when     = "aura status --no-fetch --json | jq -e '.repo' >/dev/null"
format   = "[$output]($style) "

Integration with agents

When an AI agent starts a session, its first call is almost always aura status (via the MCP tool aura_status). The agent uses the output to decide whether to pull teammate changes, respect an active zone, read team messages, or continue work on a plan. Status is the agent's orientation point; the output format is stable and documented specifically so agents can parse it reliably.

The most common agent mistake is ignoring incoming queue non-zero. The second most common is ignoring a zone BLOCKED. Both are surfaced prominently in status output; teams that review agent transcripts learn to look for these signals first.

What changes between invocations

aura status is not a static snapshot; it reflects the live state of your local Aura index, the Mothership, and the working tree. Between two invocations seconds apart, you might see the incoming queue change (a teammate saved), a message arrive (a teammate messaged), an impact appear (a teammate's delta now collides with your uncommitted code), or a zone change hands (a teammate released a claim you were waiting on). This is the intended use — aura status is a living dashboard, not a log.

The command is deliberately cheap. A full status with a fresh Mothership refresh typically returns in under 200 ms on a healthy repository. Without the refresh it returns in under 50 ms, which is fast enough for shell prompts and for tight scripting loops.

Typical status states and what to do

A repository cycles through a small set of states; recognizing them shortens the time from aura status to action.

Clean and synced. Working tree clean, incoming queue zero, outgoing queue zero, no impacts, no messages. Do whatever you came to do; no housekeeping required.

Teammate activity pending. Incoming queue non-zero. Run aura pull before editing files teammates might have touched, especially if your next change is in a shared area.

Your work staged but unpushed. Outgoing queue non-zero and last push not recent. Usually means a previous save happened with --no-push or a push failed. Run aura push --drain.

Impacts outstanding. One or more unresolved cross-branch impacts. Review each with aura live impacts --show <id>; fix or acknowledge; resolve with aura live resolve <id>. Strict mode will block the next save otherwise.

Merge in progress. A MERGE_AURA section appears with unresolved function-level conflicts. Finish with aura merge --continue or abort with aura merge --abort.

Plan active. A plan with a current wave. Run aura plan next to get the wave's tasks.

Zone blocked. Your current file is owned by a teammate and marked BLOCKED. Coordinate via aura msg send before editing.

Prompt hygiene

The purpose of aura status is to surface exactly the signals that change how you should act. If a section is healthy, it collapses. A clean, synced, zone-free repository produces a four-line status. A repository with an active plan, pending impacts, and an unread team message produces the full cockpit. The intended experience is that aura status either tells you "nothing to worry about" in under a second, or tells you exactly what to do next.