> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cirron.com/llms.txt
> Use this file to discover all available pages before exploring further.

# init

> Scaffold a new Cirron project from a template.

# cirron init

Initialize a new Cirron project with pre-configured templates for different ML frameworks. The init command creates a complete project structure with all necessary files, configuration, and dependencies.

## Usage

```bash theme={null}
cirron init [project-name] [options]
```

## Arguments

| Argument       | Description                   | Required              |
| -------------- | ----------------------------- | --------------------- |
| `project-name` | Name of the project to create | No (interactive mode) |

## Options

| Option           | Description                           | Default   |
| ---------------- | ------------------------------------- | --------- |
| `--template, -t` | Template to use (see templates below) | `pytorch` |
| `--force, -f`    | Overwrite existing directory          | `false`   |
| `--git`          | Initialize git repository             | `false`   |
| `--no-install`   | Skip dependency installation          | `false`   |

## Templates

### PyTorch Templates

```bash theme={null}
# Basic PyTorch model
cirron init my-model --template pytorch

# PyTorch training pipeline
cirron init my-model --template pytorch-train
```

Creates a project with:

* PyTorch and torchvision
* Common ML dependencies (numpy, pandas, matplotlib)
* Model definition and training scripts
* Docker configuration
* Testing setup

### TensorFlow Templates

```bash theme={null}
# Basic TensorFlow model
cirron init my-model --template tensorflow

# TensorFlow training pipeline
cirron init my-model --template tensorflow-train
```

Creates a project with:

* TensorFlow and Keras
* GPU support configuration
* Data pipeline utilities
* Model training scripts
* Docker with GPU support

### Scikit-Learn Templates

```bash theme={null}
# Basic scikit-learn model
cirron init my-model --template sklearn

# Full ML pipeline
cirron init my-model --template sklearn-pipeline
```

Creates a project with:

* scikit-learn, pandas, numpy
* Data preprocessing utilities
* Model evaluation tools
* Lightweight Docker setup

### Custom Template

```bash theme={null}
cirron init my-model --template custom
```

Creates a blank Python project for any ML framework.

## Interactive Mode

When you run `cirron init` without a project name, you'll be prompted for:

### Project Name

* **Validation**: Project name can only contain letters, numbers, hyphens, and underscores
* **Default**: `my-ml-project`

### Framework Selection

Choose from available templates:

* **PyTorch** - PyTorch model with training and inference
* **TensorFlow** - TensorFlow/Keras model with training and inference
* **Scikit-Learn** - Scikit-learn model with preprocessing and inference
* **PyTorch Training** - PyTorch training pipeline with data loading
* **TensorFlow Training** - TensorFlow training pipeline with data loading
* **Scikit-Learn Pipeline** - Full ML pipeline with preprocessing and training
* **Custom Framework** - Blank Python project for any ML framework

### Model Type

Choose from available model types:

* **Classification** - Classification models
* **Regression** - Regression models
* **Computer Vision** - Computer vision models
* **Natural Language Processing** - NLP models
* **Time Series** - Time series models
* **Custom** - Custom model types

### Additional Options

* **Include Sample Data** - Include sample data for testing (default: true)
* **Include Jupyter Notebook** - Include a Jupyter notebook for experimentation (default: true)

## Examples

### Basic Usage

```bash theme={null}
# Interactive project creation
cirron init

# Create a PyTorch project
cirron init sentiment-analysis

# Create a TensorFlow training pipeline
cirron init image-classifier --template tensorflow-train

# Create a scikit-learn pipeline
cirron init recommendation-engine --template sklearn-pipeline
```

### Advanced Usage

```bash theme={null}
# Force overwrite existing directory
cirron init my-model --force

# Initialize with git repository
cirron init my-model --git

# Skip dependency installation
cirron init my-model --no-install

# Combine options
cirron init my-model --template pytorch-train --git
```

## Project Structure

After running `cirron init`, you'll get a project structure like this:

```
my-model/
├── cirron.yaml              # Project configuration
├── src/
│   ├── __init__.py
│   ├── model.py             # Model definition
│   ├── train.py             # Training script
│   └── predict.py           # Prediction script
├── tests/
│   ├── __init__.py
│   └── test_model.py        # Unit tests
├── data/                    # Data directory
│   └── sample/              # Sample data (if included)
├── models/                  # Saved models
├── notebooks/               # Jupyter notebooks (if included)
├── Dockerfile               # Container configuration
├── requirements.txt         # Python dependencies
├── README.md               # Project documentation
└── .gitignore              # Git ignore file
```

## Configuration File

The `cirron.yaml` file is automatically created with comprehensive configuration:

```json theme={null}
{
  "name": "my-model",
  "version": "1.0.0",
  "template": "pytorch",
  "framework": "pytorch",
  "modelType": "classification",
  "pythonVersion": "3.9",
  "gpuRequired": false,
  "environments": {
    "development": {
      "name": "development",
      "url": "http://localhost:8000"
    },
    "staging": {
      "name": "staging"
    },
    "production": {
      "name": "production"
    }
  },
  "build": {
    "outputDir": "dist",
    "command": "docker build -t ${PROJECT_NAME} .",
    "include": ["src/**", "requirements.txt", "Dockerfile"],
    "exclude": ["*.pyc", "__pycache__", ".pytest_cache", "data/raw/**"]
  },
  "deploy": {
    "provider": "custom",
    "settings": {
      "containerRegistry": "harbor",
      "imageTag": "${VERSION}"
    }
  },
  "artifacts": {
    "modelPath": "models/",
    "checkpointPath": "checkpoints/",
    "logsPath": "logs/"
  },
  "test": {
    "dataPaths": {
      "sample": "data/sample/sample_data.pt",
      "validation": "data/sample/sample_data.pt",
      "inference": "data/sample/sample_data.pt"
    },
    "fallbackToDummy": true,
    "variables": {
      "featureCount": 10,
      "targetColumn": "labels",
      "dataFormat": "tensor",
      "framework": "pytorch"
    }
  },
  "metadata": {
    "modelClassName": "ClassificationModel",
    "architecture": "Neural Network",
    "lastUpdated": "2024-01-15T10:30:00.000Z",
    "inputShape": "(1, 3, 224, 224)",
    "detectedPatterns": []
  }
}
```

## Model Type Configuration

### Default Model Class Names

Each template and model type combination gets an appropriate default model class name:

* **PyTorch Classification**: `ClassificationModel`
* **PyTorch Regression**: `RegressionModel`
* **PyTorch Computer Vision**: `CNNModel`
* **PyTorch NLP**: `TransformerModel`
* **PyTorch Time Series**: `LSTMModel`
* **TensorFlow Classification**: `ClassificationModel`
* **Scikit-Learn Classification**: `ClassificationPipeline`
* **Custom**: `Model`

### Default Architectures

* **PyTorch**: Neural Network
* **TensorFlow**: Keras Model
* **Scikit-Learn**: Scikit-learn Pipeline
* **Custom**: Custom Model

### Default Input Shapes

* **PyTorch**: `(1, 3, 224, 224)`
* **TensorFlow**: `(224, 224, 3)`
* **Scikit-Learn**: Varies by dataset
* **Custom**: Not specified

## Git Integration

### Automatic Git Initialization

When using the `--git` flag, the command automatically:

1. **Initializes Git Repository**: Runs `git init`
2. **Adds All Files**: Runs `git add .`
3. **Creates Initial Commit**: Runs `git commit -m "Initial commit"`

### Git Information

If a git repository exists, the command captures:

* **Commit Hash**: Current commit hash
* **Repository Info**: Git repository metadata

## Dependency Installation

### Automatic Installation

By default, the command automatically installs dependencies. Use `--no-install` to skip. The installation:

1. **Installs Dependencies**: Runs `pip install -r requirements.txt`
2. **Error Handling**: Continues if installation fails
3. **Logging**: Shows installation progress and warnings

### Post-Install Commands

Each template includes post-install commands:

```bash theme={null}
pip install -r requirements.txt
```

## Project Registration

### Cirron API Integration

If you're authenticated with Cirron, your project will be automatically registered:

1. **API Registration**: Creates project in Cirron API
2. **Project Metadata**: Sends project configuration
3. **Error Handling**: Continues if registration fails

### Authentication Check

If not authenticated, you'll see a tip:

```
Tip: Run cirron auth login to connect to Cirron
```

## Next Steps

After initializing your project:

1. **Navigate to the project**:
   ```bash theme={null}
   cd my-model
   ```

2. **Install dependencies** (if not done automatically):
   ```bash theme={null}
   pip install -r requirements.txt
   ```

3. **Run tests**:
   ```bash theme={null}
   cirron test
   ```

4. **Build project**:
   ```bash theme={null}
   cirron build
   ```

5. **Deploy**:
   ```bash theme={null}
   cirron deploy
   ```

## Error Handling

### Directory Already Exists

```bash theme={null}
# Error: Directory 'my-model' already exists
cirron init my-model

# Interactive confirmation for overwrite
cirron init my-model
# WARNING: There is already a model with this name (my-model) and this action will overwrite existing files. This cannot be undone. Continue anyway? (y/N)
```

### Invalid Project Name

```bash theme={null}
# Error: Project name can only contain letters, numbers, hyphens, and underscores
cirron init my@model

# Valid project names
cirron init my-model
cirron init my_model
cirron init mymodel123
```

### Invalid Template

```bash theme={null}
# Error: Unknown template: invalid
cirron init my-model --template invalid

# Interactive template selection
cirron init my-model
# Choose a framework: (Use arrow keys)
# ❯ PyTorch - PyTorch model with training and inference
#   TensorFlow - TensorFlow/Keras model with training and inference
#   Scikit-Learn - Scikit-learn model with preprocessing and inference
```

### Git Initialization Fails

```bash theme={null}
# Warning: Failed to initialize git repository
cirron init my-model --git

# Solution: Ensure git is installed and configured
git --version
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
```

### Dependency Installation Fails

```bash theme={null}
# Warning: Failed to run: pip install -r requirements.txt
# Solution: Install manually
cd my-model
pip install -r requirements.txt
```

## Best Practices

### Project Naming

* **Use Descriptive Names**: Choose names that describe the project purpose
* **Follow Conventions**: Use lowercase with hyphens or underscores
* **Avoid Special Characters**: Stick to letters, numbers, hyphens, and underscores

### Template Selection

* **Choose Appropriate Framework**: Select framework based on your needs
* **Consider Training Needs**: Use training templates for full ML pipelines
* **Start Simple**: Use basic templates for simple models

### Development Workflow

* **Use Git**: Initialize git repository for version control
* **Install Dependencies**: Install dependencies immediately after creation
* **Test Early**: Run tests to verify project setup
* **Document Changes**: Update README with project-specific information

## Troubleshooting

### Common Issues

#### Permission Errors

```bash theme={null}
# Error: EACCES: permission denied
# Solution: Check directory permissions
ls -la
chmod 755 my-model
```

#### Network Issues

```bash theme={null}
# Error: Failed to register project with Cirron
# Solution: Check network connection and authentication
cirron auth status
ping app.cirron.com
```

#### Python Environment Issues

```bash theme={null}
# Error: pip install failed
# Solution: Check Python environment
python --version
pip --version
```

### Debugging Tips

* **Check Logs**: Look for detailed error messages
* **Verify Dependencies**: Ensure required tools are installed
* **Test Commands**: Run commands manually to identify issues
* **Check Permissions**: Verify file and directory permissions

## Related Commands

* **cirron auth** - Manage authentication
* **cirron test** - Test your project
* **cirron build** - Build your project
* **cirron deploy** - Deploy your project