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

# Scripts and automation

> Configure startup, setup, run, and archive commands for projects and worktrees.

Project scripts cover four different moments in a workspace lifecycle.

| Script    | When it runs                                                | Where it runs                      | Failure behavior                                       |
| --------- | ----------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------ |
| Startup   | When Radius creates a configured project or worktree group. | Visible terminal tab in the group. | Keeps completed layout changes and stops the script.   |
| Setup     | After Radius creates a new worktree.                        | Visible project terminal.          | Leaves the worktree open so you can fix and rerun it.  |
| Named run | When you choose it from the terminal's **Run…** menu.       | Active project terminal.           | Reports the exit status without closing the workspace. |
| Archive   | Before Radius removes a worktree.                           | Worktree directory.                | Blocks removal when it fails.                          |

## Startup command

Use a startup command to arrange a project group with the Radius CLI:

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[scripts]
startup = "./scripts/open-radius-workspace.sh"
```

Radius creates the group and its terminal before launching the command. The
command receives `RADIUS_WINDOW_ID`, `RADIUS_GROUP_ID`, and `RADIUS_TAB_ID`, so it can
open tabs and build splits relative to its own terminal.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
#!/usr/bin/env bash
set -euo pipefail

radius group rename "$RADIUS_GROUP_ID" "Development"
radius tab open "https://github.com/example/project/pulls"
radius tab open "http://localhost:3000" --right-of "$RADIUS_TAB_ID" --size 60%
```

Startup commands are literal automation, not a saved layout. Radius does not
reuse matching URLs, undo completed commands after a failure, or continue
enforcing the result after the script exits.

<Card title="Write a startup script" icon="code" href="/docs/guides/startup-scripts">
  Follow the complete CLI guide, including resource IDs and failure handling.
</Card>

## Setup command

Use setup for dependencies or generated files required by a newly created
worktree:

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[scripts]
setup = "pnpm install --frozen-lockfile"
```

Radius opens the worktree, exposes its terminal, and runs setup visibly. The
worktree records whether setup is pending, running, successful, failed, or
interrupted.

If setup fails, open the terminal's **Run…** menu and run **Setup** again after
fixing the problem.

<Note>
  Setup prepares files inside a worktree. Startup arranges the Radius group around
  that worktree. Keep them separate even when both commands run during creation.
</Note>

## Named run commands

Named run commands appear in the terminal's **Run…** menu:

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[scripts.run.dev]
name = "Development server"
command = "pnpm dev"

[scripts.run.test]
name = "Tests"
command = "pnpm test"
```

The table name after `scripts.run` is the stable script ID. `name` is the label
shown in Radius. If you omit the name, Radius derives one from the ID.

To hide a shared run command on one machine, add this to
`.radius/settings.local.toml`:

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[scripts.run.dev]
hide = true
```

## Archive command

Use archive for cleanup or validation that must finish before a worktree is
removed:

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[scripts]
archive = "pnpm run cleanup"
```

The command runs from the worktree directory with the effective project
environment. A non-zero exit status blocks deletion.

## Script environment

All project scripts receive variables from project settings plus:

* `RADIUS_PROJECT_ROOT`
* `RADIUS_WORKSPACE_PATH`
* `RADIUS_WORKSPACE_NAME`
* `RADIUS_DEFAULT_BRANCH`

Startup terminals also receive the [Radius CLI resource IDs](/docs/reference/commands#ids).