Troupe Docs
Terminals

Open a terminal

Open a shell in your project, choose the default shell, and save terminal profiles.

A new terminal starts in the folder of the active project. If you work in a worktree, it starts in that worktree's folder instead.

Open a terminal from the tab bar

Click New tab (the + at the end of a pane's tab bar). The menu has:

  • New terminal opens a terminal with the default shell.
  • New terminal with lists the shells Troupe found. The default shell is marked Default. While Troupe looks for shells, the list shows Detecting shells…. If Troupe could not find them, select Could not detect shells. Try again.

The terminal opens as a new tab in that pane. The same menu also has New chat and, in the desktop app, New browser tab.

Open a terminal from the tool strip

Click New terminal at the bottom of the tool strip, on the right edge of the window. The terminal opens as a new tab in the active pane, with the default shell.

To pick another shell, right-click New terminal (or focus it and press Shift+F10). This opens the same New terminal with list.

Other ways to open a terminal

  • Press Ctrl+Shift+Alt+T (Cmd+Shift+Alt+T on macOS). In the keyboard shortcut list, this shortcut is called Open Terminal in Worktree. It also works when you are not in a worktree.
  • Open the command palette with Ctrl+K (Cmd+K on macOS) and run New Terminal.
  • In the Explorer, right-click a folder and select Open in Terminal. The terminal starts in that folder.
  • In the sidebar, right-click a chat and select Open terminal here. The terminal starts in the chat's folder.
  • Right-click the project in the sidebar and select Switch worktree…. Each folder in the list has a terminal button (Open terminal in folder).

Which shells you can pick

The New terminal with menu lists the shells that Troupe finds. In the desktop app, these are the shells on your computer. In a browser, they are the shells on the computer that runs the Troupe server.

PlatformShells Troupe looks for
WindowsPowerShell 7, PowerShell (Windows PowerShell), Command Prompt, WSL, Git Bash
macOS and LinuxBash, Zsh, Fish, Shell (sh)

On Windows, Command Prompt and WSL are always in the list, even if WSL is not installed.

On macOS and Linux, Troupe looks only in /bin and /usr/bin. A shell installed somewhere else, for example by Homebrew, is not in the menu. To use one, create a terminal profile and type the shell's path.

The menu marks the default shell Default.

Set the default shell

The default shell is the shell Troupe uses when you don't pick one, for example when you run New Terminal from the command palette. There is a default for all projects and a default for each project.

To set the default for all projects:

  1. Select Settings at the bottom of the sidebar, or press Ctrl+, (Cmd+, on macOS, Alt+, in a browser).
  2. Select Default Shell.
  3. Choose a shell from Shell. System Default uses your system's default shell.

The Default Shell section of Application Preferences, with the Shell drop-down set to System Default

To set the default for one project:

  1. Hover the project in the sidebar and select the gear icon (Project settings).
  2. Click Shell and choose a shell in the Shell list. App default uses the shell from Application Preferences.
  3. Select Save changes.

When you create a project, Advanced options in the new project dialog has a Default Terminal field. It sets the same per-project default. Troupe fills in this field for you, so every project you create there starts with its own default shell.

Troupe picks the shell for a new terminal in this order:

  1. The shell you select in the New terminal with menu.
  2. The project's default shell.
  3. The default shell in Settings.
  4. Your system's default shell.

Because projects you create in Troupe already have a default shell, the Settings default applies only to projects without one. To change the shell for an existing project, change it in Project settings.

Save a terminal profile

A terminal profile is a saved shell setup. It has a shell, its arguments, a start folder, and environment variables. Use a profile when you often open the same kind of terminal, such as a shell with NODE_ENV=development set.

  1. Open Settings and select Terminal Profiles.
  2. Select Add profile.
  3. Fill in the fields you need:
    • Name. The name of the profile and of the tabs it opens. This field is required.
    • Shell. Pick a shell from the list. To use another shell, pick Other path or name and type a shell name or path in Shell path or name, for example nu or C:\tools\nu.exe. Leave the field on Default shell to use the default shell.
    • Arguments. Type one argument per line. To add arguments, you must also choose a shell.
    • Start folder. Leave it empty to start in the active project or worktree folder. If you fill it in, type a full path.
    • Environment variables. Type one KEY=value per line. These variables override project environment variables that have the same name.
  4. Select Save.

The New terminal profile dialog with the name Node dev and the variable NODE_ENV=development

Troupe saves profile environment variables in plain text with your settings. Don't put passwords or tokens in them.

To change a profile, select its pencil icon. To remove it, select its trash icon. Troupe deletes the profile right away, without asking.

Open a terminal from a profile

  1. Open the command palette with Ctrl+K (Cmd+K on macOS).
  2. Type the profile name.
  3. Select New Terminal: profile name.

The terminal opens in the active pane, and the tab has the profile's name. Profiles are not in the New terminal with menu.

The command palette filtered to Node dev, with New Terminal: Node dev at the top

Terminal limits

A project can have 10 terminals open at once, and Troupe as a whole can have 30. Terminals that keep running in the background count toward both limits. When you reach a limit, Troupe shows a message such as "Terminal limit reached (10 per project, 30 total): this project is at its limit" and doesn't open the terminal. Close a terminal to open a new one.

To change the per-project limit, set the TROUPE_MAX_TERMINALS_PER_PROJECT environment variable (or the older TERMUL_MAX_TERMINALS_PER_PROJECT) to a number before you start Troupe. If you run Troupe as a server, you can also use the --max-terminals-per-project flag. The total limit of 30 doesn't change.

On this page