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

# vessl experiment

### Overview

Run `vessl experiment --help` to view the list of commands, `vessl experiment [COMMAND] -help` to view individual command instructions.

### Create an experiment

```
vessl experiment create [OPTIONS]
```

| Option                                | Description                                                                                                                                                |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-c`, `--cluster`                     | Cluster name (must be specified before other options)                                                                                                      |
| `-x`, `--command`                     | Start command to execute in experiment container                                                                                                           |
| `-r`, `--resource`                    | Resource type to run an experiment (for managed cluster only)                                                                                              |
| `--processor-type`                    | `CPU` or `GPU` (for custom cluster only)                                                                                                                   |
| `--cpu-limit`                         | Number of vCPUs (for custom cluster only)                                                                                                                  |
| `--memory-limit`                      | Memory limit in GiB (for custom cluster only)                                                                                                              |
| `--gpu-type`                          | <p>GPU type (for custom cluster only)</p><p>ex. <code>Tesla-K80</code></p>                                                                                 |
| `--gpu-limit`                         | Number of GPU cores (for custom cluster only)                                                                                                              |
| `--image-url`                         | Kernel docker image URL.                                                                                                                                   |
| `--upload-local-file` *(multiple)*    | <p>Upload local file. Format: \[local\_path] or \[local\_path]:\[remote\_path].</p><p>ex. <code>--upload-local-file my-project:/root/my-project</code></p> |
| `--upload-local-git-diff`             | Upload local git commit hash and diff (only works in project repositories)                                                                                 |
| `-i`, `--image-url`                   | <p>Kernel docker image URL</p><p>ex. <code>vessl/kernels:py36.full-cpu</code></p>                                                                          |
| `-m`, `--message`                     | Message                                                                                                                                                    |
| `--termination-protection`            | Enable termination protection                                                                                                                              |
| `-h`, `--hyperparameter` (*multiple*) | <p>Hyperparameters in the form of <code>\[key]=\[value]</code></p><p>ex.  <code>-h lr=0.01 -h epochs=100</code></p>                                        |
| `--dataset` (*multiple*)              | <p>Dataset mounts in the form of <code>\[mount\_path] \[dataset\_name]</code></p><p>ex. <code>--dataset /input mnist</code></p>                            |
| `--root-volume-size`                  | Root volume size (defaults to `20Gi`)                                                                                                                      |
| `--working-dir`                       | Working directory path (defaults to `/root/`)                                                                                                              |
| `--output-dir`                        | Output directory path (defaults to `/output`                                                                                                               |
| `--worker-count`                      | Number of workers (for distributed experiment only)                                                                                                        |
| `--framework-type`                    | Specify `pytorch` or `tensorflow`(for distributed experiment only)                                                                                         |

### Download experiment output files

Each user can define experiment output files. You can save validation results, trained checkpoints, best performing models and other artifacts.

```
vessl experiment download-output [OPTIONS] NUMBER
```

| Argument | Description       |
| -------- | ----------------- |
| `NUMBER` | Experiment number |

| Option            | Description                                     |
| ----------------- | ----------------------------------------------- |
| `-p`, `--path`    | Local download path (defaults to`./output`)     |
| `--worker-number` | Worker number (for distributed experiment only) |

### List all experiments

```
vessl experiment list
```

### List experiment output files

Each user can define experiment output files. You can save validation results, trained checkpoints, best models, and other artifacts.

```
vessl experiment list-output [OPTIONS] NUMBER
```

| Argument | Description       |
| -------- | ----------------- |
| `NUMBER` | Experiment number |

| Option              | Description                                     |
| ------------------- | ----------------------------------------------- |
| `-r`, `--recursive` | List files recursively                          |
| `--worker-number`   | Worker number (for distributed experiment only) |

### View logs of the experiment container

```
vessl experiment logs [OPTIONS] NUMBER
```

| Argument | Description       |
| -------- | ----------------- |
| `NUMBER` | Experiment number |

| Option            | Description                                               |
| ----------------- | --------------------------------------------------------- |
| `--tail`          | Number of lines to display from the end (defaults to 200) |
| `--worker-number` | Worker number (for distributed experiment only)           |

### View information on the experiment

```
vessl experiment read NUMBER
```

| Argument | Description       |
| -------- | ----------------- |
| `NUMBER` | Experiment number |

### Terminate an experiment

```
vessl experiment terminate NUMBER
```

| Argument | Description       |
| -------- | ----------------- |
| `NUMBER` | Experiment number |