Skip to main content

​
Overview

The cactus auth command manages your Cactus Cloud API key, which enables automatic cloud fallback when on-device model confidence is below the configured threshold.

​
Usage

cactus auth
Interactively prompts for your API key and saves it securely.

​
Flags

​
—status

Check the current authentication status: 
cactus auth --status
Outputs:
  • API key status (authenticated or not)
  • Associated account information
  • Key expiration if applicable

​
—clear

Remove the saved API key: 
cactus auth --clear
This logs you out and removes the stored credentials.

​
How It Works

When configured, Cactus automatically:
  1. Monitors model confidence scores during generation
  2. Triggers cloud fallback if confidence drops below cloud_handoff_threshold
  3. Seamlessly routes the query to cloud models
  4. Returns results with cloud_handoff: true in the response

​
Configuration

Set the confidence threshold in your completion options: 
{
  "max_tokens": 512,
  "cloud_handoff_threshold": 0.8
}
Queries with confidence below 0.8 will automatically use cloud models.

​
Security

API keys are stored securely in:
  • macOS: Keychain
  • Linux: Encrypted credential store
  • iOS/Android: Secure enclave (when using SDK)
Never commit API keys to version control. Always use the cactus auth command or environment variables.

​
Environment Variables

Alternatively, set the API key via environment variable: 
export CACTUS_CLOUD_API_KEY="your-api-key"

​
Getting an API Key

Visit cactuscompute.com to:
  1. Create an account
  2. Generate an API key
  3. Configure billing and usage limits

​
See Also

Cloud Fallback

Learn about hybrid on-device/cloud inference

Chat Completion

Use cloud fallback in completions