provider - nanobot

Usage

nanobot provider [COMMAND] [OPTIONS]

Description

The provider command group manages authentication for OAuth-based AI providers that require interactive login flows instead of static API keys. Supported OAuth providers:

OpenAI Codex: IDE integrations (Cursor, Windsurf)
GitHub Copilot: GitHub-authenticated models

Subcommands

Authenticate with an OAuth provider.

nanobot provider login <provider-name>

Authenticate with an OAuth provider using an interactive login flow.

Usage

nanobot provider login <provider>

Arguments

provider

string

required

OAuth provider name. Supported values:

openai-codex
github-copilot

nanobot provider login openai-codex

OpenAI Codex

Authenticate with OpenAI Codex (used by Cursor, Windsurf, and other AI coding tools).

Usage

nanobot provider login openai-codex

Requirements

Python package: oauth-cli-kit

pip install oauth-cli-kit

nanobot provider login openai-codex

Output:

🐈 OAuth Login - OpenAI Codex

[cyan]Starting interactive OAuth login...[/cyan]

Opening browser for authentication...

1. Visit: https://api.openai.com/oauth/authorize?...
2. Authorize nanobot
3. Copy the authorization code

Enter authorization code: _

Authorization Flow

Browser opens automatically (or you click the URL)
Log in with your OpenAI account
Authorize the application
Copy the authorization code
Paste it in the terminal

Successful Authentication

[green]✓ Authenticated with OpenAI Codex[/green]  [dim][email protected][/dim]

Your credentials are stored securely.

Subsequent Logins

If already authenticated:

nanobot provider login openai-codex

Output:

[green]✓ Authenticated with OpenAI Codex[/green]  [dim][email protected][/dim]

No re-authentication needed (token is reused).

Token Storage

Tokens are stored by oauth-cli-kit in:

macOS: Keychain
Linux: Secret Service (GNOME Keyring, KWallet)
Windows: Credential Manager

Using OpenAI Codex

After authentication, configure your model:

{
  "agents": {
    "defaults": {
      "model": "openai-codex/gpt-4o"
    }
  }
}

Available models:

openai-codex/gpt-4o
openai-codex/gpt-4o-mini
openai-codex/gpt-4-turbo
openai-codex/o1
openai-codex/o1-mini

GitHub Copilot

Authenticate with GitHub Copilot using device flow.

Usage

nanobot provider login github-copilot

Device Flow

nanobot provider login github-copilot

Output:

🐈 OAuth Login - GitHub Copilot

[cyan]Starting GitHub Copilot device flow...[/cyan]

To authenticate:
1. Visit: https://github.com/login/device
2. Enter code: ABCD-1234

Waiting for authorization...

Authorization Steps

Visit the URL shown
Enter the device code
Authorize GitHub Copilot access
Return to terminal

Successful Authentication

[green]✓ Authenticated with GitHub Copilot[/green]

Requirements

GitHub Copilot subscription (Individual, Business, or Enterprise)
LiteLLM with GitHub Copilot support

Using GitHub Copilot

After authentication, configure your model:

{
  "agents": {
    "defaults": {
      "model": "github_copilot/gpt-4o"
    }
  }
}

Available models:

github_copilot/gpt-4o
github_copilot/gpt-4-turbo
github_copilot/claude-3.5-sonnet
github_copilot/o1-preview
github_copilot/o1-mini

Verifying Authentication

Check authentication status:

nanobot status

Output:

🐈 nanobot Status

Config: ~/.nanobot/config.json [green]✓[/green]
Workspace: ~/.nanobot/workspace/ [green]✓[/green]
Model: openai-codex/gpt-4o
OpenAI Codex: [green]✓ (OAuth)[/green]
GitHub Copilot: [green]✓ (OAuth)[/green]

Token Refresh

OAuth tokens are automatically refreshed when expired. If refresh fails:

[red]Authentication error: Token expired[/red]

Solution: Re-authenticate:

nanobot provider login openai-codex

Logout

To remove OAuth credentials:

OpenAI Codex

Tokens are managed by oauth-cli-kit. Remove manually:

# Find token location
python -c "from oauth_cli_kit import get_token_file; print(get_token_file())"

# Remove token file
rm /path/to/token/file

GitHub Copilot

Tokens are managed by LiteLLM. Check LiteLLM docs for token location.

Troubleshooting

oauth-cli-kit Not Installed

[red]oauth_cli_kit not installed. Run: pip install oauth-cli-kit[/red]

Solution:

pip install oauth-cli-kit

Browser Doesn’t Open

Opening browser for authentication...
[red]Failed to open browser[/red]

Solution: Manually visit the URL shown:

1. Visit: https://api.openai.com/oauth/authorize?...

Invalid Authorization Code

[red]Invalid authorization code[/red]

Solution:

Ensure you copied the complete code
Code may have expired - start over
Try again: nanobot provider login openai-codex

Authentication Failed

[red]Authentication error: ...[/red]

Common causes:

Network connectivity issues
Firewall blocking OAuth endpoints
Proxy interfering with requests
Invalid credentials

Solution:

# Check network
ping api.openai.com

# Try with verbose logging (if available)
export DEBUG=oauth:*
nanobot provider login openai-codex

GitHub Copilot: No Subscription

[red]GitHub Copilot subscription required[/red]

Solution: Subscribe to GitHub Copilot:

https://github.com/features/copilot

Token Storage Failed

[red]Failed to store token in keychain[/red]

Solution (Linux):

# Install keyring backend
sudo apt-get install gnome-keyring
# or
sudo apt-get install kwalletmanager

# Verify
python -c "import keyring; print(keyring.get_keyring())"

Provider Comparison

Provider	Authentication	Models	Use Case
OpenAI Codex	OAuth browser flow	GPT-4o, o1, o1-mini	IDE integrations, power users
GitHub Copilot	Device code flow	GPT-4o, Claude, o1	GitHub subscribers
OpenRouter	API key	200+ models	General purpose, model variety
OpenAI	API key	GPT-4, GPT-3.5	Official API access

When to Use OAuth

Use OAuth providers when:

You have an existing subscription (Cursor, Windsurf, GitHub Copilot)
You want unified billing
You need specific model access
You prefer browser-based authentication

Use API key providers when:

You want simple setup
You’re using scripts/automation
You need multiple accounts
You want explicit cost control

Exit Codes

0: Success
1: Error (authentication failed, network error, missing dependency)
130: Interrupted by user (Ctrl+C)

status - Check authentication status
agent - Use authenticated models
onboard - Initial configuration

CLI Commands

Agent API

Tools

Configuration Schema

​Usage

​Description

​Subcommands

​login

​provider login

​Usage

​Arguments

​OpenAI Codex

​Usage

​Requirements

​First Login

​Authorization Flow

​Successful Authentication

​Subsequent Logins

​Token Storage

​Using OpenAI Codex

​GitHub Copilot

​Usage

​Device Flow

​Authorization Steps

​Successful Authentication

​Requirements

​Using GitHub Copilot

​Verifying Authentication

​Token Refresh

​Logout

​OpenAI Codex

​GitHub Copilot

​Troubleshooting

​oauth-cli-kit Not Installed

​Browser Doesn’t Open

​Invalid Authorization Code

​Authentication Failed

​GitHub Copilot: No Subscription

​Token Storage Failed

​Provider Comparison

​When to Use OAuth

​Exit Codes

​Related Commands

​See Also

Build docs developers (and LLMs) love

Usage

Description

Subcommands

login

provider login

Usage

Arguments

OpenAI Codex

Usage

Requirements

First Login

Authorization Flow

Successful Authentication

Subsequent Logins

Token Storage

Using OpenAI Codex

GitHub Copilot

Usage

Device Flow

Authorization Steps

Successful Authentication

Requirements

Using GitHub Copilot

Verifying Authentication

Token Refresh

Logout

OpenAI Codex

GitHub Copilot

Troubleshooting

oauth-cli-kit Not Installed

Browser Doesn’t Open

Invalid Authorization Code

Authentication Failed

GitHub Copilot: No Subscription

Token Storage Failed

Provider Comparison

When to Use OAuth

Exit Codes

Related Commands

See Also