Authentication

Nyzhi supports three ways to authenticate with LLM providers: environment variables, config files, and interactive login. You can mix and match — Nyzhi checks them in a specific order.

Quickest Way to Connect

Launch Nyzhi and use the built-in provider selector:

nyz

Then type:

/connect

This opens an interactive picker where you can choose a provider, authenticate via OAuth (when available) or paste an API key. It’s the recommended way to set up your first provider.

Credential Resolution Order

When Nyzhi needs an API key for a provider, it checks in this order:

1. Config file — api_key set in [provider.<id>] in your config
2. Environment variable — e.g. OPENAI_API_KEY
3. Token store — saved credentials from /connect or nyz login

The first match wins. If nothing is found, Nyzhi tells you which env var it expected and (for OAuth-capable providers) suggests using /connect or running nyz login.

Setting Up API Keys

Option 1: Environment Variable (Recommended)

The simplest and most secure approach for most setups:

# Add to your shell profile (~/.zshrc, ~/.bashrc, etc.)
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export DEEPSEEK_API_KEY="sk-..."

Then reload your shell or run source ~/.zshrc.

Option 2: Config File

Set the key directly in your config. Useful for switching between multiple keys:

# ~/.config/nyzhi/config.toml

[provider.openai]
api_key = "sk-..."

[provider.anthropic]
api_key = "sk-ant-..."

Warning: Don’t commit config files that contain api_key values. Use environment variables or nyz login for shared repositories.

Option 3: Interactive Login

The easiest approach — use /connect inside the TUI or nyz login from the CLI:

nyz login cursor

This opens a browser for authentication and stores the token locally. No API key needed.

Auth Commands

/connect (Recommended)

The default interactive auth path. Launch nyz and type /connect:

/connect

Opens a provider picker, then authenticates via OAuth (when supported) or prompts for an API key. This is the recommended flow for interactive use.

nyz login

CLI fallback for when you’re not in the TUI:

# Interactive — shows a provider picker
nyz login

# Direct — log in to a specific provider
nyz login openai
nyz login anthropic
nyz login cursor

What happens:

• OAuth-capable providers — opens a browser for authentication
• Other providers — prompts for an API key interactively

nyz logout

Removes stored credentials for a provider:

nyz logout openai

nyz whoami

Shows your authentication status across all configured providers:

nyz whoami

Output looks like:

openai       env          (OPENAI_API_KEY)
anthropic    connected    (token store)
deepseek     env          (DEEPSEEK_API_KEY)
cursor       not connected
ollama       connected    (local)

Status values:

Multi-Account Support

Nyzhi supports multiple accounts per provider with labeled entries. This is useful when you have personal and work accounts, or when you want to spread load across API keys.

How It Works

The token store (~/.local/share/nyzhi/auth.json) holds an array of accounts per provider:

{
  "openai": [
    { "label": "personal", "active": true, "token": { "access_token": "sk-..." } },
    { "label": "work", "active": false, "token": { "access_token": "sk-..." } }
  ]
}

Rate-Limit Rotation

When a provider returns a rate-limit error, Nyzhi automatically:

1. Marks the active account as rate-limited for 60 seconds
2. Switches to the next eligible account
3. Retries the request

If no eligible fallback account exists, the error propagates normally.

Good to know: Rotation only applies to accounts in the token store. Environment variable credentials don’t participate in rotation.

Provider Environment Variables

Every built-in provider has a corresponding environment variable:

Token Storage Location

Tokens are stored at:

~/.local/share/nyzhi/auth.json

This path is platform-dependent (uses dirs::data_local_dir()). On macOS, it’s typically ~/Library/Application Support/nyzhi/auth.json.

Security Best Practices

1. Use /connect for personal development — the easiest way to get started
2. Use environment variables for CI/CD and shared machines
3. Never commit config.toml files containing api_key values
4. Add to .gitignore: .nyzhi/config.local.toml
5. Use nyz logout to clean up credentials when switching machines

Next Steps

• Providers — full list of supported providers and their models
• Configuration — the complete config reference
• Getting Started — set up your first provider