Skip to main content
The auth command manages authentication credentials for AI providers that support OAuth flows or require secure token storage.

​
Usage

weaver auth <subcommand> [options]

​
Subcommands

​
login

Authenticate with a provider using OAuth or token paste. 
weaver auth login --provider <name> [--device-code]
​
--provider, -p
string
required
Provider to authenticate withSupported providers:
  • openai - OpenAI OAuth or token
  • anthropic - Token paste only
​
--device-code
flag
Use device code flow instead of browser (for headless environments)Only applies to OpenAI OAuth.

​
logout

Remove stored credentials for one or all providers. 
weaver auth logout [--provider <name>]
​
--provider, -p
string
Specific provider to logout fromIf omitted, logs out from all providers.

​
status

Show current authentication status for all providers. 
weaver auth status

​
Authentication Methods

​
OpenAI OAuth (Browser Flow)

Best for local development with browser access: 
$ weaver auth login --provider openai

Opening browser for authentication...
[Browser opens to OpenAI consent page]
Login successful!
Account: [email protected]
Flow:
  1. Opens browser to OpenAI OAuth page
  2. User grants permissions
  3. Weaver receives OAuth token
  4. Token stored securely with refresh capability

​
OpenAI OAuth (Device Code Flow)

For headless servers or environments without browser: 
$ weaver auth login --provider openai --device-code

Please visit: https://auth.openai.com/activate
Enter code: ABCD-EFGH

Waiting for authorization...
Login successful!
Account: [email protected]
Flow:
  1. Displays activation URL and code
  2. User visits URL on any device
  3. User enters code and grants permissions
  4. Weaver polls for completion

​
Token Paste (Anthropic, OpenAI)

For providers without OAuth or manual token entry: 
$ weaver auth login --provider anthropic

Paste your API token (input hidden):
[User pastes token]
Token saved for anthropic!

​
Credential Storage

Credentials are stored at:
  • Location: ~/.weaver/auth.json
  • Format: Encrypted JSON
  • Permissions: 0600 (owner read/write only)
Structure: 
{
  "credentials": {
    "openai": {
      "auth_method": "oauth",
      "access_token": "...",
      "refresh_token": "...",
      "expires_at": "2026-03-15T10:30:00Z",
      "account_id": "[email protected]"
    },
    "anthropic": {
      "auth_method": "token",
      "access_token": "sk-ant-..."
    }
  }
}

​
Token Refresh

Weaver automatically refreshes OAuth tokens:
  • Trigger: When token expires or needs refresh
  • Mechanism: Uses stored refresh token
  • Fallback: Prompts for re-authentication if refresh fails

​
Examples

$ weaver auth login --provider openai

Opening browser for authentication...
Login successful!
Account: [email protected]

​
Status Values

StatusDescription
activeToken is valid and not expiring soon
needs refreshOAuth token approaching expiry
expiredOAuth token expired (will auto-refresh)

​
Integration with Config

When you authenticate via auth login, Weaver updates config.json: 
"providers": {
  "openai": {
    "auth_method": "oauth",  // Set automatically
    "api_key": ""           // Not used when auth_method is oauth
  },
  "anthropic": {
    "auth_method": "token", // Set automatically
    "api_key": ""           // Not used when auth_method is token
  }
}

​
Exit Codes

CodeReason
0Success
1Invalid provider
1Authentication failed
1Failed to save credentials
1Failed to load auth store

​
Error Handling

​
Missing Provider

Error: --provider is required
Supported providers: openai, anthropic

​
Unsupported Provider

Unsupported provider: gemini
Supported providers: openai, anthropic

​
OAuth Failure

Login failed: user denied consent

​
Token Paste Error

Login failed: invalid token format

​
Credential Save Error

Failed to save credentials: permission denied
Ensure ~/.weaver/ directory has correct permissions.

​
Security Best Practices

Never share ~/.weaver/auth.json or commit it to version control.
1

Use OAuth when available

OAuth tokens can be revoked and have automatic refresh.
2

Rotate tokens regularly

Logout and re-login periodically for manual tokens.
3

Protect auth.json

Ensure file has 0600 permissions:
chmod 600 ~/.weaver/auth.json

Build docs developers (and LLMs) love

Get started for freeTalk to us