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 — 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.

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:

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:

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.

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:

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:

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

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

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.

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.

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:

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:

autoload -Uz compinit && compinit

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

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:

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:

brew update
brew upgrade aura

Curl installer:

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.

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

Uninstall

Homebrew:

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:

rm -rf ~/.aura

Curl installer:

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 to initialize aura init in a project, then to your first intent-logged commit. If you plan to collaborate, skip ahead to connecting to a team once you have a Mothership join token.

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

Up next

Install on Linux

Debian, Ubuntu, Arch, Fedora, and manual binary installation on Linux.