# aura pull

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

## Synopsis

```bash
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](/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](/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:

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

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

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

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

Fetches `main` from `origin` and rebases the current branch onto it, using [aura merge](/aura-merge)'s semantic engine for any conflicts. Skips the Mothership.

### 4. Dry-run before a risky pull

```bash
aura pull --dry-run
```

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

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

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

## See Also

- [aura push](/aura-push) — the inverse
- [aura merge](/aura-merge) — handles Git-side conflicts
- [aura status](/aura-status) — shows pending Mothership deltas and active alerts
- [aura save](/aura-save) — triggers the teammate-visible push other people will pull