# aura status

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

## Synopsis

```bash
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:

```text
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

```bash
aura status
```

### 2. Fit it in a shell prompt

```bash
aura status --short
```

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

### 3. JSON for tooling

```bash
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

```bash
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

```bash
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:

```text
[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.

## See Also

- [aura doctor](/aura-doctor) — fix issues surfaced by status
- [aura pull](/aura-pull) — drain the incoming queue
- [aura push](/aura-push) — drain the outgoing queue
- [aura diff](/aura-diff) — see what the pending node changes actually are
- [aura save](/aura-save) — the primary action you take after reading status