Developers

CLI Command Overview

The Chutes CLI provides a complete set of commands for managing your AI applications, from account setup to deployment and monitoring.

Installation

The CLI is included when you install the Chutes SDK:

pip install chutes

Verify installation:

chutes --help

Command Structure

All Chutes commands follow this pattern:

chutes <command> [subcommand] [options] [arguments]

Account Management

Create a new account with the Chutes platform.

chutes register [OPTIONS]

Options:

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

Example:

chutes register --username myuser

Link a validator or subnet owner hotkey to your account for free developer access.

chutes link [OPTIONS]

Building & Deployment

Build a Docker image for your chute.

chutes build <chute_ref> [OPTIONS]

Arguments:

  • : Chute reference in format

Options:

  • : Custom config path
  • : Path to logo image
  • : Build locally instead of remotely
  • : Enable debug logging
  • : Include entire current directory
  • : Wait for build to complete
  • : Mark image as public

Examples:

# Build remotely and wait for completion
chutes build my_chute:chute --wait

# Build locally for testing
chutes build my_chute:chute --local

# Build with a logo
chutes build my_chute:chute --logo ./logo.png --public

Deploy a chute to the platform.

chutes deploy <chute_ref> [OPTIONS]

Arguments:

  • : Chute reference in format

Options:

  • : Custom config path
  • : Path to logo image
  • : Enable debug logging
  • : Mark chute as public

Examples:

# Basic deployment
chutes deploy my_chute:chute

# Deploy with logo
chutes deploy my_chute:chute --logo ./logo.png

# Deploy as public chute
chutes deploy my_chute:chute --public

Run a chute locally for development and testing.

chutes run <chute_ref> [OPTIONS]

Arguments:

  • : Chute reference in format

Options:

  • : Host to bind to (default: 0.0.0.0)
  • : Port to listen on (default: 8000)
  • : Enable debug logging
  • : Enable development mode

Examples:

# Run on default port
chutes run my_chute:chute

# Run on custom port with debug
chutes run my_chute:chute --port 8080 --debug

# Development mode
chutes run my_chute:chute --dev

Resource Management

Manage your deployed chutes.

List your chutes.

chutes chutes list [OPTIONS]

Options:

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

Example:

chutes chutes list --limit 10 --include-public

Get detailed information about a specific chute.

chutes chutes get <name_or_id>

Example:

chutes chutes get my-awesome-chute

Delete a chute.

chutes chutes delete <name_or_id>

Example:

chutes chutes delete my-old-chute

Manage your Docker images.

List your images.

chutes images list [OPTIONS]

Options:

  • : Filter by name
  • : Number of items per page
  • : Page number
  • : Include public images

Get detailed information about a specific image.

chutes images get <name_or_id>

Delete an image.

chutes images delete <name_or_id>

Manage API keys.

Create a new API key.

chutes keys create [OPTIONS]

Options:

  • : Name for the API key (required)
  • : Grant admin access
  • : Grant access to images
  • : Grant access to chutes
  • : Specific image IDs to allow
  • : Specific chute IDs to allow
  • : Specify action scope

Examples:

# Admin key
chutes keys create --name admin-key --admin

# Read-only access to specific chute
chutes keys create --name readonly-key --chute-ids 12345 --action read

# Image management key
chutes keys create --name image-key --images

List your API keys.

chutes keys list [OPTIONS]

Get details about a specific API key.

chutes keys get <name_or_id>

Delete an API key.

chutes keys delete <name_or_id>

Utilities

Report an invocation for billing/tracking purposes.

chutes report [OPTIONS]

Change your fingerprint.

chutes refinger [OPTIONS]

Global Options

These options work with most commands:

  • : Show help message
  • : Path to custom config file
  • : Enable debug logging

Exit Codes

The CLI uses standard exit codes:

  • : Success
  • : General error
  • : Argument error
  • : Interrupted by user (Ctrl+C)

Configuration

Config File Location

Default:

Override with:

export CHUTES_CONFIG_PATH=/path/to/config.ini

Environment Variables

  • : Custom config file path
  • : API base URL
  • : Development server URL
  • : Allow missing config

Common Workflows

1. First-Time Setup

# Register account
chutes register

# Create admin API key
chutes keys create --name admin --admin

2. Develop and Deploy

# Build your image
chutes build my_app:chute --wait

# Test locally
chutes run my_app:chute --dev

# Deploy to production
chutes deploy my_app:chute

3. Manage Resources

# List your chutes
chutes chutes list

# Get detailed info
chutes chutes get my-app

# Check logs via dashboard
# (Visit https://chutes.ai)

# Clean up old resources
chutes chutes delete old-chute
chutes images delete old-image

Troubleshooting

Common Issues

Command not found

# Check installation
pip show chutes

# Try with Python module
python -m chutes --help

Authentication errors

# Re-register if needed
chutes register

# Check config file
cat ~/.chutes/config.ini

Build failures

# Try local build for debugging
chutes build my_app:chute --local --debug

# Check image syntax
python -c "from my_app import chute; print(chute.image)"

Deployment issues

# Verify image exists
chutes images list --name my-image

# Check chute status
chutes chutes get my-chute

Debug Mode

Enable debug logging for detailed output:

chutes --debug <command>

Or set environment variable:

export CHUTES_DEBUG=1
chutes <command>

Getting Help

Built-in Help

# General help
chutes --help

# Command-specific help
chutes build --help
chutes deploy --help
chutes chutes list --help

Support Resources

Advanced Usage

Scripting and Automation

The CLI is designed for scripting:

#!/bin/bash
set -e

echo "Building and deploying my chute..."

# Build
chutes build my_app:chute --wait || exit 1

# Deploy
chutes deploy my_app:chute || exit 1

# Verify deployment
chutes chutes get my-app

echo "Deployment successful!"

JSON Output

Many commands support JSON output for programmatic use:

# Get chute info as JSON
chutes chutes get my-chute --format json

# List chutes with jq processing
chutes chutes list --format json | jq '.items[].name'

CI/CD Integration

Example GitHub Actions workflow:

name: Deploy Chute
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Setup Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.11'

      - name: Install Chutes
        run: pip install chutes

      - name: Configure Chutes
        run: |
          mkdir -p ~/.chutes
          echo "${{ secrets.CHUTES_CONFIG }}" > ~/.chutes/config.ini

      - name: Deploy
        run: |
          chutes build my_app:chute --wait
          chutes deploy my_app:chute

Continue to specific command documentation: