Scripts and automation

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:

[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.

#!/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.

Write a startup script

Follow the complete CLI guide, including resource IDs and failure handling.

Setup command

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

[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.

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

Named run commands

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

[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:

[scripts.run.dev]
hide = true

Archive command

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

[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.

Get started

Guides

Cookbook

Reference

Advanced automation

Project settings

Scripts and automation

Startup command

Write a startup script

Setup command

Named run commands

Archive command

Script environment

​Startup command

Write a startup script

​Setup command

​Named run commands

​Archive command

​Script environment

Startup command

Setup command

Named run commands

Archive command

Script environment