# exec

> Run a script on a remote GPU from your terminal, as if it ran locally.

`exec` submits a [Run Job](/run-jobs), streams its output while it runs, and exits with the command's exit code.

```bash
featherless-cloud exec [options] -- <command> [args...]
```

```bash
featherless-cloud exec --gpu-count 1 -- python -c "import torch; print(torch.cuda.is_available())"
featherless-cloud exec --cpu-cores 32 --volume data:/workspace -- ./preprocess.sh
featherless-cloud exec --template trainer --gpu-count 8 -- python train.py --epochs 10
featherless-cloud exec --detach --name nightly --timeout 7200 -- python eval.py
```

Your local files aren't uploaded. The command and its files must be in the image or on a mounted volume.

## Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --name <name>
      </code>
    </td>
    
    <td>
      Run Job name. Random when omitted.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --template <name>
      </code>
    </td>
    
    <td>
      Template: a name, <code>
        org/<name>
      </code>
      
      , <code>
        featherless/<name>
      </code>
      
       or an ID. The default PyTorch environment when omitted.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --template-id <id>
      </code>
    </td>
    
    <td>
      Template, by ID.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --template-version <version>
      </code>
    </td>
    
    <td>
      Version of an official template. Newest by default.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --image <reference>
      </code>
    </td>
    
    <td>
      Container image to run, or to replace the template's.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --registry <name|id>
      </code>
    </td>
    
    <td>
      Registry credential for a private image.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --gpu-type <text>
      </code>
    </td>
    
    <td>
      GPU model, matched on part of its name.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --gpu-count <n>
      </code>
    </td>
    
    <td>
      GPUs: 1, 2, 4 or 8.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cpu-cores <n>
      </code>
    </td>
    
    <td>
      vCPUs. Can't be combined with GPU options.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --disk <gb>
      </code>
    </td>
    
    <td>
      Container disk, 20–2,000. Default 20.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --volume <name>:<path>
      </code>
    </td>
    
    <td>
      Mount a network volume. Repeatable.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --workdir <path>
      </code>
    </td>
    
    <td>
      Working directory. Default <code>
        /workspace
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --env <K=V>
      </code>
    </td>
    
    <td>
      Environment variable. Repeatable.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --secret <K=V>
      </code>
    </td>
    
    <td>
      Secret variable, available as a file under <code>
        $FEATHERLESS_SECRETS_PATH
      </code>
      
      . Repeatable.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --timeout <seconds>
      </code>
    </td>
    
    <td>
      Time limit once compute is assigned, 1–86,400. Default 86,400 (24 hours).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --preemption-retries <n>
      </code>
    </td>
    
    <td>
      Times to start again from the beginning if interrupted, 0–3. Default 0.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --no-retain-logs
      </code>
    </td>
    
    <td>
      Don't collect output, including the live output <code>
        exec
      </code>
      
       prints.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --idempotency-key <key>
      </code>
    </td>
    
    <td>
      Reuse the first Run Job when the same command is retried with the same key.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --detach
      </code>
    </td>
    
    <td>
      Submit and return without waiting.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cancel-on-interrupt
      </code>
    </td>
    
    <td>
      Cancel the job on Ctrl-C, instead of detaching.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --profile <name>
      </code>
    </td>
    
    <td>
      Profile to use.
    </td>
  </tr>
</tbody>
</table>

With a template that has a start command, the command after `--` is optional.

## Exit codes

<table>
<thead>
  <tr>
    <th>
      Code
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      The command's own
    </td>
    
    <td>
      The job finished.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        124
      </code>
    </td>
    
    <td>
      The job reached its time limit.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        130
      </code>
    </td>
    
    <td>
      The job was cancelled, or you detached.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        1
      </code>
    </td>
    
    <td>
      The job failed to start, or another error.
    </td>
  </tr>
</tbody>
</table>

`--json` is available with `--detach` only.
