picoclaw auth - PicoClaw

Overview

The auth command manages authentication with AI providers, supporting both OAuth flows and direct token authentication. It handles login, logout, status checking, and model listing for OAuth providers.

Usage

picoclaw auth [subcommand] [flags]

Subcommands

Authenticate with a provider using OAuth or token.

picoclaw auth login [flags]

Flags

-p, --provider

string

required

Provider to authenticate with.Supported providers:

openai - OpenAI (OAuth or token)
anthropic - Anthropic (token only)
google-antigravity (or antigravity) - Google Cloud Code Assist (OAuth)

picoclaw auth login --provider openai

--device-code

boolean

default:"false"

Use device code flow for OAuth (for headless/SSH environments).Only applicable for OAuth providers (OpenAI, Google Antigravity).

picoclaw auth login --provider openai --device-code

logout

Remove stored credentials for one or all providers.

picoclaw auth logout [flags]

Flags

-p, --provider

string

Provider to logout from. If omitted, logs out from all providers.

# Logout from specific provider
picoclaw auth logout --provider openai

# Logout from all providers
picoclaw auth logout

status

Show authentication status for all providers.

picoclaw auth status

Displays:

Authenticated providers
Authentication method (oauth/token)
Status (active/expired/needs refresh)
Account details (email, account ID, project)
Expiration times

models

Show available models for Google Antigravity.

picoclaw auth models

Lists all models available in your Cloud Code Assist project, including:

Model ID
Display name
Quota status

Note: Currently only supported for Google Antigravity provider.

Provider-Specific Flows

OpenAI (OAuth)

picoclaw auth login --provider openai

Flow:

Opens browser for OAuth authentication
Log in with OpenAI account
Grant permissions
Credentials stored automatically
Config updated to use OAuth
Default model set to gpt-5.2

Output:

Opening browser for authentication...
✓ Login successful!
Account: [email protected]
Default model set to: gpt-5.2

Headless/SSH Environments:

picoclaw auth login --provider openai --device-code

Output:

To authenticate, visit: https://auth.openai.com/activate
Enter code: ABCD-EFGH
Waiting for authentication...
✓ Login successful!

Anthropic (Token)

picoclaw auth login --provider anthropic

Flow:

Prompts for API key
You paste your Anthropic API key
Credentials stored securely
Config updated
Default model set to claude-sonnet-4.6

Output:

Enter your Anthropic API key: sk-ant-...
✓ Token saved for anthropic!
Default model set to: claude-sonnet-4.6

Get API Key: https://console.anthropic.com/settings/keys

Google Antigravity (OAuth)

picoclaw auth login --provider google-antigravity

Flow:

Opens browser for Google OAuth
Select Google account
Grant Cloud Code Assist permissions
Fetches project ID automatically
Stores credentials
Config updated
Default model set to gemini-flash

Output:

Opening browser for authentication...
Email: [email protected]
Project: my-project-123456

✓ Google Antigravity login successful!
Default model set to: gemini-flash
Try it: picoclaw agent -m "Hello world"

Requirements:

Google Cloud project with Code Assist enabled
Billing enabled (free tier available)

Examples

picoclaw auth login --provider openai

Browser opens, authenticate, then:

picoclaw agent -m "Hello!"

picoclaw auth login --provider anthropic
# Paste API key when prompted

picoclaw auth login --provider google-antigravity

For SSH sessions without browser access:

picoclaw auth login --provider openai --device-code

Output:

To authenticate, visit: https://auth.openai.com/activate
Enter code: WXYZ-1234

(On your local machine, open the URL and enter the code)

Check Authentication Status

picoclaw auth status

Output:

Authenticated Providers:
------------------------
  openai:
    Method: oauth
    Status: active
    Account: [email protected]
    Expires: 2026-04-03 12:00
  
  anthropic:
    Method: token
    Status: active
  
  google-antigravity:
    Method: oauth
    Status: active
    Email: [email protected]
    Project: my-project-123
    Expires: 2026-03-03 18:00

List Available Models (Antigravity)

picoclaw auth login --provider google-antigravity
picoclaw auth models

Output:

Fetching models for project: my-project-123

Available Antigravity Models:
-----------------------------
  ✓ gemini-3-flash (Gemini 3.0 Flash)
  ✓ gemini-3-pro (Gemini 3.0 Pro)
  ✓ claude-5.6-sonnet (Claude Sonnet 5.6)
  ✗ gpt-4o (quota exhausted)

Logout from Specific Provider

picoclaw auth logout --provider openai

Output:

✓ Logged out from openai

Logout from All Providers

picoclaw auth logout

Output:

✓ Logged out from all providers

Authentication Storage

Credentials are stored securely in:

~/.config/picoclaw/auth.json

This file contains:

OAuth access tokens and refresh tokens
Pasted API tokens
Expiration times
Account metadata

Security Notes:

File permissions are set to 0600 (user read/write only)
Tokens are stored in plaintext (secure file permissions)
Refresh tokens enable automatic token renewal
OAuth tokens expire and are automatically refreshed

OAuth Token Lifecycle

Active

Token is valid and ready to use.

Needs Refresh

Token is expiring soon. PicoClaw will automatically refresh it on next use.

Expired

Token has expired. Need to re-authenticate:

picoclaw auth login --provider <provider>

Automatic Refresh

OAuth tokens are automatically refreshed when:

Token expires within refresh window
Refresh token is available
Next API call is made

No manual intervention required for active sessions.

Configuration Updates

When logging in, config.yaml is automatically updated:

providers:
  openai:
    auth_method: oauth  # Added

model_list:
  - model_name: gpt-5.2
    model: openai/gpt-5.2
    auth_method: oauth  # Added

agents:
  defaults:
    model_name: gpt-5.2  # Updated

providers:
  anthropic:
    auth_method: token  # Added

model_list:
  - model_name: claude-sonnet-4.6
    model: anthropic/claude-sonnet-4.6
    auth_method: token  # Added

agents:
  defaults:
    model_name: claude-sonnet-4.6  # Updated

Troubleshooting

Browser Won’t Open

Problem: OAuth browser window doesn’t open Solution: Use device code flow:

picoclaw auth login --provider openai --device-code

OAuth Permission Denied

Problem: “Access denied” during OAuth flow Solution:

Check you’re using the correct Google/OpenAI account
Ensure account has necessary permissions
For Antigravity, verify Cloud Code Assist is enabled

Token Invalid

Problem: “Invalid credentials” error Solution: Re-login:

picoclaw auth login --provider <provider>

Expired OAuth Token

Problem: “Token expired” error Check status:

picoclaw auth status

Solution: Re-authenticate:

picoclaw auth login --provider <provider>

Cannot Fetch Models

Problem: picoclaw auth models fails Solution:

Verify logged in: picoclaw auth status
Check project has Code Assist enabled
Verify billing is enabled
Re-login if token expired

Config Not Updated

Problem: Login succeeds but config unchanged Solution: Check file permissions:

ls -la ~/.config/picoclaw/config.yaml
chmod 644 ~/.config/picoclaw/config.yaml

Manual Token Configuration

Alternatively, you can manually add API keys to config.yaml:

providers:
  openai:
    api_key: "sk-..."
  
  anthropic:
    api_key: "sk-ant-..."
  
  openrouter:
    api_key: "sk-or-v1-..."

This bypasses OAuth but requires manual key management.

Provider Comparison

Provider	Auth Method	Browser Required	Headless Support	Auto-Refresh
OpenAI	OAuth	Yes (or device code)	Yes (device code)	Yes
Anthropic	Token	No	Yes	N/A
Google Antigravity	OAuth	Yes	No	Yes

Security Best Practices

Logout When Done: On shared machines, logout after use
```
picoclaw auth logout
```
Protect Auth File: Ensure proper permissions
```
chmod 600 ~/.config/picoclaw/auth.json
```

Rotate Tokens: Periodically re-authenticate

picoclaw auth logout --provider <provider>
picoclaw auth login --provider <provider>

Monitor Usage: Check auth status regularly
```
picoclaw auth status
```

Exit Codes

0: Success
1: Error (invalid provider, authentication failed, network error)

Get Started

Core Concepts

Commands

Configuration

Chat Channels

Features

Deployment

Advanced

​Overview

​Usage

​Subcommands

​login

​Flags

​logout

​Flags

​status

​models

​Provider-Specific Flows

​OpenAI (OAuth)

​Anthropic (Token)

​Google Antigravity (OAuth)

​Examples

​Login to OpenAI

​Login to Anthropic with Token

​Login to Google Antigravity

​Headless Server Login

​Check Authentication Status

​List Available Models (Antigravity)

​Logout from Specific Provider

​Logout from All Providers

​Authentication Storage

​OAuth Token Lifecycle

​Active

​Needs Refresh

​Expired

​Automatic Refresh

​Configuration Updates

​OpenAI Login

​Anthropic Login

​Troubleshooting

​Browser Won’t Open

​OAuth Permission Denied

​Token Invalid

​Expired OAuth Token

​Cannot Fetch Models

​Config Not Updated

​Manual Token Configuration

​Provider Comparison

​Security Best Practices

​Exit Codes

​See Also

Build docs developers (and LLMs) love

Overview

Usage

Subcommands

login

Flags

logout

Flags

status

models

Provider-Specific Flows

OpenAI (OAuth)

Anthropic (Token)

Google Antigravity (OAuth)

Examples

Login to OpenAI

Login to Anthropic with Token

Login to Google Antigravity

Headless Server Login

Check Authentication Status

List Available Models (Antigravity)

Logout from Specific Provider

Logout from All Providers

Authentication Storage

OAuth Token Lifecycle

Active

Needs Refresh

Expired

Automatic Refresh

Configuration Updates

OpenAI Login

Anthropic Login

Troubleshooting

Browser Won’t Open

OAuth Permission Denied

Token Invalid

Expired OAuth Token

Cannot Fetch Models

Config Not Updated

Manual Token Configuration

Provider Comparison

Security Best Practices

Exit Codes

See Also