aura pull

Pull function-level changes from teammates via the Mothership, or commits via a Git remote.

Synopsis

aura pull [--remote=<name>] [--mothership] [--git] [--branch=<name>] [--rebase|--merge] [--dry-run]

Description

aura pull brings changes from remote sources into your working tree. It understands two remote kinds and will use both by default.

The Mothership is Aura's real-time coordination server. When a teammate runs aura save, the bodies of every function they touched — along with the intent text — are streamed to the Mothership as semantic deltas. aura pull fetches any deltas newer than your last cursor and applies them to your logic graph at the function level. Because these deltas are AST-shaped, applying one does not require creating a Git commit: the change lives in your working tree, optionally staged, and shows up in aura status as an incoming patch.

The Git remote is the underlying source of truth for durable history. aura pull fetches from the configured branch, then either merges or rebases in the normal way, but hands conflict resolution to aura merge so that conflicts are function-scoped rather than line-scoped.

By default, aura pull does both: it drains the Mothership queue first (fast, often zero conflicts because deltas are function-granular), then fetches from the Git remote (slower, carries whole-commit history). If you only want one, pass --mothership or --git.

Flags

| Flag | Description | | --- | --- | | --remote=<name> | Name of a configured Mothership or Git remote. Defaults to origin and the Mothership bound to it. | | --mothership | Only pull from the Mothership. Skip the Git fetch/merge. | | --git | Only pull from the Git remote. Skip the Mothership drain. | | --branch=<name> | Pull a branch other than the currently checked-out one. | | --rebase | Rebase local commits onto the fetched tip after the Git fetch. | | --merge | Merge instead of rebase (default). | | --dry-run | Show what would be pulled without applying anything. | | --stop-on-impact | Abort the pull if applying deltas would generate new cross-branch impact alerts. |

Mothership vs Git remote

| | Mothership pull | Git pull | | --- | --- | --- | | Granularity | One function body at a time | Entire commits | | Latency | Seconds (streamed on aura save) | Whenever you pull | | Creates commits? | No — deltas land as staged changes | Yes | | Conflict model | Function-level, surfaced as impact alerts | Three-way merge via aura merge | | Carries intent? | Yes — each delta has the teammate's --intent string | Only the commit message | | Works offline? | No | Yes (after last fetch) |

The two channels are complementary, not redundant. The Mothership gives you sub-minute awareness of what teammates are touching while they are still working. The Git remote gives you durable, signed history after the fact.

Conflict Surfacing

Mothership deltas cannot produce merge conflicts in the Git sense, because they arrive before anything has been committed. Instead they produce impact alerts when an incoming delta touches a function your uncommitted code depends on:

aura pull --remote origin

Pulled 7 function updates from mothership origin
Applied cleanly:  5
Impact alerts:    2

  alert 4a1: fn auth::verify_token was modified by jamie@aura
             you have uncommitted callers: fn api::middleware::require_auth
             run: aura live impacts --show 4a1

  alert 4a2: fn db::User was deleted by jamie@aura
             you have uncommitted code referencing: fn api::users::handler
             run: aura live impacts --show 4a2

Then: aura live resolve <id>

Resolve each alert (fix the caller, or acknowledge that the change is fine), then continue. Unresolved alerts block your next aura save in strict mode.

Examples

1. Routine sync at the start of a session

aura pull

Drains the Mothership queue, fetches the current branch from origin, and fast-forwards or merges as needed. This is typically the first command of a working session.

2. Pull only teammate function updates

aura pull --mothership

No Git fetch. Useful when the Git remote is slow (e.g. behind a VPN) but the Mothership is fast, or when you want to see what teammates are working on without pulling commits.

3. Rebase-pull a feature branch

aura pull --git --branch=main --rebase

Fetches main from origin and rebases the current branch onto it, using aura merge's semantic engine for any conflicts. Skips the Mothership.

4. Dry-run before a risky pull

aura pull --dry-run

aura pull (dry-run) — remote: origin

Mothership:
  7 deltas pending from: jamie@aura (4), li@aura (3)
  would touch 9 functions across 5 files
  impact alerts predicted: 2

Git:
  origin/feat/search is 3 commits ahead
  would require merge (non-fast-forward)
  semantic conflicts predicted: 0

No changes applied.

5. Stop if the pull would surface impacts

aura pull --stop-on-impact

If applying Mothership deltas would generate any new impact alerts, the pull aborts before touching the working tree. Use this in CI or in a paranoid workflow where you want to manually review each teammate's change before merging it.

Exit Codes

| Code | Meaning | | --- | --- | | 0 | Pull completed. Any alerts reported are informational, not failures. | | 1 | Generic failure (network, auth, corrupt index). | | 2 | Git merge conflicts remain. Resolve and run aura merge --continue. | | 3 | Impact alerts were generated and --stop-on-impact was set. Nothing applied. | | 4 | No configured remote matches the requested name. | | 5 | Local branch has diverged and neither --rebase nor --merge was specified. |

Pull cadence

There is no "right" pull frequency, but a few patterns work well. Session-start pull — always run aura pull as the first command after opening the repo for a work session. This drains any deltas that arrived overnight and gives you a truthful status. Pre-edit pull — before editing a file you know teammates are also working on, pull first. Post-break pull — after stepping away for more than ~30 minutes. Pre-save pull — strict-mode teams configure the pre-commit hook to refuse a save if the incoming queue exceeds a threshold, which enforces this implicitly.

Pulling a specific teammate's work

aura pull --mothership --from jamie@naridon.io

Filters the incoming queue to a single author. Useful when you want to fast-follow a specific teammate's in-progress feature without pulling everyone else's noise. The filter also accepts agent names (e.g. claude-opus-4.6) for when an AI collaborator is producing deltas alongside humans.

How Mothership deltas are applied

A Mothership delta is a tuple (node_id, op, body_after, parent_hash, metadata). When Aura pulls a delta, it performs three operations in order.

First, it locates the target node in your local semantic index by node_id. If the node does not exist (it was added in the delta), the target is a new insertion. If it exists but its current hash does not match the delta's parent_hash, the delta is non-fast-forward — your local copy has diverged from the sender's starting point. Non-fast-forward deltas become impact alerts.

Second, it writes the body into the working tree at the node's current location. Writes are line-preserving where possible: only the function's body region is rewritten, and surrounding code is untouched. If the node was moved locally since the last pull, the delta is applied to the node's new location automatically.

Third, it updates the cursor. Each Mothership stream maintains a per-repo cursor recording the last delta you ingested. The cursor advances as deltas apply; partial failures roll back cleanly.

Deltas do not produce commits. They stage a change in your working tree and the Aura index, and that is all. The teammate's eventual Git commit still has to land via aura pull --git or a routine git fetch; the Mothership delta is the advance warning.

Handling a large incoming queue

After a long absence — a vacation, a long-running feature branch kept in isolation — the Mothership queue can have hundreds of deltas pending. Applying them all at once is usually fine, but if many touch the same functions, the result can be noisy. Two options.

Collapse the queue. Run aura pull --mothership --collapse. Deltas touching the same function are folded so only the final body is applied; intermediate deltas are skipped (they are still visible in the trace). This produces a clean working tree without intermediate states.

Follow the queue incrementally. Run aura pull --mothership --limit 20 repeatedly. Each batch applies 20 deltas; in between, run aura diff to see what landed. This is slower but gives you a better feel for what teammates did while you were away.

Authentication and transport

Mothership pulls use the team token from ~/.aura/config.toml (or $AURA_TOKEN). Transport is TLS-only; payloads are JSON over a long-lived HTTP/2 stream. The stream reconnects automatically after network drops and resumes from the last confirmed cursor. The client will degrade gracefully to short-polling over HTTPS if HTTP/2 is blocked.