Authentication

How to authenticate Arial with Anthropic's Claude API.

Overview

Arial supports two authentication methods:

If both are available, API key takes precedence.

Local Credentials (Recommended for Development)

Use Claude's built-in authentication for the simplest setup.

Setup

# Authenticate with your Anthropic account
claude login

This opens a browser for OAuth authentication and stores credentials locally.

Usage

No additional configuration needed. Arial automatically uses local credentials:

arial init
arial plan --specs ./specs
arial run

Verify

# Check if logged in
claude whoami

API Key

Use an API key for automated environments or when local credentials aren't available.

Get an API Key

1. Go to console.anthropic.com
2. Navigate to API Keys
3. Create a new key (starts with sk-ant-)

Setup

Temporary (current session):

export ANTHROPIC_API_KEY=sk-ant-your-key-here

Persistent (add to shell config):

# For bash
echo 'export ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.bashrc
source ~/.bashrc

# For zsh
echo 'export ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.zshrc
source ~/.zshrc

Verify

echo $ANTHROPIC_API_KEY
# Should output: sk-ant-...

Authentication Precedence

When both methods are available:

1. API key (if ANTHROPIC_API_KEY is set)
2. Local credentials (fallback)

This allows you to:

• Use local credentials for development
• Override with API key in CI/CD via environment variable

CI/CD Setup

For GitHub Actions, add your API key as a secret:

# .github/workflows/arial.yml
jobs:
  run-arial:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Arial
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npx arial init
          npx arial plan --specs ./specs -y
          npx arial run --no-tui

For other CI systems, set ANTHROPIC_API_KEY as an environment variable or secret.

Troubleshooting

"Missing ANTHROPIC_API_KEY environment variable"

This error appears when:

• No API key is set, AND
• No local credentials exist

Fix: Either run claude login or set ANTHROPIC_API_KEY.

"Invalid API key"

Fix: Verify your key at console.anthropic.com. Keys start with sk-ant-.

Local credentials not working

# Re-authenticate
claude logout
claude login

Check which auth method is active

# If this shows your key, API key auth is active
echo $ANTHROPIC_API_KEY

# If empty, local credentials will be used (if available)
claude whoami

Security Best Practices

• Never commit API keys to version control
• Use secrets in CI/CD systems
• Rotate keys periodically via the Anthropic console
• Use local credentials for development to avoid key exposure