aura push

Push commits to a Git remote and function deltas to the Mothership, with attached intent metadata.

Synopsis

aura push [--remote=<name>] [--mothership] [--git] [--branch=<name>] [--force-with-lease] [--tags] [--dry-run]

Description

aura push is the outbound counterpart to aura pull. It transmits your work to two destinations: the Mothership, which keeps teammates' function-level views in sync in near real time, and the Git remote, which stores the durable commit graph.

Most of the time you do not need to run aura push explicitly, because aura save calls it at the end of every save. You will reach for it directly in three situations: (1) you ran aura save --no-push earlier and now want to broadcast, (2) the previous push failed mid-flight and you want to retry, or (3) you want to push tags or a non-current branch without creating a new save.

The push carries more than bytes. Each function delta sent to the Mothership is tagged with the save_id of the commit that produced it, the author's agent identity (human, Claude, Gemini, etc.), the --intent string, the AST before/after hashes, and a pointer to the Git object so teammates' clients can fetch the full commit if they want. This is what lets teammates' aura status say "jamie is working on retry_logic — 'switching to exponential backoff'" before the Git commit ever lands on origin.

Flags

| Flag | Description | | --- | --- | | --remote=<name> | Named remote pair (Mothership + Git). Defaults to origin. | | --mothership | Only push to the Mothership. Skip the Git remote. | | --git | Only push to the Git remote. Skip the Mothership. | | --branch=<name> | Push a branch other than the current one. | | --force-with-lease | Allow a non-fast-forward push if the remote ref matches your last known state. | | --tags | Also push tags reachable from the pushed commits. | | --dry-run | Print what would be transmitted without sending. | | --drain | Flush queued Mothership deltas from previous offline saves, then exit. |

Note: plain --force is deliberately absent. Use --force-with-lease; Aura will refuse to push a force that silently clobbers a teammate's Mothership cursor.

Intent metadata sent along

Every Mothership payload for a save looks roughly like this (JSON shown for clarity):

{
  "save_id":        "sv_019abc...",
  "branch":         "feat/account-rename",
  "author": {
    "email":        "ashiq@naridon.io",
    "agent":        "claude-opus-4.6"
  },
  "intent":         "Rename User to Account throughout the codebase",
  "deltas": [
    {
      "node_id":    "n_fn_User__new",
      "path":       "src/models/user.rs",
      "op":         "rename",
      "new_id":     "n_fn_Account__new",
      "hash_before":"a17f3c1",
      "hash_after": "b42e90d"
    },
    { "node_id": "n_fn_api__users__handler", "op": "modify", "hash_after": "c019..." }
  ],
  "git_ref":        "refs/heads/feat/account-rename",
  "git_commit":     "3d22f0e..."
}

Teammates' clients ingest this and update their local logic graph. Only deltas and intent are broadcast to teammates' UIs; everything else is metadata.

Examples

1. Push after a no-push save

aura save --intent "Initial sketch of billing flow" --no-push
# ...later, after reviewing...
aura push

Pushes the local save's function deltas to the Mothership and the commit to origin. If multiple saves have accumulated, all of them are pushed in order.

2. Mothership-only push

aura push --mothership

Sends pending function deltas to the Mothership without touching the Git remote. Useful when you want teammates to see your work-in-progress immediately but are not yet ready to publish the commit. Mothership-only pushes are visible to teammates under a wip: prefix in their aura status.

3. Retry after a failed push

aura push --drain

If the Mothership was offline during your previous save, the deltas were queued locally. --drain flushes that queue and exits without creating new work. Pairs nicely with a post-network-outage checklist.

4. Push a branch and its tags

aura push --branch=release/0.12 --tags

Pushes the named branch plus all reachable tags. Mothership does not track tags; only the Git remote receives them.

5. Dry-run a force-with-lease

aura push --force-with-lease --dry-run

aura push (dry-run) — remote: origin

Git:
  force-with-lease: ok — remote tip matches expected 3d22f0e
  would push: feat/auth-rewrite  5 commits (3d22f0e..9b7a221)

Mothership:
  would push 12 deltas across 4 functions
  would retract 3 deltas from superseded commits

No changes sent.

The "retract" lines show deltas that will be un-broadcast because the rewritten commits no longer exist. Teammates' clients will roll back those function states to the pre-push version on their next pull.

Exit Codes

| Code | Meaning | | --- | --- | | 0 | Push completed to all requested destinations. | | 1 | Generic failure. | | 2 | Git remote rejected the push (non-fast-forward, hook failure, permissions). | | 3 | Mothership unreachable. Deltas remain queued locally. | | 4 | --force-with-lease check failed — the remote moved. Pull first. | | 5 | No remote of the given name is configured. |

Queue semantics

When the Mothership is reachable, deltas are sent synchronously as part of the push. When it is not, they are appended to a local queue under .aura/outbox/ and retried on the next push, pull, or save. The queue is durable across reboots; crashing mid-push cannot lose a delta.

Each queued delta carries the save_id it belongs to. If the same save_id is superseded by an amend, the queued delta is rewritten in place — the Mothership only ever sees the final version. This is important: teammates should not see work-in-progress from your --amend cycle, only the final intent and body.

The queue has a bounded size (default 1000 deltas per remote). If it fills, the oldest pending delta that has not yet been committed locally is dropped with a warning. Deltas backing a committed save are never dropped; they block the queue instead, and aura doctor will flag the condition.

Ordering guarantees

Mothership deltas from a single author arrive at each teammate in the order they were produced. Cross-author ordering is best-effort but causal: if delta B on your machine was produced after you pulled delta A from a teammate, teammates who receive B will also have received A. This is enough for interactive collaboration. It is not a total order; do not rely on it for consensus.

The Git push is a conventional git push under the hood, with all the standard guarantees (atomic ref update, hook invocation server-side, and so on). Aura does not attempt to interleave Mothership and Git atomically — the Mothership is a coordination layer, not a source of truth. If the Git push fails, the Mothership push that already succeeded is not rolled back; teammates will simply see a wip: delta that never finalizes into a commit. On your next successful save, the delta will be superseded.

What teammates see

When your push lands on the Mothership, each teammate's aura status updates within seconds to show a delta from you. Their incoming queue increments. If a teammate has aura watch running (a persistent status view), they see the function names and intent float by in real time. If you are editing a function a teammate is also editing, their Aura client raises a presence warning so they can pause and talk to you.

None of this requires them to git pull. The Mothership layer exists precisely to close the gap between the moment you save and the moment teammates know about it.

Configuration

[push]
default_remote        = "origin"
mothership_enabled    = true
push_on_save          = true
queue_on_offline      = true
max_queue_size        = 1000        # deltas, per remote
force_lease_required  = true

Teams often set push_on_save = false on release branches so only the release manager broadcasts; developers in that scenario explicitly run aura push when they want visibility.

Retry and backoff

Failed pushes are retried with exponential backoff: the first retry after 2 seconds, then 4, 8, 16, capped at 60 seconds between attempts. A persistent failure is reported via aura status and surfaces in aura doctor as MOT003. Transient failures — TLS handshakes, brief DNS hiccups, server restarts — resolve on their own within the first few retries and are invisible to the user.

Interactive saves do not wait for the full retry ladder; after the first failed attempt, the delta is queued and the command returns. Background retries continue. This keeps the developer loop fast even when the network is flaky.

Observability

Every push emits structured log events to .aura/logs/push.log: timestamp, remote, delta count, bytes, round-trip, success/failure. aura doctor --check=MOT003 parses these logs to detect stalls. Teams running self-hosted Mothership servers often aggregate these logs centrally to monitor team throughput.

Security

Intent strings and function bodies are sent to the Mothership. If your codebase contains secrets embedded in source (it should not), they will be transmitted. Aura scrubs common secret patterns (AWS keys, private key PEMs, JWT-shaped tokens) from function bodies before they leave the machine; strings that match one of these patterns are replaced with [REDACTED-AURA] in the broadcast, though the local commit is untouched. This is a best-effort filter, not a substitute for not committing secrets.