# Install Aura on macOS

*A single binary, two installers, and a shell that knows your functions by name.*

Aura ships as a native universal binary for macOS. It runs on Apple Silicon (M1, M2, M3, M4) and Intel without emulation, registers itself on your `PATH`, and installs pre-commit hooks into any repository you ask it to protect. This guide covers the two supported installation paths — Homebrew and the canonical curl installer — followed by verification, shell completion setup, upgrade procedure, and clean uninstall.

If you are coming from Git, you can keep Git. Aura runs *alongside* it. Nothing you install here rewrites your existing Git configuration.

## Prerequisites

- macOS 12 (Monterey) or later. Aura has been tested on macOS 14 and 15.
- A POSIX shell. The installer writes completions for both `zsh` (default on modern macOS) and `fish`.
- At least 120 MB of free disk space for the binary, sidecar grammars, and the initial `.aura/` directory in any repo you initialize.
- Network egress to `auravcs.com` and `github.com` for the installer and self-update checks.

You do **not** need Rust, Node, Python, or any other toolchain. The `aura` binary is statically linked against its tree-sitter grammars and ships with every parser it needs at build time.

If you plan to use [Mothership Mode](/mothership-overview) — the peer-to-peer team hub — you will additionally need an outbound TCP connection to your team's Mothership host. No inbound ports are required on your laptop.

## Primary: Homebrew

Homebrew is the recommended installer for most macOS users. It handles upgrades, uninstallation, and keeps the binary on a path Homebrew already manages.

```bash
brew install auravcs/tap/aura
```

The first part of the formula slug — `auravcs/tap` — is the official Aura tap maintained by Naridon Inc. Homebrew will fetch the tap if this is the first install, then pull the signed bottle for your architecture. Apple Silicon bottles install into `/opt/homebrew/bin/aura`; Intel bottles install into `/usr/local/bin/aura`.

Verify the install in a new shell:

```bash
aura --version
```

You should see output similar to:

```
aura 0.14.1
```

If the command is not found, confirm Homebrew's `bin` directory is on your `PATH`:

```bash
echo $PATH | tr ':' '\n' | grep -E '(homebrew|local)/bin'
```

On Apple Silicon the expected entry is `/opt/homebrew/bin`. Add it via `eval "$(/opt/homebrew/bin/brew shellenv)"` in your `~/.zprofile` if it is missing.

## Alternative: curl installer

If you do not use Homebrew, or you are scripting a developer machine setup, the official curl installer is the canonical path. It is the same installer used in CI pipelines and cloud VMs.

```bash
curl -fsSL https://auravcs.com/install.sh | bash
```

The script performs the following steps, in order, and prints a line for each:

1. Detects architecture (`arm64` vs `x86_64`) and operating system.
2. Downloads the signed release tarball from GitHub Releases.
3. Verifies the SHA-256 checksum against the value pinned in the installer.
4. Extracts the binary to `~/.aura/bin/aura`.
5. Appends a `PATH` line to your shell profile (`~/.zprofile` or `~/.bash_profile`).
6. Writes shell completion files for `zsh` and `fish`.

If you prefer to audit the installer before running it, download it first:

```bash
curl -fsSL https://auravcs.com/install.sh -o /tmp/aura-install.sh
less /tmp/aura-install.sh
bash /tmp/aura-install.sh
```

The installer is idempotent. Running it a second time upgrades an existing install in place. It will not duplicate `PATH` entries.

### Installing without touching the shell profile

For container images or restricted environments where you manage `PATH` yourself:

```bash
curl -fsSL https://auravcs.com/install.sh | AURA_NO_PATH=1 bash
```

You can then move the binary to any location you prefer:

```bash
install -m 0755 ~/.aura/bin/aura /usr/local/bin/aura
```

### Pinning a specific version

The installer accepts a version pin through the `AURA_VERSION` environment variable. Useful for reproducible developer machines and CI.

```bash
curl -fsSL https://auravcs.com/install.sh | AURA_VERSION=0.14.1 bash
```

Omitting the variable installs the latest stable release.

## Verification

Once `aura` is on your `PATH`, run the standard checks. These are the same commands the onboarding wizard runs on first launch.

```bash
aura --version
aura doctor
```

`aura --version` prints the semantic version and the Git-equivalent commit hash of the release. `aura doctor` performs a full health check: it verifies the binary is executable, the tree-sitter grammars loaded correctly, the local data directory (`~/.aura/`) is writable, and that hook scripts can be installed. Any failure is printed in red with a remediation hint. A healthy output ends with `All checks passed`.

For a quick functional smoke test, initialize a throwaway repo and log a dummy intent:

```bash
mkdir /tmp/aura-smoke && cd /tmp/aura-smoke
aura init
echo 'fn main() { println!("hi"); }' > main.rs
aura log-intent "Smoke test: added main"
aura status
```

`aura status` should report one tracked logic node, an active session, and no pending impacts.

## Shell completion

The Homebrew formula and the curl installer both write completion files, but they take effect only in new shell sessions. For `zsh`, ensure your completion system is initialized in `~/.zshrc`:

```bash
autoload -Uz compinit && compinit
```

For users with Homebrew on Apple Silicon, add Homebrew's completions directory to your `fpath` before `compinit` runs:

```bash
if type brew &>/dev/null; then
  FPATH="$(brew --prefix)/share/zsh/site-functions:${FPATH}"
fi
autoload -Uz compinit && compinit
```

For `fish`, completions are installed to `~/.config/fish/completions/aura.fish` and load automatically on next shell start.

To regenerate completions manually — useful after upgrading across a minor version — run:

```bash
aura completions zsh > "$(brew --prefix)/share/zsh/site-functions/_aura"
aura completions fish > ~/.config/fish/completions/aura.fish
```

Aura's completion is context-aware. Typing `aura rewind <TAB>` inside an Aura repository will list function names from the current session, not filenames. This works because completions shell out to `aura` itself for dynamic candidates.

## Upgrading

**Homebrew:**

```bash
brew update
brew upgrade aura
```

**Curl installer:**

```bash
aura self-update
```

`aura self-update` checks GitHub Releases, downloads the new binary to a temporary path, verifies its signature, and swaps it into place atomically. If a pre-commit hook is currently executing against the old binary, the swap waits until the hook finishes.

You can also re-run the installer — it upgrades in place.

```bash
curl -fsSL https://auravcs.com/install.sh | bash
```

## Uninstall

**Homebrew:**

```bash
brew uninstall aura
brew untap auravcs/tap
```

This removes the binary but leaves `~/.aura/` intact. That directory stores your local semantic cache, session history, and any handover payloads. Remove it explicitly if you want a clean slate:

```bash
rm -rf ~/.aura
```

**Curl installer:**

```bash
aura self-uninstall
```

The uninstaller removes the binary, the `PATH` line from your shell profile, and the completion files. It prompts before deleting `~/.aura/`. Answer `no` if you plan to reinstall and keep your cache.

Per-repository Aura state lives in `<repo>/.aura/`. That directory is untouched by uninstall. Remove it manually if you are decommissioning a repo.

## Next steps

With the binary installed and verified, continue to [your first repository](/first-repo) to initialize `aura init` in a project, then to [your first intent-logged commit](/first-commit-with-intent). If you plan to collaborate, skip ahead to [connecting to a team](/connecting-to-team) once you have a Mothership join token.

If you hit a snag during install, `aura doctor` is the first stop; the [troubleshooting guide](/troubleshooting-install) covers the long tail of environment-specific issues, and the [CLAUDE.md protocol](/claude-md-integration) explains how to wire Aura into Claude Code so your AI agent respects the semantic guardrails from the first commit.