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

# cassian exec

> Run a command on the instance.

## Usage

```bash theme={null}
cassian exec <command> [options]
cassian exec "python train.py --epochs 50"
cassian exec -d "python long_training.py"
cassian exec -i my-instance "nvidia-smi"
```

Pushes your local files to `/workspace`, runs the command, and prints stdout/stderr. Exits with the command's exit code.

## Options

| Flag                    | Description                                      | Default      |
| ----------------------- | ------------------------------------------------ | ------------ |
| `--timeout <seconds>`   | Max execution time                               | `3600`       |
| `--no-sync`             | Skip file push before running                    | `false`      |
| `-d, --detach`          | Run in background, return immediately            | `false`      |
| `-w, --workdir <path>`  | Working directory inside the container           | `/workspace` |
| `-i, --instance <name>` | Target instance by name (no cassian.yaml needed) | —            |

## Background execution

Use `--detach` for long-running jobs. You get your terminal back immediately.

```bash theme={null}
cassian exec -d "python train.py --epochs 500"
# ✓ Running in background (task: a1b2c3d4)
#   View output: cassian logs
```

## Running without a project directory

`-i / --instance` lets you target any instance from anywhere:

```bash theme={null}
cassian exec -i my-training-run "nvidia-smi"
cassian exec -i my-training-run --no-sync "tail -f /workspace/train.log"
```

Useful for monitoring, CI scripts, and AI agents that manage instances on your behalf.

## Working directory

```bash theme={null}
# Run tests from a specific subdirectory
cassian exec -w /workspace/src "pytest tests/"

# Default is /workspace
cassian exec "ls"
```

## What gets pushed

Only default (hot) files. Folders under `no_sync`, `storage`, and `exclude` in your `cassian.yaml` are skipped.

Sync output is shown before the command runs:

```
  Syncing 3 files...
  Synced 3 files (12KB)
```

You'll get a warning above 500MB. The hard limit is 2GB — above that, add excludes or move files to `/workspace/storage`.

## Examples

```bash theme={null}
# Training
cassian exec "python train.py --epochs 50"

# Background job
cassian exec -d "python sweep.py"

# Check GPU without pushing
cassian exec --no-sync "nvidia-smi"

# Run from a specific directory
cassian exec -w /workspace/experiments "python run.py"

# Monitor another instance from anywhere
cassian exec -i training-run --no-sync "tail -f /workspace/loss.log"
```