Developers

Start

Account Management

This section covers CLI commands for managing your Chutes account, registration, authentication, and API keys.

Account Registration

Create a new account with the Chutes platform.

chutes register [OPTIONS]

Options:

  • : Custom path to config file
  • : Desired username
  • : Path to Bittensor wallets directory (default: )
  • : Name of the wallet to use
  • : Hotkey to register with

Examples:

# Basic registration with interactive prompts
chutes register

# Register with specific username
chutes register --username myusername

# Register with specific wallet
chutes register --wallet my_wallet --hotkey my_hotkey

Registration Process:

  1. Choose Username: Select a unique username for your account
  2. Wallet Selection: Choose from available Bittensor wallets
  3. Hotkey Selection: Select which hotkey to use for signing
  4. Token Verification: Complete registration token verification
  5. Config Generation: Configuration file is generated and saved

What Happens During Registration:

  • Creates your Chutes account
  • Generates initial configuration file at
  • Sets up your payment address for adding balance
  • Provides your account fingerprint (keep this safe!)

API Key Management

API keys provide programmatic access to your Chutes account and are essential for CI/CD and automation.

List all API keys for your account.

chutes keys list [OPTIONS]

Options:

  • : Filter by name
  • : Number of items per page (default: 25)
  • : Page number (default: 0)

Example:

chutes keys list

Output:

┌──────────┬─────────────────────┬─────────┬──────────────────────────┐
│ ID       │ Name                │ Admin   │ Scopes                   │
├──────────┼─────────────────────┼─────────┼──────────────────────────┤
│ key_123  │ admin               │ true    │ -                        │
│ key_456  │ ci-cd               │ false   │ {"action": "invoke"...}  │
│ key_789  │ dev                 │ false   │ {"action": "read"...}    │
└──────────┴─────────────────────┴─────────┴──────────────────────────┘

Create a new API key.

chutes keys create [OPTIONS]

Options:

  • : Name for the API key (required)
  • : Create admin key with full permissions
  • : Allow full access to images
  • : Allow full access to chutes
  • : Allow access to specific image IDs (can be repeated)
  • : Allow access to specific chute IDs (can be repeated)
  • : Specify action scope
  • : Provide raw scopes document as JSON for advanced usage
  • : Custom config path

Examples:

# Create admin key with full permissions
chutes keys create --name admin --admin

# Create key for invoking all chutes
chutes keys create --name invoke-all --chutes --action invoke

# Create key for reading specific chute
chutes keys create --name readonly-key --chute-ids my-chute-id --action read

# Create key for managing images
chutes keys create --name image-manager --images --action write

# Create key with advanced scopes using JSON
chutes keys create --name advanced-key --json-input '{"scopes": [{"object_type": "chutes", "action": "invoke"}]}'

Key Types:

  • Admin Keys: Full account access including all resources
  • Scoped Keys: Limited access based on object type and action

Using Your API Key:

After creating a key, you'll receive output like:

API key created successfully
{
  "api_key_id": "...",
  "name": "my-key",
  "secret_key": "cpk_xxxxxxxxxxxxxxxx"
}

To use the key, add "Authorization: Bearer cpk_xxxxxxxxxxxxxxxx" to your headers!

Get details about a specific API key.

chutes keys get <name_or_id>

Example:

chutes keys get my-key

Delete an API key.

chutes keys delete <name_or_id>

Example:

# Delete by name
chutes keys delete old-key

Safety Notes:

  • Deleted keys cannot be recovered
  • Active deployments using the key will lose access
  • Always rotate keys before deletion in production

Secrets Management

Secrets allow you to securely store sensitive values (like API tokens) that your chutes need at runtime.

Create a new secret for a chute.

chutes secrets create [OPTIONS]

Options:

  • : The chute UUID or name this secret is for (required)
  • : The secret key/environment variable name (required)
  • : The secret value (required)
  • : Custom config path

Examples:

# Create a HuggingFace token secret for a chute
chutes secrets create --purpose my-llm-chute --key HF_TOKEN --value hf_xxxxxxxxxxxx

# Create an API key secret
chutes secrets create --purpose my-chute --key EXTERNAL_API_KEY --value sk-xxxxxxxx

List your secrets.

chutes secrets list [OPTIONS]

Options:

  • : Number of items per page (default: 25)
  • : Page number (default: 0)

Output:

┌────────────────┬─────────────────┬─────────────┬─────────────────────┐
│ Secret ID      │ Purpose         │ Key         │ Created             │
├────────────────┼─────────────────┼─────────────┼─────────────────────┤
│ sec_123abc     │ my-llm-chute    │ HF_TOKEN    │ 2024-01-15 10:30:00 │
│ sec_456def     │ my-chute        │ API_KEY     │ 2024-01-20 14:45:00 │
└────────────────┴─────────────────┴─────────────┴─────────────────────┘

Get details about a specific secret.

chutes secrets get <secret_id>

Delete a secret.

chutes secrets delete <secret_id>

Configuration Management

Config File Structure

The Chutes configuration file () stores your account settings:

[api]
base_url = https://api.chutes.ai

[auth]
username = myusername
user_id = user_123abc456def
hotkey_seed = your_hotkey_seed
hotkey_name = my_hotkey
hotkey_ss58address = 5xxxxx...

[payment]
address = 5xxxxx...

Environment Variables

Override config settings with environment variables:

# Config path
export CHUTES_CONFIG_PATH=/path/to/config.ini

# API URL (for development/testing)
export CHUTES_API_URL=https://api.chutes.ai

# Allow missing config (useful during registration)
export CHUTES_ALLOW_MISSING=true

Multiple Configurations

Manage multiple accounts or environments:

# Create environment-specific configs
mkdir -p ~/.chutes/environments

# Production config
chutes register --config-path ~/.chutes/environments/prod.ini

# Staging config
chutes register --config-path ~/.chutes/environments/staging.ini

# Use specific config for commands
chutes build my_app:chute --config-path ~/.chutes/environments/prod.ini

Security Best Practices

API Key Security

# Use separate keys for different purposes
chutes keys create --name production-deploy --chutes --action write
chutes keys create --name monitoring --chutes --action read
chutes keys create --name ci-invoke --chutes --action invoke

# Rotate keys regularly
chutes keys create --name new-prod-key --admin
# Update your deployments to use new key
chutes keys delete old-prod-key

Account Security

  • Keep Your Fingerprint Safe: Your fingerprint is shown during registration - don't share it
  • Secure Your Hotkey: The hotkey seed in your config file should be kept private
  • Regular Audits: Review your API keys periodically and delete unused ones
  • Environment Separation: Use different keys for dev/staging/prod

CI/CD Security

# GitHub Actions example
env:
  CHUTES_API_KEY: ${{ secrets.CHUTES_API_KEY }}

steps:
  - name: Deploy to Chutes
    run: |
      pip install chutes
      mkdir -p ~/.chutes
      cat > ~/.chutes/config.ini << EOF
      [api]
      base_url = https://api.chutes.ai
      
      [auth]
      # Use API key authentication
      EOF
      chutes deploy my_app:chute --accept-fee

Troubleshooting

Common Issues

Registration fails?

# Check network connectivity
curl -I https://api.chutes.ai/ping

# Try with different username (may already be taken)
chutes register --username alternative_username

# Verify wallet path exists
ls ~/.bittensor/wallets/

API key not working?

# Verify key exists and check scopes
chutes keys list
chutes keys get my-key

# Ensure you're using the secret_key value with "Authorization: Bearer" header

Configuration issues?

# Check config file exists and has correct format
cat ~/.chutes/config.ini

# Verify environment variables aren't overriding
echo $CHUTES_CONFIG_PATH
echo $CHUTES_API_URL

Getting Help

Next Steps