Skip to main content

​
Installation

This guide covers everything you need to know about installing and setting up the A24Z CLI on your system.

​
System Requirements

Before installing A24Z, ensure your system meets these requirements:
  • Operating System: macOS, Linux, or Windows (WSL recommended)
  • Node.js: Version 18.0.0 or higher
  • Package Manager: npm 9+ or pnpm 8+
  • Disk Space: ~50MB for CLI and dependencies
Check your Node.js version: 
node --version
If you need to install or update Node.js, visit nodejs.org.

​
Installation Methods

Install the A24Z CLI globally: 
npm install -g a24z

​
Using pnpm

If you prefer pnpm: 
pnpm add -g a24z

​
Using yarn

For yarn users: 
yarn global add a24z

​
Verify Installation

After installation, verify that the CLI is accessible: 
a24z --version
You should see the current version number (e.g., 1.0.0). Check available commands: 
a24z --help

​
Configuration

​
Initial Setup

After installation, configure the CLI: 
a24z login
This command will:
  1. Open your default browser
  2. Navigate to the A24Z authentication page
  3. Prompt you to log in or sign up
  4. Store your authentication token locally
Your credentials are stored securely in ~/.a24z/config.json. This file is created automatically and should not be shared.

​
Configuration File

The A24Z CLI stores its configuration in ~/.a24z/config.json. Here’s what it contains: 
{
  "apiKey": "your-api-key-here",
  "organizationId": "org_abc123",
  "organizationName": "Your Organization",
  "apiUrl": "https://api.a24z.ai",
  "activeOrganization": {
    "id": "org_abc123",
    "name": "Your Organization"
  }
}
Never commit your config file to version control. It contains sensitive authentication credentials.

​
Environment Variables

You can also configure A24Z using environment variables:
  • A24Z_API_KEY - Your API key
  • A24Z_API_URL - Custom API endpoint (for enterprise deployments)
  • A24Z_ORG_ID - Default organization ID
Example: 
export A24Z_API_KEY=sk_live_your_key_here
export A24Z_API_URL=https://api.your-domain.com

​
Installing Tool Integrations

​
Claude Code

To install observability hooks for Claude Code: 
a24z install claude-code
This command:
  • Updates ~/.claude/settings.json with hook configurations
  • Configures all 9 Claude Code hook types
  • Sets up automatic telemetry collection
  • Validates the installation
Hook Types Configured:
  • PreToolUse - Before tool execution
  • PostToolUse - After tool execution
  • UserPromptSubmit - When user submits a prompt
  • SessionStart - When session begins
  • SessionEnd - When session ends
  • SubagentStop - When subagent stops
  • Notification - System notifications
  • Stop - When assistant stops
  • PreCompact - Before transcript compaction

​
Gemini CLI

For Gemini CLI integration: 
a24z install gemini

​
Codex

For Codex integration: 
a24z install codex

​
Updating the CLI

​
Check for Updates

To check if a new version is available: 
npm outdated -g a24z

​
Update to Latest Version

Update using npm: 
npm update -g a24z
Or using pnpm: 
pnpm update -g a24z

​
Update to Specific Version

To install a specific version: 
npm install -g [email protected]

​
Uninstalling

​
Remove the CLI

To uninstall the A24Z CLI: 
npm uninstall -g a24z

​
Clean Up Configuration

To remove configuration files: 
rm -rf ~/.a24z

​
Remove Tool Hooks

Before uninstalling, you may want to remove tool hooks: 
# Backup your settings
cp ~/.claude/settings.json ~/.claude/settings.json.backup

# Manual removal
# Edit ~/.claude/settings.json and remove A24Z hook configurations
We recommend keeping a backup of your tool configuration files before making changes.

​
Platform-Specific Installation

​
macOS

On macOS, you might need to use sudo for global installations: 
sudo npm install -g a24z
Or configure npm to use a user-level global directory: 
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g a24z

​
Linux

Most Linux distributions work with the standard npm installation: 
npm install -g a24z
For distributions using snap: 
# Install Node.js via snap if needed
sudo snap install node --classic

# Then install A24Z
npm install -g a24z

​
Windows (WSL)

For Windows users, we recommend using WSL (Windows Subsystem for Linux):
  1. Install WSL 2
  2. Install Node.js in your WSL environment
  3. Follow the Linux installation instructions

​
Troubleshooting Installation

​
Permission Denied Errors

If you encounter permission errors: 
# Option 1: Use sudo (macOS/Linux)
sudo npm install -g a24z

# Option 2: Configure npm to use a user directory (Recommended)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g a24z

​
Command Not Found

If a24z command is not found after installation:
  1. Check your PATH: 
    echo $PATH
  2. Find where npm installs global packages: 
    npm config get prefix
  3. Add the npm bin directory to your PATH: 
    echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

​
Network Issues

If installation fails due to network issues: 
# Use a different registry
npm install -g a24z --registry=https://registry.npmjs.org/

# Or increase timeout
npm install -g a24z --fetch-timeout=60000

​
Next Steps

After installation:
  1. Authenticate: Run a24z login to connect to your account
  2. Install Hooks: Use a24z install [tool] for your AI coding tools
  3. Verify: Run a24z status to check everything is working
  4. Start Monitoring: Use your AI tools and view metrics on your dashboard

Quick Start

Complete the quick start guide

Configuration

Learn about advanced configuration

CLI Reference

Explore all CLI commands

Troubleshooting

Get help with common issues