# Run Scripts

Run scripts let you define frequently used shell commands in `polyscope.json` and launch them from the header bar. Each script opens in a dedicated terminal tab with a **RUN** indicator, making it easy to distinguish from regular terminal sessions.

## Defining Run Scripts

Add a `scripts.run` array to your `polyscope.json`:

```json
{
  "scripts": {
    "run": [
      "npm run dev",
      { "label": "Tests", "command": "npm run test:watch" }
    ]
  }
}
```

Each entry can be a plain string or an object. When using a string, it serves as both the label and the command. The object form supports these properties:

| Property | Type | Description |
|---|---|---|
| **`label`** | string | Display name in the UI (defaults to the command) |
| **`command`** | string | Shell command to execute |
| **`runMode`** | `"preserve"` \| `"replace"` | Per-script override for terminal tab behavior |
| **`autostart`** | boolean | Auto-run after workspace setup completes |

## Launching Scripts

When run scripts are defined, a **Run** button appears in the header bar.

- **Single script** — Click the button to run it immediately.
- **Multiple scripts** — Click the button to open a dropdown and pick the script to run. You can also press **⌘⇧R** to open the script picker from anywhere.

Each launched script opens in its own terminal tab marked with a **RUN** badge, so you can tell run script tabs apart from regular terminals at a glance.

## Run Mode

The `runMode` setting controls what happens when you launch a script that is already running.

| Mode | Behavior |
|---|---|
| **`preserve`** (default) | Opens a new terminal tab, keeping previous runs visible |
| **`replace`** | Kills the existing tab for that script and starts fresh |

Set a global default at the top level of `polyscope.json`:

```json
{
  "runMode": "replace"
}
```

Or override per script:

```json
{
  "scripts": {
    "run": [
      { "label": "Dev Server", "command": "npm run dev", "runMode": "replace" },
      { "label": "Lint", "command": "npm run lint", "runMode": "preserve" }
    ]
  }
}
```

Per-script `runMode` takes precedence over the global setting.

## Autostart

Scripts with `"autostart": true` launch automatically once the workspace finishes its setup scripts (or immediately if there are no setup scripts). This is useful for dev servers, queue workers, or file watchers that you always want running.

```json
{
  "scripts": {
    "run": [
      { "label": "Dev Server", "command": "npm run dev", "autostart": true },
      { "label": "Queue Worker", "command": "php artisan queue:work", "autostart": true }
    ]
  }
}
```

## Environment

Run scripts execute inside the workspace terminal with the `POLYSCOPE_ROOT_PATH` environment variable set to the repository root. This lets scripts reference the original repo path regardless of which worktree they run in.

Run script commands also support the `{{folder}}` placeholder, which resolves to the workspace's folder name at runtime:

```json
{
  "scripts": {
    "run": [
      { "label": "Serve", "command": "php artisan serve --host={{folder}}.test" }
    ]
  }
}
```

## Example

A full-featured Laravel setup:

```json
{
  "scripts": {
    "setup": ["herd link", "herd secure"],
    "archive": ["herd unsecure", "herd unlink"],
    "run": [
      { "label": "Queue Worker", "command": "php artisan queue:work", "autostart": true, "runMode": "replace" },
      { "label": "Vite", "command": "npm run dev", "autostart": true, "runMode": "replace" },
      { "label": "Tests", "command": "php artisan test --watch" }
    ]
  },
  "runMode": "replace",
  "preview": {
    "url": "https://{{folder}}.test"
  }
}
```