Skip to main content

​
Configuration

Learn how to configure and customize A24Z to fit your workflow and organizational needs.

​
Configuration File

A24Z stores its configuration in ~/.a24z/config.json. This file is automatically created when you run a24z login.

​
Location

~/.a24z/config.json

​
Structure

{
  "apiKey": "sk_live_abc123...",
  "organizationId": "org_xyz789",
  "organizationName": "Acme Corp",
  "apiUrl": "https://api.a24z.ai",
  "activeOrganization": {
    "id": "org_xyz789",
    "name": "Acme Corp"
  },
  "debug": false
}

​
Fields

FieldDescriptionRequired
apiKeyYour A24Z API keyYes
organizationIdActive organization IDYes
organizationNameActive organization nameYes
apiUrlA24Z API endpointYes
activeOrganizationCurrently selected organizationYes
debugEnable debug loggingNo

​
Environment Variables

You can override configuration using environment variables:

​
Available Variables

# API Configuration
export A24Z_API_KEY=sk_live_your_key_here
export A24Z_API_URL=https://api.a24z.ai
export A24Z_ORG_ID=org_abc123

# Debug Options
export A24Z_DEBUG=true
export A24Z_LOG_LEVEL=debug

​
Precedence

Environment variables take precedence over the configuration file:
  1. Environment variables (highest priority)
  2. Configuration file (~/.a24z/config.json)
  3. Default values (lowest priority)

​
Tool-Specific Configuration

​
Claude Code

A24Z integrates with Claude Code through ~/.claude/settings.json. Example configuration: 
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "a24z hook --type PreToolUse"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "a24z hook --type PostToolUse"
          }
        ]
      }
    ]
  }
}
The a24z install claude-code command automatically configures all hooks. You typically don’t need to edit this manually.

​
Gemini CLI

Configuration for Gemini CLI is stored in ~/.gemini/config.json.

​
Codex

Codex configuration is managed through ~/.codex/settings.json.

​
Organization Management

​
List Organizations

View all organizations you belong to: 
a24z org list

​
Switch Organizations

Switch to a different organization: 
a24z org switch
Or specify the organization directly: 
a24z org switch "Acme Corp"

​
View Current Organization

Check which organization is currently active: 
a24z org current

​
Debug Mode

Enable debug mode for troubleshooting:

​
Via Configuration File

Edit ~/.a24z/config.json: 
{
  "debug": true
}

​
Via Environment Variable

export A24Z_DEBUG=true
a24z status

​
Debug Output

When debug mode is enabled, you’ll see detailed logs: 
[DEBUG] Loading config from /home/user/.a24z/config.json
[DEBUG] API Key: sk_live_abc...xyz (masked)
[DEBUG] Organization: Acme Corp (org_xyz789)
[DEBUG] Sending request to https://api.a24z.ai/v1/status
[DEBUG] Response: 200 OK

​
Advanced Configuration

​
Custom API Endpoint

For self-hosted or enterprise deployments: 
export A24Z_API_URL=https://a24z.your-company.com
Or in your config file: 
{
  "apiUrl": "https://a24z.your-company.com"
}

​
Proxy Configuration

If you’re behind a corporate proxy: 
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1

​
Custom Hook Configuration

For advanced users who want to customize hook behavior: 
{
  "hooks": {
    "enabled": true,
    "async": true,
    "timeout": 5000,
    "retries": 3
  }
}

​
Security Best Practices

​
Protect Your Configuration

Your configuration file contains sensitive credentials: 
# Set appropriate permissions
chmod 600 ~/.a24z/config.json

# Never commit to version control
echo ".a24z/" >> ~/.gitignore

​
API Key Management

  • Rotate keys regularly - Generate new API keys quarterly
  • Use separate keys per environment - Different keys for dev/staging/prod
  • Revoke compromised keys immediately - Use the dashboard to revoke and regenerate

​
Environment-Specific Configuration

For different environments: 
# Development
export A24Z_API_KEY=sk_test_dev_key

# Production
export A24Z_API_KEY=sk_live_prod_key

​
Resetting Configuration

​
Reset to Defaults

To reset your configuration: 
# Backup existing config
mv ~/.a24z/config.json ~/.a24z/config.json.backup

# Re-authenticate
a24z login

​
Clear Cached Data

rm -rf ~/.a24z/cache

​
Reinstall Hooks

To reinstall tool hooks: 
a24z install claude-code --force

​
Configuration Examples

​
Minimal Configuration

{
  "apiKey": "sk_live_abc123",
  "organizationId": "org_xyz789",
  "organizationName": "Acme Corp",
  "apiUrl": "https://api.a24z.ai"
}

​
Full Configuration

{
  "apiKey": "sk_live_abc123",
  "organizationId": "org_xyz789",
  "organizationName": "Acme Corp",
  "apiUrl": "https://api.a24z.ai",
  "activeOrganization": {
    "id": "org_xyz789",
    "name": "Acme Corp"
  },
  "debug": true,
  "logLevel": "debug",
  "hooks": {
    "enabled": true,
    "async": true,
    "timeout": 5000,
    "retries": 3
  },
  "telemetry": {
    "enabled": true,
    "batchSize": 100,
    "flushInterval": 30000
  }
}

​
Troubleshooting Configuration

​
Invalid Configuration

If you see “Invalid configuration” errors:
  1. Validate JSON syntax: 
    cat ~/.a24z/config.json | jq .
  2. Check for required fields
  3. Verify API key format starts with sk_live_ or sk_test_

​
Configuration Not Loading

If your configuration isn’t being loaded:
  1. Check file permissions: 
    ls -la ~/.a24z/config.json
  2. Verify file location: 
    cat ~/.a24z/config.json
  3. Check environment variables: 
    env | grep A24Z

​
Next Steps

CLI Reference

Learn all CLI commands

Organizations

Manage multiple organizations

Troubleshooting

Fix common issues

Security

Learn about security best practices