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

# run

> Trigger training runs and pipeline jobs.

# cirron run

Manage training runs, pipeline executions, batch inference, and hyperparameter sweeps. The run command provides subcommands for triggering, monitoring, and managing compute jobs on the Cirron platform.

## Usage

```bash theme={null}
cirron run <subcommand> [options]
```

## Subcommands

| Subcommand               | Description                  |
| ------------------------ | ---------------------------- |
| `pipeline [name]`        | Trigger a pipeline run       |
| `job`                    | Execute a single-task job    |
| `inference [deployment]` | Trigger batch inference      |
| `sweep`                  | Trigger hyperparameter sweep |
| `list`                   | List all runs and jobs       |
| `status <runId>`         | Get run status               |
| `cancel <runId>`         | Cancel a running job         |
| `logs <runId>`           | Stream run logs              |

## Pipeline

Trigger a pipeline run by name with optional configuration.

```bash theme={null}
cirron run pipeline my-pipeline -c config.yaml --watch
```

### Pipeline Options

| Option                | Description                                | Default  |
| --------------------- | ------------------------------------------ | -------- |
| `-c, --config <file>` | Pipeline config file (YAML/JSON)           | -        |
| `--gpu <type>`        | GPU type override                          | -        |
| `--priority <level>`  | Job priority (low, normal, high, critical) | `normal` |
| `--tag <tags>`        | Comma-separated run tags                   | -        |
| `--dry-run`           | Show what would execute without running    | `false`  |
| `--watch`             | Stream output and wait for completion      | `false`  |

### Examples

```bash theme={null}
# Trigger a pipeline with config
cirron run pipeline training-pipeline -c config.yaml

# Watch pipeline execution
cirron run pipeline my-pipeline --watch

# High-priority GPU run
cirron run pipeline my-pipeline --gpu a100 --priority high

# Dry run to preview
cirron run pipeline my-pipeline -c config.yaml --dry-run
```

## Job

Execute a single-task job.

```bash theme={null}
cirron run job -c job-config.yaml
```

### Job Options

| Option                | Description                             | Default  |
| --------------------- | --------------------------------------- | -------- |
| `-c, --config <file>` | Job config file                         | -        |
| `--gpu <type>`        | GPU type override                       | -        |
| `--priority <level>`  | Job priority                            | `normal` |
| `--dry-run`           | Show what would execute without running | `false`  |

## Inference

Trigger batch inference on a deployment.

```bash theme={null}
cirron run inference my-deployment -i data/input.csv -o results/
```

### Inference Options

| Option                | Description               | Default |
| --------------------- | ------------------------- | ------- |
| `-i, --input <path>`  | Input data path           | -       |
| `-o, --output <path>` | Output path               | -       |
| `--model <name>`      | Model name/version to use | -       |
| `--batch-size <n>`    | Batch size override       | -       |
| `--watch`             | Stream output             | `false` |

## Sweep

Trigger a hyperparameter sweep.

```bash theme={null}
cirron run sweep -c sweep-config.yaml --trials 50 --strategy bayesian
```

### Sweep Options

| Option                | Description                              | Default |
| --------------------- | ---------------------------------------- | ------- |
| `-c, --config <file>` | Sweep config file                        | -       |
| `--trials <n>`        | Number of trials                         | -       |
| `--parallel <n>`      | Max parallel trials                      | -       |
| `--strategy <type>`   | Search strategy (grid, random, bayesian) | -       |
| `--watch`             | Stream output                            | `false` |

## List

List all runs and jobs.

```bash theme={null}
cirron run list --status running --last 10
```

### List Options

| Option              | Description                                              | Default |
| ------------------- | -------------------------------------------------------- | ------- |
| `--status <status>` | Filter by status (running, completed, failed, cancelled) | -       |
| `--last <n>`        | Show last N runs                                         | -       |
| `--pipeline <name>` | Filter by pipeline                                       | -       |
| `--json`            | Output in JSON format                                    | `false` |

Runs are also accessible via `cirron list runs`.

## Status

Check the status of a specific run.

```bash theme={null}
cirron run status <runId> --json
```

### Status Options

| Option    | Description           | Default |
| --------- | --------------------- | ------- |
| `--json`  | Output in JSON format | `false` |
| `--watch` | Poll for updates      | `false` |

## Cancel

Cancel a running job.

```bash theme={null}
cirron run cancel <runId> --force
```

### Cancel Options

| Option    | Description                       | Default |
| --------- | --------------------------------- | ------- |
| `--force` | Force cancel without confirmation | `false` |

## Logs

Stream logs for a run.

```bash theme={null}
cirron run logs <runId> -f
```

### Logs Options

| Option                 | Description             | Default |
| ---------------------- | ----------------------- | ------- |
| `-f, --follow`         | Follow log output       | `false` |
| `-n, --lines <number>` | Number of lines to show | -       |

## Examples

### Training Workflow

```bash theme={null}
# Trigger a training pipeline
cirron run pipeline training -c train-config.yaml --watch

# Check status
cirron run status abc123

# View logs
cirron run logs abc123 -f

# List recent runs
cirron run list --last 5
```

### Batch Inference

```bash theme={null}
# Run inference on a deployed model
cirron run inference prod-deployment -i data/batch.csv -o results/

# Monitor the run
cirron run status def456 --watch
```

### Hyperparameter Search

```bash theme={null}
# Launch a sweep
cirron run sweep -c sweep.yaml --trials 100 --parallel 4 --strategy bayesian --watch

# Cancel if needed
cirron run cancel ghi789 --force
```