Skip to main content

Install Agent Layer once per machine, then initialize each repo you want to use. The CLI is named al.

Requirements​

  • A supported client installed separately (Antigravity agy, Claude, Codex, Copilot CLI, Grok, or VS Code with the code command on PATH)

Agent Layer does not install clients for you.

note

If you manage multiple repos, you still install al only once. Each repo gets its own .agent-layer/ config.

Homebrew (macOS/Linux)​

brew install conn-castle/tap/agent-layer

Script (macOS/Linux)​

curl -fsSL https://github.com/conn-castle/agent-layer/releases/latest/download/al-install.sh | bash

The script installs to ~/.local/bin by default and verifies checksums. If ~/.local/bin is not on your PATH, it prints an exact line to add.

If you prefer not to pipe a script into your shell, download it first and inspect it:

curl -fsSL -o al-install.sh https://github.com/conn-castle/agent-layer/releases/latest/download/al-install.sh
less al-install.sh
bash al-install.sh

By default, the script also installs shell completions for your current interactive shell. You can manage completions manually with al completion <bash|zsh|fish> --install.

Verify​

al --version

First run​

cd /path/to/repo
al init
al <client> # e.g., al claude

al init seeds:

  • .agent-layer/ for configuration
  • a managed .gitignore block

By default, al init prompts to run the setup wizard. The wizard can seed instruction files and docs/agent-layer/ project memory, and can install catalog skills. Skip it with --no-wizard if you prefer to configure manually.

You can also run al wizard later to revisit approvals, enabled clients, MCP servers, and warnings.

tip

For a safe evaluation, run al init in a disposable repository first.

  • Read the docs: /docs/getting-started
  • Run al doctor to validate config and MCP connectivity
  • Edit .agent-layer/instructions/ to set team rules
  • Review .agent-layer/commands.allow to keep approvals tight
  • Enable only MCP servers you trust (see /docs/concepts#mcp-servers)
  • Skim /security for network behavior and secret handling

Update​

Update the global CLI:

al update

al update detects whether the running release binary is owned by Homebrew. It upgrades the formula when it is, and otherwise downloads and reruns the official installer while preserving the current install prefix.

If the installed CLI predates the al update command, update it once with brew upgrade conn-castle/tap/agent-layer for Homebrew or by rerunning the original script install command (including the same --prefix, if any).

Run al upgrade plan and then al upgrade inside the repo. This updates the repo pin (.agent-layer/al.version) and refreshes template-managed files. For a concise runbook (interactive + CI), use /docs/upgrade-checklist.

For the full upgrade policy (event model, compatibility guarantees, migration rules, and platform matrix), see /docs/upgrades.

caution

To upgrade a repo safely, use al upgrade plan (dry-run) and then al upgrade (apply). For CI-safe non-interactive apply, use al upgrade --yes --apply-managed-updates. Include --apply-memory-updates and/or --apply-deletions only when explicitly intended.