Skip to main content
Scripts automate repetitive tasks in your workflow. Set them up once, and Termpad runs them at the right time automatically.

​
Script Types

Termpad supports three types of scripts:
TypeWhen It RunsUse For
SetupWhen creating a new worktreeInstalling dependencies, building assets
RunWhen you click “Run”Starting dev server, running tests
CleanupWhen deleting a worktreeStopping processes, cleaning artifacts

​
Configuring Scripts

1

Open project settings

Click the gear icon next to the project name.
2

Add your scripts

Enter commands for each script type.

​
Setup Scripts

Setup scripts run automatically when you create a new worktree. Use them for:
  • Installing dependencies
  • Setting up environment files
  • Building initial assets
  • Starting background services
Scripts run in the default shell/terminal you configured in your settings. Write your commands using the syntax for that shell.
Creating worktrees by default doesn’t include any files in your .gitignore. If you have .env variables in your main branch and want them brought over to the worktree, add that to your setup script.

​
Examples

# Copy .env file
cp $TERMPAD_ROOT_PATH/.env .env && npm install

​
Run Scripts

Run scripts are manually triggered commands for common tasks. You can have multiple run scripts per project.

​
Creating run scripts

1

Open script settings

Navigate to the run scripts section.
2

Add a new script

Click Add Run Script.
3

Configure the script

Enter a name (e.g., “Dev Server”) and the command.

​
Common run scripts

NameCommandPurpose
Dev Servernpm run devStart development server
Testsnpm testRun test suite
Buildnpm run buildBuild for production
Lintnpm run lintCheck code style
Formatnpm run formatFormat code

​
Running a script

1

Select a worktree

Click on the worktree where you want to run the script.
2

Click Run

Click the Run button in the terminals section/panel at the bottom right.
3

Choose a script

Select which script to run from the dropdown.

​
Exclusive mode

Some scripts can’t run in multiple worktrees (e.g., dev servers that need a specific port). Enable exclusive mode for these scripts. When you run an exclusive script:
  1. Termpad checks if it’s running elsewhere
  2. If yes, it stops the other instance
  3. Then starts the script in your current worktree
Exclusive mode kills the script in other worktrees. Only use it when necessary.
Exclusive mode only detects scripts run using the Run Script feature. It won’t detect if you manually run the same command in your terminal.

​
Cleanup Scripts

Cleanup scripts run when you delete a worktree. When deleting a worktree, Termpad automatically removes the entire worktree directory. Cleanup scripts are useful for doing operations outside the working tree, for example removing build artifacts if applicable.

​
Example

# Remove build artifacts outside the worktree
rm -rf $TERMPAD_ROOT_PATH/.build-cache || true

​
Environment Variables

Scripts have access to Termpad-provided environment variables:
VariableDescription
TERMPAD_WORKSPACE_NAMEWorkspace name
TERMPAD_WORKSPACE_PATHWorkspace path
TERMPAD_ROOT_PATHRepository root directory path
TERMPAD_PORTUnique port for this worktree (100 ports available per repository)

​
Using environment variables

# In a run script
npm run dev --port $TERMPAD_PORT

​
Smart Port Management

Avoid port conflicts when running dev servers across worktrees:
1

Configure your scripts

Use $TERMPAD_PORT in your run scripts:
npm run dev --port $TERMPAD_PORT
2

Each worktree gets a unique port

Each worktree receives a unique port from a pool of 100 ports available per repository.

​
Script Tips

​
Chain commands

Run multiple commands in sequence: 
npm install && npm run build && npm test

​
Handle failures gracefully

Use || true to prevent script failure from blocking: 
# Don't fail if there's nothing to clean
rm -rf dist || true

​
Keep scripts simple

If your script is complex, put it in a file: 
./scripts/setup.sh
Then reference that file in Termpad.

​
Test scripts manually first

Before adding a script to Termpad, test it in a terminal to make sure it works.