axauth

Unified authentication management for AI coding agents.

Overview

axauth provides a consistent interface for managing credentials across multiple AI coding agent CLIs. It abstracts away the differences between agent-specific credential storage mechanisms (macOS Keychain, file-based storage, environment variables) and provides:

- Auth status detection - Check which agents are authenticated and via which method
- Credential extraction - Extract tokens for API calls or export/import workflows
- Portable credential export - Encrypted credential files for CI/CD and backup
- Multi-storage support - Keychain (macOS), file storage, and environment variables

Supported Agents

| Agent | CLI | Provider | Auth Methods |
| ----------- | ---------- | --------- | ------------------------------------------ |
| Claude Code | claude | Anthropic | OAuth (keychain/file), ANTHROPIC_API_KEY |
| Codex CLI | codex | OpenAI | ChatGPT OAuth, OPENAI_API_KEY |
| Gemini CLI | gemini | Google | OAuth, GEMINI_API_KEY |
| OpenCode | opencode | Sst | Multi-provider OAuth |
| Copilot CLI | copilot | GitHub | OAuth, GH_TOKEN/GITHUB_TOKEN |

Installation

``bash
npm install axauth


or


pnpm add axauth
`

CLI Usage

`bash


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
axauth token --agent opencode --provider anthropic # OpenCode requires --provider

Export credentials to encrypted file

axauth export --agent claude --output creds.json
axauth export --agent claude --output creds.json --no-password

Install credentials from exported file

axauth install-credentials --agent claude --input creds.json
axauth install-credentials --agent claude --input creds.json --config-dir /tmp/config

Remove credentials (agent will prompt for login on next use)

axauth remove-credentials --agent claude
axauth remove-credentials --agent claude --config-dir /tmp/config
`

$3

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

`bash


List all agents and their auth status

axauth list

AGENT STATUS METHOD

claude 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

Check if a specific agent is authenticated

axauth list --json | jq -e '.[] | select(.agentId == "claude") | .authenticated'

Use token with curl

curl -s -H "Authorization: Bearer $(axauth token --agent claude)" \
-H "anthropic-beta: oauth-2025-04-20" \
https://api.anthropic.com/api/oauth/usage | jq .
`

Library API

`typescript
import {
// Core operations
checkAuth, // Check single agent auth status
checkAllAuth, // Check all agents' auth status
getAgentAccessToken, // Get access token for an agent
findCredentials, // Find credentials from storage or environment
installCredentials, // Install credentials to storage
removeCredentials, // Remove credentials from storage

// Credential utilities
getAccessToken, // Extract token from credential object
credentialsToEnvironment, // Convert credentials to env vars
getCredentialsEnvironmentVariableName, // Get AX_*_CREDENTIALS var name
installCredentialsFromEnvironmentVariable, // Install from env var (CI/CD)

// Adapter access
getAdapter, // Get adapter for an agent
getAllAdapters, // Get all adapters
getCapabilities, // Check adapter capabilities
} from "axauth";

// Types
import type {
AgentCli, // "claude" | "codex" | "gemini" | "opencode" | "copilot"
AuthStatus, // { agentId, authenticated, method?, details? }
Credentials, // { agent, type, data }
AuthAdapter, // Adapter interface
AdapterCapabilities, // { keychain, file, environment, installApiKey }
} from "axauth";
`

$3

`typescript
import { checkAuth, getAgentAccessToken, getCapabilities } from "axauth";

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

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

// OpenCode requires explicit provider (multi-provider agent)
const openCodeToken = await getAgentAccessToken("opencode", {
provider: "anthropic",
});

// Check adapter capabilities
const caps = getCapabilities("gemini");
if (!caps.keychain) {
console.log("Gemini requires file storage on this platform");
}
`

$3

Each agent implements the AuthAdapter interface, hiding storage complexity:

`typescript
import { getAdapter } from "axauth";

const adapter = getAdapter("claude");

// All adapters have the same interface (OpenCode requires { provider } option)
const status = adapter.checkAuth();
const creds = adapter.findStoredCredentials(); // OpenCode: findStoredCredentials({ provider: "anthropic" })
const token = adapter.getAccessToken(creds);
const envVars = adapter.credentialsToEnvironment(creds);

// Check what the adapter supports
console.log(adapter.capabilities);
// { keychain: true, file: true, environment: true, installApiKey: false }
`

Adapter Capabilities

Each agent adapter declares its storage capabilities:

| Agent | Keychain | File | Environment | Install API Key |
| -------- | :------: | :--: | :---------: | :-------------: |
| claude | macOS | Yes | Yes | No (env-only) |
| codex | macOS | Yes | Yes | No (env-only) |
| gemini | macOS | Yes | Yes | No (env-only) |
| opencode | No | Yes | Yes | No |
| copilot | macOS | Yes | Yes | No (env-only) |

Notes:

- Keychain: macOS Keychain support (not available on Linux/Windows)
- File: File-based credential storage
- Environment: Can read credentials from environment variables
- Install API Key: Whether API keys can be installed (vs. read from env only)

Credential Export Format

Exported credentials are encrypted with AES-256-GCM:

`json
{
"version": 1,
"agent": "claude",
"ciphertext": "",
"salt": "",
"iv": "",
"tag": ""
}
`

- Key derivation: PBKDF2 with SHA-256, 100,000 iterations
- Use --no-password for CI/CD (uses a default password)
- Files are written with 0o600 permissions

Environment Variables

For CI/CD workflows, credentials can be passed via environment variables:

| Agent | Credential Env Var |
| -------- | ------------------------- |
| claude | AX_CLAUDE_CREDENTIALS |
| codex | AX_CODEX_CREDENTIALS |
| gemini | AX_GEMINI_CREDENTIALS |
| copilot | AX_COPILOT_CREDENTIALS |
| opencode | AX_OPENCODE_CREDENTIALS |

Use installCredentialsFromEnvironmentVariable() to install credentials from these variables programmatically.

Config Directory Requirements

Some agents require specific directory name suffixes:

| Agent | Directory Requirement | Example |
| -------- | ------------------------ | -------------------- |
| claude | Any name | /tmp/my-config |
| codex | Any name | /tmp/my-config |
| gemini | Must end with .gemini | /tmp/home/.gemini |
| copilot | Must end with .copilot | /tmp/home/.copilot |
| opencode | Must end with opencode | /tmp/data/opencode |

Architecture

axauth follows the adapter pattern with a functional core:

`
src/
├── index.ts # Public API exports
├── cli.ts # CLI entry point
├── crypto.ts # AES-256-GCM encryption
├── commands/
│ └── auth.ts # CLI command handlers
└── auth/
├── adapter.ts # AuthAdapter interface
├── types.ts # AuthStatus, Credentials types
├── registry.ts # Adapter registry and unified operations
└── agents/ # Agent-specific adapters
├── claude-code.ts
├── claude-code-storage.ts
├── codex.ts
├── codex-storage.ts
├── codex-config.ts
├── gemini.ts
├── gemini-storage.ts
├── gemini-auth-check.ts
├── copilot.ts
├── copilot-storage.ts
├── copilot-auth-check.ts
└── opencode.ts
``

Related Packages

axauth is part of the a╳kit ecosystem:

- axshared - Shared types and agent metadata
- axconfig - Permission and configuration management
- axrun - Agent execution and output normalization

License

MIT