The chisel command is the primary interface for running Python scripts on cloud GPUs. It activates GPU functionality and handles authentication, upload, and execution automatically.

​
chisel Command

The main command for executing Python scripts on cloud GPUs. 
chisel <command> [arguments...]

​
How It Works

1

Environment Setup

Sets CHISEL_ACTIVATED=1 environment variable to enable GPU functionality in ChiselApp instances.
2

Authentication Check

Verifies user authentication or initiates browser-based authentication flow if needed.
3

Command Execution

Executes the specified command with GPU functionality enabled and real-time output streaming.

​
Basic Usage

# Execute any Python script on GPU
chisel python my_script.py

# Script with command-line arguments
chisel python my_script.py --arg1 value1 --arg2 value2

# Python with complex arguments
chisel python my_script.py --config config.json --verbose

​
Environment Variables

Environment variables that control Chisel CLI behavior:

​
Core Variables

​
CHISEL_ACTIVATED
string
Set to “1” by the chisel command to activate GPU functionality. When set, ChiselApp instances will run in active mode.
​
CHISEL_BACKEND_URL
string
Override the default backend URL. Useful for testing or connecting to different environments.
​
CHISEL_API_KEY
string
Directly provide API key for authentication, bypassing stored credentials.

​
Backend Variables

These are set automatically by the backend system:
​
CHISEL_BACKEND_RUN
string
Set to “1” when code is executing on the backend. Indicates cloud GPU execution environment.
​
CHISEL_JOB_ID
string
Unique identifier for the current job. Available during backend execution for tracking and logging.

​
Environment Variable Examples

# Use production backend
export CHISEL_BACKEND_URL="https://api.herdora.com"
chisel python my_script.py

​
Real-time Output

The chisel command provides real-time streaming of execution output:

​
Output Features

​
Command Examples

​
Argument Passing

# Basic argument passing
chisel python train.py --epochs 100 --lr 0.001

# Boolean flags
chisel python train.py --verbose --save-model

# Mixed argument types
chisel python process.py --input data.csv --output results/ --batch-size 32

​
Testing and Development

# Test CUDA availability
chisel python -c "import torch; print(f'CUDA: {torch.cuda.is_available()}')"

# Test specific functionality
chisel python -c "
import torch
print(f'GPU count: {torch.cuda.device_count()}')
print(f'GPU name: {torch.cuda.get_device_name(0)}')
print(f'Memory: {torch.cuda.get_device_properties(0).total_memory / 1e9:.1f}GB')
"

​
Error Handling

The chisel command includes comprehensive error handling:

​
Common Exit Codes

Exit CodeMeaningExample
0SuccessScript completed without errors
1Script errorPython script raised an exception
2Authentication errorFailed to authenticate with backend
3Upload errorFailed to upload code to backend
4Connection errorNetwork or backend connectivity issues

​
Error Examples

chisel python my_script.py
# ❌ Authentication failed. Unable to get valid API key.
# 💡 Try: clear credentials and re-authenticate
# Exit code: 2

​
Integration Patterns

​
Shell Scripting

#!/bin/bash
# Example: Automated training pipeline

echo "🚀 Starting training pipeline..."

# Check authentication
if ! chisel python -c "from chisel.auth import is_authenticated; exit(0 if is_authenticated() else 1)"; then
    echo "❌ Authentication required"
    exit 1
fi

# Run preprocessing
echo "📊 Preprocessing data..."
chisel python preprocess.py --input raw_data/ --output processed/

# Run training
echo "🎯 Training model..."
chisel python train.py --data processed/ --output models/

# Run evaluation
echo "📈 Evaluating model..."
chisel python evaluate.py --model models/latest.pt --test-data test/

echo "✅ Pipeline complete!"

​
Makefile Integration

# Makefile for ML project with Chisel

.PHONY: install train evaluate test

install:
	chisel python -m pip install -r requirements.txt

train:
	chisel python train.py --config config/train.yaml

evaluate:
	chisel python evaluate.py --model-dir models/ --data-dir test/

test:
	chisel python -m pytest tests/ -v

clean:
	rm -rf models/ logs/ __pycache__/

pipeline: install train evaluate
	@echo "✅ Full pipeline completed"

​
CI/CD Integration

# GitHub Actions example
name: GPU Training Pipeline

on: [push, pull_request]

jobs:
  gpu-training:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    
    - name: Setup Python
      uses: actions/setup-python@v2
      with:
        python-version: '3.8'
    
    - name: Install Chisel CLI
      run: pip install chisel-cli
    
    - name: Authenticate
      env:
        CHISEL_API_KEY: ${{ secrets.CHISEL_API_KEY }}
      run: echo "Using API key from secrets"
    
    - name: Run GPU training
      env:
        CHISEL_API_KEY: ${{ secrets.CHISEL_API_KEY }}
      run: chisel python train.py --config config/ci.yaml

​
Performance Considerations

Optimize your chisel usage for better performance and cost efficiency.

​
Upload Optimization

# Reduce upload size with .gitignore
echo "__pycache__/" >> .gitignore
echo "*.pyc" >> .gitignore
echo ".venv/" >> .gitignore
echo "data/" >> .gitignore  # Don't upload large datasets

# Use specific upload directory
chisel python src/train.py  # Only uploads current directory

​
Batch Operations

# Combine multiple operations in one session
chisel python -c "
import subprocess
import sys

# Install dependencies
subprocess.run([sys.executable, '-m', 'pip', 'install', 'torch', 'transformers'])

# Run preprocessing
subprocess.run([sys.executable, 'preprocess.py'])

# Run training
subprocess.run([sys.executable, 'train.py'])

# Run evaluation
subprocess.run([sys.executable, 'evaluate.py'])
"

ChiselApp

Python API that works with CLI commands

Authentication

Authentication functions and credential management

Configuration

Environment variables and configuration options

Troubleshooting

CLI troubleshooting and common issues