# Your First `aura save`

*One command for snapshot, intent, commit, and push. When to reach for it, and when to keep using raw Git.*

`aura save` is the unified Aura workflow command. It bundles the four discrete steps that ought to happen on every commit — pre-edit snapshot, intent log, Git commit, and (optionally) Mothership push — into a single invocation. It is the command most developers end up running by reflex once they have worked with Aura for a few days. This page covers what it actually does under the hood, when it is the right tool, and the handful of situations where plain `git commit` is still the better choice.

## The short version

Inside an Aura-initialized repository, with changes staged:

```bash
git add src/auth.rs src/config.rs
aura save "Switched password hashing from bcrypt to argon2id"
```

That single command:

1. Snapshots every modified file to `.aura/snapshots/` (so `aura rewind` can recover any of them).
2. Logs the supplied string as your intent in `.aura/intent_log.jsonl`.
3. Validates the intent against the AST-level diff. Aborts if they disagree.
4. Runs `git commit` with the same message.
5. If a Mothership is connected, pushes the changed functions via Live Sync so teammates see them immediately.

If any step fails — intent mismatch, hook rejection, Git error — the whole save is aborted and the repository is left in the state it was in before you invoked the command. No half-committed states.

## What each step does, in detail

### 1. Snapshot

The first thing `aura save` does is take a snapshot of every file that is currently modified (staged or unstaged) in the working tree. The snapshot is content-addressed and written to `.aura/snapshots/objects/`. It is durable: even if the subsequent commit fails, the snapshot remains, and you can recover the file or any function inside it with `aura rewind`.

This is the "safety net" step. It exists because the single most valuable recovery operation in day-to-day work is "undo that one function I just ruined." The snapshot makes that operation semantic — `aura rewind auth::hash_password` — rather than a full-file revert.

### 2. Log intent

The intent string you pass to `aura save` is recorded in `.aura/intent_log.jsonl` with the same fields `aura log-intent` would write. The log entry is timestamped, branch-tagged, and cryptographically tied to the staged diff's hash.

If you pass no string, `aura save` opens `$EDITOR` with a templated message. The template includes the staged diff's semantic summary at the top, so you can write an intent that actually describes the change.

### 3. Validate

Aura parses the staged diff into its AST-level representation, compares it against the stated intent, and decides whether they describe the same change. Agreement is a judgment, not a hash match: the comparison is done by a rule-based engine plus, optionally, an LLM-backed review step for cases that are harder to judge mechanically.

If agreement holds, validation passes silently. If it does not, `aura save` prints the semantic diff with the mismatched nodes highlighted and exits non-zero without committing. You can then either amend the intent or unstage files and re-run.

### 4. Commit

If validation passes, `aura save` shells out to `git commit` with:

```
git commit -m "<your intent string>"
```

It runs through the normal pre-commit hook, which re-validates (this is a cheap idempotent check) and records the commit SHA back into the intent log entry.

If you want a different commit message from your intent string — for example, a Conventional Commits-formatted message that differs from the longer intent — use:

```bash
aura save --intent "Switched password hashing from bcrypt to argon2id; added ConfigError" \
          --message "feat(auth): migrate to argon2id"
```

### 5. Push to Mothership

If this repository is connected to a [Mothership](/mothership-overview), the final step is a push of the changed *function bodies* (not full files, not full commits) to the Mothership. This is the Live Sync path. It happens automatically after a successful local commit.

Teammates running the same repo receive the function-level change within seconds. If someone else is editing the same function, Aura's live-sync layer surfaces a collision notification on their side; see [connecting to a team](/connecting-to-team).

If no Mothership is connected, this step is a no-op.

## Flags worth knowing

- `--no-push` — skip the Mothership push step. Useful if you are committing partially-working code you do not want teammates to pick up yet.
- `--no-snapshot` — skip the snapshot step. Rarely what you want; saves a few milliseconds at the cost of rewind safety.
- `--amend` — amend the last commit. Works like `git commit --amend` but correctly updates the intent log so the hook does not complain on the next commit.
- `--wip` — marks this save as work-in-progress. The hook relaxes its intent/diff agreement rules, and the Mothership push is suppressed by default. Use when you are stubbing something out.
- `--force` — bypass hook rejection. Recorded in the intent log as a forced save so the audit trail is intact. Blocked in strict mode.

## When to use `aura save` vs. raw Git

`aura save` is the right command for **almost every commit** in an Aura-tracked repository. Reach for raw Git when:

- **You are committing to a repo that has not been `aura init`-ed.** `aura save` requires `.aura/` to exist.
- **You are performing a rebase, cherry-pick, or other history-rewriting operation.** Use the native Git commands. Aura tracks semantic identity across rebases correctly; no special wrapper needed.
- **You are resolving a merge conflict interactively.** Resolve with `git`, then `aura save --message "merge: ..." "Merged branch foo, resolving conflict in parser::tokenize by keeping the new behavior."` for the final commit.
- **You are operating on the repo from a script that does not have an intent context.** A script committing generated files (say, a regenerated lockfile) has no meaningful intent to log. Use raw `git commit` with `--no-verify` and document the script's role in `.aura/config.toml` under `[policy.allow_unverified]`.

For everything else, `aura save` is shorter, safer, and produces a better audit trail.

## From the agent's side

Claude Code and other MCP-aware agents do not call `aura save`. They call the individual MCP tools — `aura_snapshot`, `aura_log_intent` — and then issue the commit themselves. This is deliberate: at the tool-call granularity, the agent has richer context about *why* it is snapshotting or logging, and Aura's MCP server can give more targeted warnings (team zones, sync conflicts) at each step.

`aura save` is the shape humans reach for; the equivalent agent-side flow is the MCP tool chain. Both produce the same audit record. See the [CLAUDE.md protocol](/claude-md-integration) for the full agent workflow.

## Interaction with strict mode

In [strict mode](/first-commit-with-intent), `aura save` is effectively *required* — raw `git commit` without a prior `aura log-intent` is blocked by the hook. Teams that enable strict mode typically also alias `git commit` to a warning-emitting wrapper that points developers at `aura save`.

A minimal shell alias:

```bash
alias commit='aura save'
```

That covers the common case. When you do need raw Git behavior, type `git commit` with no alias.

## Recovering from a bad save

Because `aura save` snapshots before it commits, *everything* is recoverable. The most common recovery scenarios:

**"I committed, but realized I included the wrong file."**

```bash
git reset HEAD~1
# files are back in the working tree, unstaged
aura rewind <file-or-function>  # if you need to discard a change
```

**"I committed and now a function behaves worse than before."**

```bash
aura rewind auth::hash_password
```

Aura restores just that function from its last-known-good snapshot and leaves the rest of the commit intact. You then `aura save` the rewind as a new commit.

**"My intent was wrong; the diff was right."**

```bash
git commit --amend --no-edit
aura log-intent --amend "Correct intent goes here."
```

The amended intent supersedes the bad one in the log.

**"The whole commit was a mistake."**

```bash
git reset --hard HEAD~1
```

The snapshots remain in `.aura/snapshots/`. Nothing is lost from Aura's perspective; Git has lost the commit as normal, and you can re-try.

## What `aura save` is not

A few common misunderstandings worth flattening:

- **It is not a replacement for Git.** It is a wrapper that calls `git commit` after doing the Aura-specific preamble. If Git breaks, so will `aura save`.
- **It does not push to your Git remote.** The "push" step is a Mothership function-level push, not `git push`. If you want both, run `git push` after.
- **It is not required.** You can use `aura log-intent` + `git commit` forever if you prefer separate steps. `aura save` is convenience, not policy. (Unless you enable strict mode, in which case the policy is enforced by the hook, not by the command name.)
- **It is not available in `--no-git` repositories.** Standalone Aura repositories use `aura commit` instead, which is the same workflow minus the Git step.

## Typical session

A realistic five-minute slice of using `aura save`:

```bash
# Morning — pull teammate changes first
aura live-sync-pull

# Work...
vim src/parse.rs
vim tests/parse.rs

# Check what you're about to commit
git status
git diff --cached

# Commit
git add src/parse.rs tests/parse.rs
aura save "Taught parse_expr to handle trailing commas in tuples; added regression test"

# Push Git branch to remote
git push
```

That is the whole loop. Once `aura save` is muscle memory, the friction of the intent discipline drops to zero — you write the message as you would have written a commit message anyway, and the hook validation happens in the background.

## Next steps

- [Connect to a Mothership](/connecting-to-team) so the push step actually pushes somewhere.
- [CLAUDE.md integration](/claude-md-integration) for the agent-side flow.
- [Troubleshooting](/troubleshooting-install) if `aura save` fails in a way you cannot diagnose.