Skip to content

Getting started

Install aru, initialize a project, and replay its locked state.

Install

Aru requires a system git executable.

Install the PyPI distribution named arust:

uv tool install arust

The distribution name differs because aru was already taken on PyPI, but the installed command remains aru. Prebuilt wheels support x86-64 glibc Linux and Apple Silicon macOS.

The standalone installer downloads a prebuilt, checksum-verified binary and does not require Rust.

curl -LsSf https://raw.githubusercontent.com/narumiruna/aru/main/scripts/install.sh | sh

You can use wget instead:

wget -qO- https://raw.githubusercontent.com/narumiruna/aru/main/scripts/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/narumiruna/aru/main/scripts/install.ps1 | iex"

cargo install aru

Verify the installation:

aru --version
aru --help

Standalone installations can update themselves:

aru self update

Package-manager installations should be updated through the same package manager instead:

uv tool upgrade arust

cargo install aru --locked

Initialize a project

Run init from an existing project directory and name every coding agent the project should support:

aru init --target codex --target claude --target copilot

Or initialize another directory:

aru init ../my-project --target codex

The instruction-capable targets are agents, codex, claude, copilot, pi, and opencode. Additional canonical targets provide project-scoped Agent Skills only. Run aru target list --available for the complete registry and aliases such as claude-code, gemini-cli, and kiro-cli. Initialization creates:

  • aru.toml for human-maintained intent;
  • aru.lock for exact, reproducible resolution and projection data;
  • .aru/ for ignored local cache, ownership, and transaction state.

Adopt existing instructions

Specify each existing AGENTS.md file explicitly and preview without writing:

aru instruction add AGENTS.md src/api/AGENTS.md --dry-run

Apply the result:

aru instruction add AGENTS.md src/api/AGENTS.md

If an unmanaged destination such as CLAUDE.md already exists, aru reports a collision. Choose an explicit policy only after reviewing the file:

aru instruction add AGENTS.md src/api/AGENTS.md --merge  # preserve Markdown around owned blocks
aru instruction add AGENTS.md src/api/AGENTS.md --force  # destructively take over the destination

Warning

--force is destructive takeover. A later removal will not restore the old unmanaged content.

Add a skill

Choose exports explicitly for reproducible scripts and CI:

aru skill add narumiruna/skills --skill writing-plans

In an interactive terminal, omit selectors to open the searchable multi-select interface:

aru skill add narumiruna/skills

Verify replay

Require the committed lock, then check local synchronization without writing:

aru sync --locked
aru sync --check

Next, learn how to lock and synchronize project state or configure a specific resource: