Shell Integration

Quickstart#

Install shell integration: in the app, select the “Install shell integration…” menu item from the Indigo menu. More…

Open a new window in your Terminal app. Type indi and press tab once or twice to show the available autocompletions. More…

Enter one of the available options (eg indigo.set.My-Stack.default) and press enter. You’re done! Now, all the services in your chosen stack will be available to you on the command line.

For example, if PHP is in this Indigo stack, entering php -v on the command line will now run the very same version of PHP as your stack.

Delving deeper: understanding the problem#

Normally when you install a binary such as PHP, it’s accessible from the command line because it was installed into a special location, one which is in your system’s PATH.

If you type php on the command line, your shell (ZSH, by default on the Mac) will look at these paths in order, and use the first PHP binary it finds. For this reason, you can only access one PHP binary.

Indigo needs a different approach, since it allows you to specify a different version of PHP for each project. If you want to work with an Indigo stack on the command line, you’ll need a different way of telling your shell which php binary to use and when.

Indigo’s Shell Integration allows you to configure access to the services in any of your stacks from the command line.

About Terminal Presets#

Indigo allows you to define one or more Terminal Presets for each stack. A Terminal Preset specifies which of the stack’s services you would like to use on the command line.

Each stack comes with a default Terminal Preset, which simply includes the first service of each type in the stack. For example, if your stack defines two PHP services, the default will include only the first (the highest in the rack).

For many, the default terminal presets will be fine. If your stacks are complex, you may create as many additional Terminal Presets as you wish.

Installation#

Using Indigo’s UI#

Launch Indigo, then in the menubar, select Indigo > Install shell integration…

Indigo will back up your ~/.zshrc if you have one, before modifying it.

You will need to open a new terminal window for Indigo’s changes to take effect.

Manual installation#

Advanced users may prefer to implement the required changes to their zsh environment manually.

Open your ~/.zshrc file in a text editor (you will need to create this file if you don’t have it already.)

Append the following lines to the end of the file:

# Added for Indigo.app
source /Users/username/.indigo/.profile

Replace username with your macOS user name.

You will need to open a new terminal window for your changes to take effect.

Uninstallation#

Open your ~/.zshrc file in a text editor.

Remove the following lines from the end of the file:

# Added for Indigo.app
source /Users/username/.indigo/.profile

Usage#

Activating a Terminal Preset#

It takes just one step to activate a Terminal Preset on the command line: enter its alias name and hit enter.

An example:

Configuring your IDE#

If your IDE provides a built-in terminal, it’s useful to have it preconfigure your Indigo terminal preset automatically. This way your IDE’s terminal will always use the services associated with the project you are working on.

Option 1: Running an “init” shell command#

Your IDE may allow you to run a command when its terminal starts up. In this case, simply tell it to run the shell alias for your chosen stack.

The following example will configure your terminal to use the services in the stack “my stack”:

indigo.set.my-stack.default

Option 2: Configuring an environment variable#

Your IDE may allow you to configure environment variables for use in its terminal. Indigo provides a special environment variable, INDIGO_INIT_COMMAND. If this variable is set, Indigo will run its value as a command when the terminal session starts. This can be any shell command or script, but is a great way to run one of Indigo’s Terminal Preset aliases.

This is pretty easy in practice. For example, configure the following in your IDE:

INDIGO_INIT_COMMAND="echo hi"

…or more usefully:

INDIGO_INIT_COMMAND="indigo.set.my-stack.default"

An example: Visual Studio Code#

You can configure VS Code so that its terminal always uses the services in the stack for the current project.

Since VS Code doesn’t allow you to configure a terminal startup command (option one above), we will specify the Indigo environment variable instead (option two).

1. Open the VS Code preferences: Code > Preferences > Settings
2. Find the terminal environment setting: in the “search settings” field type terminal.env.osx
3. You’ll want to make this setting workspace-specific, so click the “workspace” tab (below the “search settings” field).
4. Click “Edit in settings.json”. VS Code will create an entry in your workspace settings.json for your custom environment variables.
5. Enter a command for Indigo to run each time your terminal launches inside this workspace. The following example will configure your VS Code terminal to use the services in the stack “my stack”:

"terminal.integrated.env.osx": {
    "INDIGO_INIT_COMMAND": "indigo.set.my-stack.default",
},