Skip to main content
The auth command manages API tokens for AI providers and sets default models for extraction. Tokens are stored securely in macOS Keychain (when available) or in ~/.config/struktur/tokens.json with strict file permissions.

​
Subcommands

​
auth set

Store an API token for a provider. 
struktur auth set --provider <name> --token <token>
struktur auth set --provider <name> --token-stdin
​
--provider
string
required
Provider name: openai, anthropic, google, opencode, or openrouter
​
--token
string
API token value (prefer --token-stdin for security)
​
--token-stdin
boolean
Read token from stdin to avoid shell history
​
--storage
string
default:"auto"
Storage backend: auto, keychain, or file. Auto uses macOS Keychain when available, otherwise falls back to file.
​
--default
boolean
Set the cheapest model from this provider as the default
Examples: 
# Store token from stdin (recommended)
echo "sk-..." | struktur auth set --provider openai --token-stdin
Output: 
{
  "provider": "openai",
  "stored": "keychain"
}

# Store token and set default model
echo "sk-..." | struktur auth set \
  --provider openai \
  --token-stdin \
  --default
Output: 
{
  "provider": "openai",
  "stored": "keychain",
  "defaultModel": "openai/gpt-4o-mini"
}

# Force file storage
echo "sk-..." | struktur auth set \
  --provider anthropic \
  --token-stdin \
  --storage file
Output: 
{
  "provider": "anthropic",
  "stored": "file"
}

​
auth default

Set the default model for extraction. 
struktur auth default <provider>
struktur auth default --model <provider/model>
​
provider
string
Provider name (positional). Sets the cheapest model from this provider as default.
​
--model
string
Explicit model identifier in format provider/model
Examples: 
# Set cheapest model from provider
struktur auth default openai
Output: 
{
  "defaultModel": "openai/gpt-4o-mini"
}

# Set specific model
struktur auth default --model anthropic/claude-4-sonnet
Output: 
{
  "defaultModel": "anthropic/claude-4-sonnet"
}

​
auth get

Retrieve a stored token (masked by default). 
struktur auth get --provider <name> [--raw]
​
--provider
string
required
Provider name
​
--raw
boolean
Print full token without masking
Examples: 
# Get masked token
struktur auth get --provider openai
Output: 
sk-p...x7Qz

# Get raw token
struktur auth get --provider openai --raw
Output: 
sk-proj-abc123...

​
auth delete

Remove a stored token. 
struktur auth delete --provider <name>
​
--provider
string
required
Provider name
Example: 
struktur auth delete --provider openai
Output: 
{
  "provider": "openai",
  "deleted": true
}

​
auth list

List all stored providers. 
struktur auth list
Example: 
struktur auth list
Output: 
{
  "providers": [
    {
      "provider": "openai",
      "storage": "keychain"
    },
    {
      "provider": "anthropic",
      "storage": "file"
    }
  ]
}

​
Supported providers

  • openai - OpenAI (GPT models)
  • anthropic - Anthropic (Claude models)
  • google - Google Generative AI (Gemini models)
  • opencode - OpenCode Zen (multi-provider)
  • openrouter - OpenRouter (multi-provider)

​
Storage backends

​
macOS Keychain

On macOS, tokens are stored in the system Keychain by default:
  • Service: struktur (or $STRUKTUR_KEYCHAIN_SERVICE)
  • Account: provider name
  • Requires /usr/bin/security binary

​
File storage

Tokens are stored at ~/.config/struktur/tokens.json with:
  • Directory permissions: 0700
  • File permissions: 0600

​
Environment variables

​
STRUKTUR_CONFIG_DIR
string
Override config directory (default: ~/.config/struktur)
​
STRUKTUR_DISABLE_KEYCHAIN
boolean
Force file storage even on macOS
​
STRUKTUR_KEYCHAIN_SERVICE
string
default:"struktur"
macOS Keychain service name

​
Token precedence

  1. Stored tokens (via auth set)
  2. Environment variables (OPENAI_API_KEY, etc.)
Stored tokens always take precedence over environment variables when both are present.

Build docs developers (and LLMs) love

Get started for freeTalk to us