# Mags Job Runner

Execute scripts on Magpie's instant microVM infrastructure using the `mags` CLI.

## How to Use

IMPORTANT: Always use the `mags` CLI tool. NEVER use curl or direct API calls.
The CLI handles authentication, polling, and output automatically.

When the user says `/mags <command or description>`, run it using the `mags` CLI.

## Commands

### Run a script
```bash
mags run '<script>'
```

### Run with a persistent workspace (changes saved to S3)
```bash
mags run -w <workspace-name> '<script>'
```

### Run a persistent VM with public URL
```bash
mags run -p --url '<script>'
```

### Run with workspace + persistence + URL + custom port
```bash
mags run -w <workspace> -p --url --port 3000 '<script>'
```

### Create a new persistent VM (stays alive for SSH)
```bash
mags new <name>
```

### SSH into a running VM
```bash
mags ssh <name-or-id>
```

### Check job status
```bash
mags status <name-or-id>
```

### View job logs
```bash
mags logs <name-or-id>
```

### List recent jobs
```bash
mags list
```

### Enable URL access on existing job
```bash
mags url <name-or-id> [port]
```

### Stop a running job
```bash
mags stop <name-or-id>
```

### Run without workspace (ephemeral, fastest)
```bash
mags run -e '<script>'
```

### Upload files into the VM before running
```bash
mags run -f script.py -f data.csv 'python3 script.py'
```

### Cron: schedule recurring jobs
```bash
mags cron add --name "daily-backup" --schedule "0 0 * * *" 'tar czf /root/backup.tar.gz /root/data'
mags cron list
mags cron remove <id>
mags cron enable <id>
mags cron disable <id>
```

## CLI Flags for `run`

| Flag | Description |
|------|-------------|
| `-w, --workspace <id>` | Persistent workspace (S3 sync) |
| `-n, --name <name>` | Job name for easier reference |
| `-p, --persistent` | Keep VM alive after script |
| `-e, --ephemeral` | No workspace, no S3 sync (fastest). Cannot combine with -w or -p |
| `-f, --file <path>` | Upload a file into /root/ in the VM (repeatable) |
| `--url` | Enable public URL (requires -p) |
| `--port <port>` | Port to expose (default: 8080) |
| `--startup-command <cmd>` | Command to run when VM wakes |

## Workflow

When the user asks to run something on mags:

1. **Parse the request** - determine the script/command and any flags needed
2. **Run via CLI** - use `mags run '<script>'` (with appropriate flags)
3. **Show the output** - the CLI handles polling and displays results automatically

## Examples

### Simple command
User: `/mags echo Hello World`
```bash
mags run 'echo Hello World'
```

### Install packages and run code
User: `/mags run python with numpy`
```bash
mags run 'apk add python3 py3-pip && pip install numpy && python3 -c "import numpy; print(numpy.array([1,2,3]))"'
```

### Deploy a web server
User: `/mags deploy a python web server`
```bash
mags run -p --url 'python3 -m http.server 8080'
```

### Persistent workspace
User: `/mags set up a node project in my-app workspace`
```bash
mags run -w my-app 'apk add nodejs npm && mkdir -p /workspace/my-app && cd /workspace/my-app && npm init -y'
```

### Ephemeral (no workspace, fastest)
User: `/mags quickly check disk info`
```bash
mags run -e 'df -h && uname -a'
```

### Upload a file and run it
User: `/mags run my local script.py in a VM`
```bash
mags run -f script.py 'python3 script.py'
```

### Upload multiple files
User: `/mags run my analysis with the data file`
```bash
mags run -f analyze.py -f data.csv 'python3 analyze.py'
```

### Schedule a cron job
User: `/mags schedule a health check every hour`
```bash
mags cron add --name "health-check" --schedule "0 * * * *" 'curl -sf https://example.com/health || echo FAIL'
```

## Authentication

The CLI reads credentials from `~/.mags/config.json` (set via `mags login`).
If not authenticated, tell the user to run `mags login` first.
Do NOT hardcode tokens or use environment variables for auth.

## Important Rules

1. ALWAYS use `mags run '...'` - never use curl or direct API calls
2. ALWAYS quote the script argument in single quotes
3. The CLI handles job submission, polling, and log retrieval automatically
4. For multi-line scripts, use semicolons or `&&` to chain commands
5. If the user wants to create a VM and SSH in, use `mags new <name>` then `mags ssh <name>`
