Customizing MacOS Terminal with Starship Like a Pro

As terminal applications grow more powerful and complex, managing multiple CLIs and their different versions becomes increasingly challenging. Customizing your terminal can make a big difference, helping you handle several tools at once without getting lost in the clutter.

I previously relied on Oh My Zsh for prompt customization, but recently switched to Starship because it provides a simpler declarative approach to customization. So in this post, I will walk through how to build a clean starship prompt, including dynamic context for:

• AWS profiles
• Java (Gradle)
• Node.js

Getting Started

• Install Homebrew
• Install Iterm2

Step 1: Install Starship

brew install starship

Step 2: Integrate Starship with Zsh

Open .zshrc for edition:

nano ~/.zshrc

Add the following line to load starship on every zsh session:

eval "$(starship init zsh)"

Step 3 (Optional): Install Zsh Plugins

The following plugins are optional, but they enhance your terminal experience by highlighting commands in real time and providing suggestions based on your command history and current input:

brew install zsh-syntax-highlighting
brew install zsh-autosuggestions

Open .zshrc for edition:

nano ~/.zshrc

Add following lines to load plugins on every zsh session:

source $(brew --prefix)/share/zsh-autosuggestions/zsh-autosuggestions.zsh
source $(brew --prefix)/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh

Step 4: Install Nerd Fonts

To ensure terminal can correctly render icons and custom glyphs, you need to install a Nerd Font:

brew search font-fira-code-nerd-font
brew install --cask font-fira-code-nerd-font

Step 5: Setting Terminal Font

Update your terminal settings to use a Nerd Font:

Iterm2

Navigate to: Settings > Profiles > Default > General

Option	Value
Terminal Font	FiraCode Nerd Font

Visual Studio Code integrated terminal

Navigate to: Settings > User

Option	Value
terminal.integrated.fontFamily	FiraCode Nerd Font
editor.fontFamily	Menlo, Monaco, 'Courier New', monospace, 'FiraCode Nerd Font’

MacOS native terminal

Navigate to: Settings > Profiles > Text

Option	Value
Font	FiraCode Nerd Font

Step 6: Customize Starship Theme

Create and open the starship.toml configuration file to customize the Starship prompt.

mkdir -p ~/.config && nano ~/.config/starship.toml

Add the following lines:

# Get editor completions based on the config schema
"$schema" = 'https://starship.rs/config-schema.json'

# ~/.config/starship.toml
format = """
$directory$git_branch$git_status$fill$aws$nodejs$java$gradle
$os$character
"""

[fill]
symbol = ' '

[directory]
format = '[ $path ]($style)[$read_only]($read_only_style)'
style = 'bg:blue'
read_only_style = 'bg:red'
truncate_to_repo = true
truncation_length = 1

[git_branch]
format = '[ $symbol$branch ]($style)'
style = 'bg:green'

[git_status]
format = '[$all_status$ahead_behind](bg:green)'
conflicted = '[ = ](bg:yellow bold)'
ahead = '[ ⇡ ](bg:yellow bold)'
behind = '[ ⇣ ](bg:yellow bold)'
diverged = '[ ⇕ ](bg:yellow bold)'
up_to_date = ''
untracked = '[ ? ](bg:yellow bold)'
stashed = '[ \$ ](bg:yellow bold)'
modified = '[ ! ](bg:yellow bold)'
staged = '[ + ](bg:yellow bold)'
renamed = '[ » ](bg:yellow bold)'
deleted = '[ ✘ ](bg:yellow bold)'
typechanged = ""

[aws]
format = '[ $symbol $profile $region ]($style)'
symbol = ' '

[nodejs]
format = '[ $symbol $version ]($style)'
version_format = '${raw}' 

[java]
format = '[ $symbol:$version ]($style)'
version_format = '${raw}'
style = 'bg:red bold'
symbol = 'jdk'

[gradle]
format = '[ $symbol $version ]($style)'
version_format = '${raw}' 
symbol = ''

[os]
format = '[$symbol ]($style)'
disabled = false

[os.symbols]
Macos = '󰀵'

[character]
success_symbol = "[❯](bold default)"
error_symbol = '[✗](bold red) '

Last Step: Play With The New Prompt

AWS profiles

In the example below, after running export AWS_PROFILE=root, Starship reflects the currently active AWS account directly in the prompt:

• Starship displays the active AWS profile: root
• The terminal prompt also shows the active AWS region: us-east-1 (Virginia)

NodeJS projects

The following example shows how changing the Node.js version using NVM (nvm use) is reflected in Starship:

• Starship automatically updates the prompt to display the active Node.js version.
• Starship also shows useful Git repository information, such as the current branch and an icon indicating modified files.

Java and Gradle projects

In the following example, observe how Starship displays information about the current environment in a Java application directory:

• The active Java version currently in use.
• The active Gradle version.
• Additional contextual information, such as the active AWS profile and region, when those tools are enabled.

Enjoy it!