Shared Config

Share your project’s Termpad scripts with teammates by adding a termpad.json file to the repository root. Everyone who opens the project in Termpad gets the same setup, run, and cleanup scripts automatically.

Quick Start

Create a termpad.json file in your repository root:

{
  "setupScript": "npm install",
  "runScripts": [
    { "name": "Dev Server", "command": "npm run dev" },
    { "name": "Tests", "command": "npm test" }
  ],
  "cleanupScript": null,
  "exclusiveMode": false
}

Commit it to your repo. When a teammate opens this project in Termpad for the first time, the scripts are applied automatically.

File Format

Field	Type	Description
`setupScript`	`string \| null`	Runs when creating a new worktree
`runScripts`	`array`	Scripts available via the Run button
`cleanupScript`	`string \| null`	Runs after deleting a worktree
`exclusiveMode`	`boolean`	Kill other instances of a script before running

Each entry in runScripts has:

Field	Type	Description
`name`	`string`	Display name shown in the Run dropdown
`command`	`string`	Shell command to execute

How It Works

Opening a project with termpad.json

Termpad never auto-applies the shared config. When a termpad.json is detected, a Sync from termpad.json button appears on the Scripts settings page with a notification badge indicating there are scripts available to apply. Click the button to review and apply the shared scripts.

Syncing updates

When termpad.json changes (e.g., after a git pull), Termpad detects the update and shows the notification badge again on the sync button.

Syncing overwrites all your local script changes with the contents of termpad.json.

Examples

Node.js project

{
  "setupScript": "cp $TERMPAD_ROOT_PATH/.env .env\nnpm install",
  "runScripts": [
    { "name": "Dev Server", "command": "npm run dev -- --port $TERMPAD_PORT" },
    { "name": "Tests", "command": "npm test" },
    { "name": "Lint", "command": "npm run lint" },
    { "name": "Build", "command": "npm run build" }
  ],
  "cleanupScript": null,
  "exclusiveMode": false
}

Python project

{
  "setupScript": "python -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt",
  "runScripts": [
    { "name": "Run Server", "command": "source .venv/bin/activate && python manage.py runserver $TERMPAD_PORT" },
    { "name": "Tests", "command": "source .venv/bin/activate && pytest" },
    { "name": "Migrations", "command": "source .venv/bin/activate && python manage.py migrate" }
  ],
  "cleanupScript": null,
  "exclusiveMode": false
}

Monorepo with Docker

{
  "setupScript": "npm install\ndocker-compose up -d postgres redis",
  "runScripts": [
    { "name": "API", "command": "npm run dev:api -- --port $TERMPAD_PORT" },
    { "name": "Web", "command": "npm run dev:web" },
    { "name": "Tests", "command": "npm test" }
  ],
  "cleanupScript": "docker-compose down",
  "exclusiveMode": true
}

Multiline Scripts

Use \n for multiline scripts in JSON:

{
  "setupScript": "npm install\ncp .env.example .env\nnpm run db:migrate"
}

Each line runs as a separate command in the terminal.

Environment Variables

All Termpad environment variables are available in termpad.json scripts:

Variable	Description
`$TERMPAD_WORKSPACE_NAME`	Workspace name
`$TERMPAD_WORKSPACE_PATH`	Workspace path
`$TERMPAD_ROOT_PATH`	Repository root directory path
`$TERMPAD_PORT`	Unique port for this worktree

Tips

Commit the file

Add termpad.json to version control so the whole team benefits. It’s a small JSON file with no secrets.

Keep secrets out

Don’t put API keys or passwords in termpad.json. Reference .env files instead:

{
  "setupScript": "cp $TERMPAD_ROOT_PATH/.env .env"
}

Use with port management

Combine $TERMPAD_PORT with exclusiveMode: false to let multiple worktrees run dev servers simultaneously on different ports.

Getting Started

Guides

Tips

Support

Quick Start

File Format

How It Works

Opening a project with termpad.json

Syncing updates

Examples

Node.js project

Python project

Monorepo with Docker

Multiline Scripts

Environment Variables

Tips

Commit the file

Keep secrets out

Use with port management

​Quick Start

​File Format

​How It Works

​Opening a project with termpad.json

​Syncing updates

​Examples

​Node.js project

​Python project

​Monorepo with Docker

​Multiline Scripts

​Environment Variables

​Tips

​Commit the file

​Keep secrets out

​Use with port management

Quick Start

File Format

How It Works

Opening a project with termpad.json

Syncing updates

Examples

Node.js project

Python project

Monorepo with Docker

Multiline Scripts

Environment Variables

Tips

Commit the file

Keep secrets out

Use with port management