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

Installation

# CLI (global)
npm install -g axauth
# or
pnpm add -g axauth

# Library usage (non-global)
npm install axauth

Prerequisites

• Node.js 22.19+
• pnpm or npm
• jq for JSON examples
• Agent CLIs installed (as needed): claude, codex, gemini, opencode, copilot
• POSIX shell assumed in examples (bash/zsh); PowerShell needs syntax adjustments

CLI Usage

Examples use long-form flags; short flags exist but prefer long for clarity.

# 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

Output Formats

• axauth list outputs TSV by default; --json returns a JSON array
• axauth vault fetch outputs JSON by default; --json pretty-prints JSON
• axauth token outputs the raw token for piping

Pipeline Examples

The axauth list command outputs TSV with a header row:

• Columns: AGENT, STATUS, METHOD
• STATUS values: authenticated | not_configured

# List all agents and their auth status
axauth list

Output (TSV):

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 .

Security Note: --no-password

--no-password uses a deterministic “default password” derived from the source code. This is intended for CI/CD convenience (e.g., storing the exported file as a secret), not for protecting credentials at rest.

Library API

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";

Examples

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");
}

Adapter Pattern

Each agent implements the AuthAdapter interface, hiding storage complexity:

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:

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:

{
  "version": 1,
  "agent": "claude",
  "ciphertext": "<base64>",
  "salt": "<base64>",
  "iv": "<base64>",
  "tag": "<base64>"
}

• 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:

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

Custom Directory Behavior

Directory handling depends on whether the agent separates config and data:

• Shared config/data agents (claude, codex, gemini, copilot): --config-dir and --data-dir are interchangeable and point to the same location.
• Separate config/data agent (opencode): --config-dir and --data-dir are independent. If only one is provided, the other uses the default location and axauth emits a warning.

Architecture

axauth follows an adapter architecture with a functional core:

• src/auth/ — core auth domain logic, adapter interfaces, registry, shared utilities
• src/auth/agents/ — agent-specific adapter implementations and storage/install/remove flows
• src/commands/ — CLI command handlers (list, token, export, install-credentials, vault, etc.)
• src/vault/ — axvault client/config integration for fetch/push workflows
• src/crypto.ts — credential encryption/decryption primitives (AES-256-GCM + PBKDF2)
• src/index.ts / src/cli.ts — library exports and CLI entrypoint

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