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 (Gemini, Claude, Codex, VS Code, Antigravity)

Agent Layer does not install client CLIs 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
  • docs/agent-layer/ for project memory
  • a managed .gitignore block

By default, al init prompts to run the setup wizard. 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:

  • Homebrew: brew upgrade conn-castle/tap/agent-layer
  • macOS/Linux script: re-run the install script above

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 complete upgrade contract (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.