Complete documentation for all Chisel CLI components including the Python API, command-line interface, and configuration options.

​
Overview

Chisel CLI provides a simple Python API for GPU acceleration with minimal changes to your existing code. The main components are:

ChiselApp

Main class for creating GPU-accelerated applications

GPU Types

Available GPU configurations and selection guide

Authentication

Authentication functions and credential management

CLI Commands

Command-line interface and environment variables

​
Quick Reference

​
Basic Usage Pattern

from chisel import ChiselApp, GPUType

# Create app with GPU configuration
app = ChiselApp("my-app", gpu=GPUType.A100_80GB_2)

# Mark functions for GPU execution
@app.capture_trace(trace_name="my_operation")
def my_gpu_function(data):
    import torch
    device = "cuda" if torch.cuda.is_available() else "cpu"
    # Your GPU code here
    return result

# Execute on cloud GPU
# chisel python my_script.py

​
Import Reference

from chisel import ChiselApp, GPUType

​
How It Works

1

Local Mode

When CHISEL_ACTIVATED != "1":
  • ChiselApp runs in inactive mode
  • Decorators are pass-through (no-op)
  • Code runs normally on local machine
# This runs locally
python my_script.py
2

Chisel Mode

When using the chisel command:
  • Sets CHISEL_ACTIVATED=1 environment variable
  • Activates GPU functionality in ChiselApp
  • Uploads code and runs on cloud GPU
# This runs on cloud GPU
chisel python my_script.py
3

Backend Mode

When CHISEL_BACKEND_RUN=1 (set by backend):
  • Detects execution on cloud infrastructure
  • Skips authentication and upload steps
  • Executes functions with GPU tracing enabled

​
Type Hints Support

Chisel CLI includes full type hint support for modern Python development: 
from typing import Optional, Any
from chisel import ChiselApp, GPUType
import numpy as np

def create_app(name: str, gpu: Optional[GPUType] = None) -> ChiselApp:
    return ChiselApp(name, gpu=gpu)

@app.capture_trace(trace_name="typed_function")
def process_data(data: np.ndarray, size: int = 1000) -> np.ndarray:
    import torch
    tensor = torch.from_numpy(data)
    return (tensor * 2).numpy()

​
Error Handling

All Chisel CLI functions include proper error handling with descriptive messages:

​
Best Practices

Follow these patterns for optimal Chisel CLI usage:
  1. Always test locally first - Verify your code works before GPU execution
  2. Use appropriate GPU types - Match GPU memory to your workload requirements
  3. Handle device placement - Check for CUDA availability in your functions
  4. Manage memory efficiently - Clear GPU cache and process in batches for large data
  5. Use meaningful trace names - Help with debugging and monitoring
# Example following best practices
@app.capture_trace(trace_name="data_processing", record_shapes=True)
def process_large_dataset(data):
    import torch
    
    device = "cuda" if torch.cuda.is_available() else "cpu"
    
    # Process in chunks to manage memory
    batch_size = 1000
    results = []
    
    for i in range(0, len(data), batch_size):
        batch = data[i:i+batch_size]
        batch_tensor = torch.tensor(batch, device=device)
        
        # Your processing here
        result = process_batch(batch_tensor)
        results.append(result.cpu())  # Move back to CPU
        
        # Clear GPU memory periodically
        if i % (batch_size * 10) == 0:
            torch.cuda.empty_cache()
    
    return torch.cat(results)

​
Next Steps

ChiselApp API

Detailed ChiselApp class documentation

Working Examples

Complete examples and usage patterns