Run configs reference

The .cate/run-configs.json file defines named launch configurations for your project. Each configuration is a group of commands that launch together in parallel sub-tabs. See Set up run configs for a guide to creating these via the Cate interface.

Schema

{
  "configurations": [
    {
      "id": "unique-uuid",
      "name": "Configuration Name",
      "commands": [
        {
          "id": "unique-uuid",
          "name": "Tab Name",
          "command": "shell command"
        }
      ]
    }
  ]
}

Fields

RunConfigFile (top-level)

Field	Type	Description
configurations	array	List of run configurations

RunConfiguration

Field	Type	Description
id	string	Unique UUID. Use UUIDv7 if possible; UUIDv4 is acceptable. Must be lowercase.
name	string	Display name shown in the launcher dropdown
commands	array	List of commands to run in parallel

RunConfigCommand

Field	Type	Description
id	string	Unique UUID. Same format requirements as configuration id.
name	string	Display name shown as the sub-tab label
command	string	Shell command to execute. The shell handles pipes, environment variables, etc.

Constraints

• All id fields must be unique across the entire file.
• Every configuration must have at least one command.
• When editing an existing file, preserve existing IDs for configurations and commands you aren’t changing. This ensures stable identity across updates.

Examples

Single command

{
  "configurations": [
    {
      "id": "019e1a2b-3c4d-7000-8000-000000000001",
      "name": "Dev Server",
      "commands": [
        {
          "id": "019e1a2b-3c4d-7000-8000-000000000002",
          "name": "Server",
          "command": "npm run dev"
        }
      ]
    }
  ]
}

Launches one sub-tab running npm run dev.

Multi-command parallel

{
  "configurations": [
    {
      "id": "019e1a2b-3c4d-7000-8000-000000000010",
      "name": "Full Stack Dev",
      "commands": [
        {
          "id": "019e1a2b-3c4d-7000-8000-000000000011",
          "name": "Database",
          "command": "docker compose up"
        },
        {
          "id": "019e1a2b-3c4d-7000-8000-000000000012",
          "name": "API",
          "command": "./gradlew bootRun"
        },
        {
          "id": "019e1a2b-3c4d-7000-8000-000000000013",
          "name": "Frontend",
          "command": "npm run dev"
        }
      ]
    }
  ]
}

Launches three sub-tabs simultaneously. Each sub-tab label (“Database”, “API”, “Frontend”) appears in the tab bar.

Multiple configurations

{
  "configurations": [
    {
      "id": "019e1a2b-3c4d-7000-8000-000000000020",
      "name": "Development",
      "commands": [
        {
          "id": "019e1a2b-3c4d-7000-8000-000000000021",
          "name": "API",
          "command": "npm run dev:api"
        },
        {
          "id": "019e1a2b-3c4d-7000-8000-000000000022",
          "name": "Frontend",
          "command": "npm run dev:web"
        }
      ]
    },
    {
      "id": "019e1a2b-3c4d-7000-8000-000000000030",
      "name": "Staging",
      "commands": [
        {
          "id": "019e1a2b-3c4d-7000-8000-000000000031",
          "name": "API",
          "command": "npm run staging:api"
        },
        {
          "id": "019e1a2b-3c4d-7000-8000-000000000032",
          "name": "Frontend",
          "command": "npm run staging:web"
        }
      ]
    }
  ]
}

Two configurations appear as separate entries in the launcher dropdown. Select which environment to launch before clicking run.