> ## 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.

# plan

> Preview, diff, and replay deployment plans.

# cirron plan

Generate execution plans for Cirron operations (compile, build) and save, compare, or replay them. Plans show what will be executed, estimated resources, and potential issues without running anything.

## Usage

```bash theme={null}
cirron plan <command> [options]
```

## Commands

| Command   | Description                             |
| --------- | --------------------------------------- |
| `compile` | Generate compilation plan for ML models |
| `build`   | Generate build plan for ML projects     |
| `diff`    | Compare two saved plans                 |
| `save`    | Save plans for future reference         |
| `replay`  | Execute a saved plan from file          |

## Options (compile / build)

| Option              | Description                                | Default       |
| ------------------- | ------------------------------------------ | ------------- |
| `--arch, -a`        | Target architecture (`cpu`, `cuda`, `gpu`) | Auto-detected |
| `--index`           | Path to index/manifest file                | `null`        |
| `--validate`        | Run validation checks during planning      | `false`       |
| `--save`            | Save plan to file                          | `false`       |
| `--json`            | Output plan in JSON format                 | `false`       |
| `--verbose`         | Show detailed plan information             | `false`       |
| `-i, --interactive` | Enhanced planning with save options        | `false`       |

## Plan compile / build

```bash theme={null}
# Compilation plans
cirron plan compile
cirron plan compile --arch cuda
cirron plan compile --validate
cirron plan compile --save my-compile-plan.json

# Build plans (PyTorch CUDA/CPU, TensorFlow GPU/CPU, Scikit-learn CPU)
cirron plan build
cirron plan build --validate --save build-plan.json
```

Validation covers required files (`src/model.py`, `requirements.txt`), architecture-specific checks (e.g. CUDA availability), framework compatibility, and dependency resolution. The plan reports environment setup, dependency resolution, model compilation/build, architecture-specific optimization, and artifact generation steps.

## Plan diff

Compare two saved plans to identify added/removed/changed/unchanged configurations and dependencies.

```bash theme={null}
cirron plan diff plan-a.json plan-b.json
cirron plan diff plan-a.json plan-b.json --save comparison.json
```

Example diff:

```
Dependencies Changed:
- torch==1.9.0
+ torch==2.0.0
+ numpy==1.21.0

Model Params:
- Total: 1.2M -> 2.1M (+75.0%)
```

## Plan save

| Option                 | Description                          | Default        |
| ---------------------- | ------------------------------------ | -------------- |
| `--all`                | Save all plan types (compile, build) | `false`        |
| `--name <filename>`    | Custom filename                      | Auto-generated |
| `--description <desc>` | Description for the plan             | -              |
| `--tags <tags>`        | Comma-separated tags                 | -              |
| `--list`               | List all saved plans                 | `false`        |
| `--cleanup [days]`     | Remove plans older than N days       | `30`           |
| `--verbose`            | Detailed save output                 | `false`        |
| `--json`               | JSON output                          | `false`        |

```bash theme={null}
cirron plan save compile --name "production-compile" --description "Production compile"
cirron plan save build --tags "gpu,optimized"
cirron plan save --all --name "project-baseline" --tags "baseline"
cirron plan save --list
cirron plan save --cleanup 30
```

Plans are stored in `~/.cirron/plans/` with timestamp, description, tags, command type, and framework metadata.

## Plan replay

| Option          | Description                                 | Default |
| --------------- | ------------------------------------------- | ------- |
| `--plan <file>` | Plan file to replay (required)              | -       |
| `--validate`    | Validate environment compatibility          | `true`  |
| `--dry-run`     | Show what would be executed without running | `false` |
| `--verbose`     | Detailed execution information              | `false` |
| `--force`       | Force replay despite compatibility warnings | `false` |

```bash theme={null}
cirron plan replay --plan build-plan.json
cirron plan replay --plan compile-plan.json --validate
cirron plan replay --plan compile-plan.json --dry-run
cirron plan replay --plan build-plan.json --force --verbose
```

## Examples

```bash theme={null}
# Plan, compare, then execute
cirron plan compile --arch cuda --save
cirron plan build --validate --save
cirron plan diff compile-plan.json build-plan.json
cirron compile --arch cuda
cirron build

# Compare configurations
cirron plan compile --arch cpu --save cpu-plan.json
cirron plan compile --arch cuda --save cuda-plan.json
cirron plan diff cpu-plan.json cuda-plan.json

# CI/CD: generate, diff against known good, replay
cirron plan compile --arch cpu --json > compile-plan.json
cirron plan diff compile-plan.json previous-compile-plan.json
cirron plan replay --plan production-compile.json --validate
```

## Output Formats

```
Compilation Plan:
  Project: sentiment-analysis
  Framework: pytorch
  Architecture: cuda
  Generated: 1/15/2024, 10:30:00 AM

Compilation Steps:
  Environment setup
  Dependencies resolution
  Model compilation
  CUDA optimization
  Artifact generation

Generated Artifacts:
  models/model_cuda.pth
  artifacts/model_info.json
```

```json theme={null}
{
  "command": "compile",
  "framework": "pytorch",
  "architecture": "cuda",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "steps": [
    { "name": "Environment Setup", "description": "Prepare Python environment", "estimatedTime": "30s" }
  ],
  "artifacts": ["models/model_cuda.pth", "artifacts/model_info.json"]
}
```

## Troubleshooting

| Error                  | Resolution                                                 |
| ---------------------- | ---------------------------------------------------------- |
| `No cirron.yaml found` | `cirron init my-project`                                   |
| `Invalid plan files`   | Regenerate with `cirron plan compile --save new-plan.json` |

Use descriptive names and tags, save baselines before major changes, and clean up old plans regularly with `--cleanup`. Use `--json` for programmatic processing in CI/CD pipelines.