axauth

Authentication management library and CLI for AI coding agents.

Overview

axauth manages credentials for AI coding agents. It can be used:

1. As a library - imported to check auth status, extract tokens, and manage credentials programmatically
2. As a CLI - standalone tool for managing agent credentials

Supported Agents

• claude-code - Claude Code (Anthropic)
• codex - Codex CLI (OpenAI)
• gemini - Gemini CLI (Google)
• opencode - OpenCode

Library API

import { checkAuth, getAgentAccessToken, extractCredentials } from "axauth";

// Check auth status for an agent
const status = checkAuth("claude-code");
if (status.authenticated) {
  console.log(`Authenticated via ${status.method}`);
}

// Get access token for API calls
const token = getAgentAccessToken("claude-code");
if (token) {
  // Use token for API calls
}

// Extract full credentials for export
const creds = extractCredentials("claude-code");
if (creds) {
  // creds.accessToken, creds.refreshToken, etc.
}

CLI Commands

# List agents and their auth status
axauth list
axauth list --json

# Get access token for an agent (outputs raw token for piping)
axauth token --agent claude-code

# Export credentials to encrypted file
axauth export --agent claude-code --output creds.json
axauth export --agent claude-code --output creds.json --no-password

# Remove credentials (agent will prompt for login)
axauth remove-credentials --agent claude-code

# Install credentials from exported file
axauth install-credentials --agent claude-code --input creds.json

Pipeline Examples

The CLI outputs TSV format for easy processing with standard Unix tools:

# List all agents and their auth status
axauth list
# AGENT         STATUS          METHOD
# claude-code   authenticated   OAuth (max)
# codex         authenticated   ChatGPT OAuth
# ...

# Filter to show only authenticated agents
axauth list | tail -n +2 | awk -F'\t' '$2 == "authenticated"'

# Count agents by status
axauth list | tail -n +2 | cut -f2 | sort | uniq -c

# Extract agent names as a list
axauth list | tail -n +2 | cut -f1

# Check if a specific agent is authenticated
axauth list --json | jq -e '.[] | select(.agentId == "claude-code") | .authenticated'

# Check Claude Code usage via OAuth endpoint
curl -s -H "Authorization: Bearer $(axauth token --agent claude-code)" \
  -H "anthropic-beta: oauth-2025-04-20" \
  https://api.anthropic.com/api/oauth/usage | jq .

Module Structure

src/
├── types.ts                # AgentId type definition
├── crypto.ts               # AES-256-GCM encryption for credentials
├── cli.ts                  # CLI entry point
├── commands/
│   └── auth.ts             # CLI command handlers
└── auth/
    ├── check-auth.ts       # Auth status detection
    ├── extract-credentials.ts  # Credential extraction
    ├── get-access-token.ts     # Token retrieval
    ├── install-credentials.ts  # Credential installation
    ├── remove-credentials.ts   # Credential removal
    ├── keychain.ts         # macOS Keychain utilities
    ├── file-storage.ts     # File I/O utilities
    ├── types.ts            # Auth types
    └── agents/             # Agent-specific implementations
        ├── claude-code.ts
        ├── codex.ts
        ├── gemini.ts
        └── opencode.ts

Authentication Methods

Agent Rule

Add to your CLAUDE.md or AGENTS.md:

# Rule: `axauth` Usage

Run `npx -y axauth --help` to learn available options.

Use `axauth` to manage AI agent credentials. Check auth status with `axauth list`,
get tokens with `axauth token`, and export/import credentials for CI/CD workflows.

Development Status

🚧 Work in Progress

License

MIT