1337skills.com

Appearance

Starship - Cross-Shell Prompt Customizer ​

Starship is a minimal, blazing-fast, and infinitely customizable prompt for any shell. Written in Rust, it provides a modern approach to shell prompt customization with cross-platform compatibility and intelligent context awareness. Starship shows relevant information at a glance while maintaining exceptional performance and a clean, minimal aesthetic.

Installation ​

bash
# Install via shell script (Linux/macOS)
curl -sS https://starship.rs/install.sh | sh

# Update Starship (same command)
curl -sS https://starship.rs/install.sh | sh

Package Managers ​

macOS ​

bash
# Homebrew
brew install starship

# MacPorts
sudo port install starship

Linux ​

bash
# Arch Linux
sudo pacman -S starship

# Debian/Ubuntu (via .deb package)
curl -sS https://starship.rs/install.sh | sh

# Fedora
sudo dnf install starship

# Gentoo
emerge app-shells/starship

# Nix
nix-env -iA nixpkgs.starship

Windows ​

powershell
# Winget
winget install starship

# Chocolatey
choco install starship

# Scoop
scoop install starship

Manual Installation ​

bash
# Download binary directly
wget https://github.com/starship/starship/releases/latest/download/starship-x86_64-unknown-linux-gnu.tar.gz
tar -xzf starship-x86_64-unknown-linux-gnu.tar.gz
sudo mv starship /usr/local/bin/

Shell Integration ​

Bash ​

bash
# Add to ~/.bashrc
eval "$(starship init bash)"

# Reload configuration
source ~/.bashrc

Zsh ​

bash
# Add to ~/.zshrc
eval "$(starship init zsh)"

# Reload configuration
source ~/.zshrc

Fish ​

bash
# Add to ~/.config/fish/config.fish
starship init fish | source

# Reload configuration
source ~/.config/fish/config.fish

PowerShell ​

powershell
# Add to PowerShell profile
# Check profile location: $PROFILE
Invoke-Expression (&starship init powershell)

# Reload profile
. $PROFILE

Other Shells ​

bash
# Ion shell (~/.config/ion/initrc)
eval $(starship init ion)

# Elvish (~/.elvish/rc.elv)
eval (starship init elvish)

# Tcsh (~/.tcshrc)
eval `starship init tcsh`

# Nushell
mkdir ($nu.data-dir | path join "vendor/autoload")
starship init nu | save -f ($nu.data-dir | path join "vendor/autoload/starship.nu")

# Xonsh (~/.xonshrc)
execx($(starship init xonsh))
lua
-- Create starship.lua in Clink scripts directory
load(io.popen('starship init cmd'):read("*a"))()

Configuration ​

Configuration File Setup ​

bash
# Create configuration directory
mkdir -p ~/.config

# Create configuration file
touch ~/.config/starship.toml

# Alternative: Use custom location
export STARSHIP_CONFIG=~/my-starship-config.toml

Basic Configuration Structure ​

toml
# ~/.config/starship.toml

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

# Inserts a blank line between shell prompts
add_newline = true

# Replace the '❯' symbol in the prompt with '➜'
[character]
success_symbol = '[➜](bold green)'
error_symbol = '[➜](bold red)'

# Disable the package module, hiding it from the prompt completely
[package]
disabled = true

Environment Variables ​

bash
# Custom config location
export STARSHIP_CONFIG=~/.config/my-starship.toml

# Custom cache directory
export STARSHIP_CACHE=~/.starship/cache

# Session logging
export STARSHIP_SESSION_KEY="$(date +%s)"

Core Modules Configuration ​

Character Module ​

toml
[character]
success_symbol = '[❯](bold green)'
error_symbol = '[❯](bold red)'
vimcmd_symbol = '[❮](bold green)'
vimcmd_replace_one_symbol = '[❮](bold purple)'
vimcmd_replace_symbol = '[❮](bold purple)'
vimcmd_visual_symbol = '[❮](bold yellow)'

Directory Module ​

toml
[directory]
truncation_length = 3
truncation_symbol = '…/'
home_symbol = '~'
read_only = ' 🔒'
style = 'bold cyan'
truncate_to_repo = true
format = '[$path]($style)[$read_only]($read_only_style) '

[directory.substitutions]
'Documents' = '📄 '
'Downloads' = '📥 '
'Music' = '🎵 '
'Pictures' = '📷 '
'Developer' = '💻 '

Git Integration ​

toml
[git_branch]
symbol = '🌱 '
truncation_length = 20
truncation_symbol = '…'
style = 'bold purple'

[git_status]
format = '([\[$all_status$ahead_behind\]]($style) )'
style = 'cyan'
conflicted = '🏳'
up_to_date = '✓'
untracked = '🤷'
ahead = '⇡${count}'
diverged = '⇕⇡${ahead_count}⇣${behind_count}'
behind = '⇣${count}'
stashed = '📦'
modified = '📝'
staged = '[++\($count\)](green)'
renamed = '👅'
deleted = '🗑'

Language Detection ​

toml
[nodejs]
format = 'via [🤖 $version](bold green) '
detect_extensions = ['js', 'mjs', 'cjs', 'ts']
detect_files = ['package.json', '.node-version']
detect_folders = ['node_modules']

[python]
symbol = '🐍 '
pyenv_version_name = true
format = 'via [${symbol}${pyenv_prefix}(${version} )(\($virtualenv\) )]($style)'
style = 'yellow bold'
pyenv_prefix = 'pyenv '
python_binary = ['./venv/bin/python', 'python', 'python3', 'python2']

[rust]
format = 'via [⚙️ $version](red bold)'
symbol = '⚙️ '

[golang]
format = 'via [🏎💨 $version](bold cyan) '
symbol = '🏎💨 '

System Information ​

toml
[hostname]
ssh_only = false
format = '[$hostname](bold red) '
trim_at = '.companyname.com'
disabled = false

[username]
style_user = 'white bold'
style_root = 'black bold'
format = '[$user]($style) '
disabled = false
show_always = true

[time]
disabled = false
format = '🕙[\[ $time \]](bold yellow) '
time_format = '%T'
utc_time_offset = '-5'
time_range = '10:00:00-14:00:00'

Command Execution ​

toml
[cmd_duration]
min_time = 2_000
format = 'underwent [$duration](bold yellow)'
disabled = false
show_milliseconds = false
show_notifications = false
min_time_to_notify = 45_000

[jobs]
symbol = '+ '
number_threshold = 1
symbol_threshold = 1
format = '[$symbol$number]($style) '
style = 'bold blue'

Advanced Configuration ​

Custom Commands ​

toml
[custom.git_server]
command = 'git config --get remote.origin.url | sed "s/.*@\(.*\):.*/\1/"'
when = 'git rev-parse --is-inside-work-tree'
format = 'on [$output]($style) '
style = 'bold blue'
shell = ['bash', '--noprofile', '--norc']
description = 'Display git server name'

[custom.docker]
command = 'docker version --format "{{.Server.Version}}"'
when = 'docker info'
format = 'via [🐳 $output](blue bold)'
shell = ['bash', '--noprofile', '--norc']

Conditional Formatting ​

toml
[aws]
format = 'on [$symbol($profile )(\($region\) )(\[$duration\] )]($style)'
symbol = '☁️  '
style = 'bold yellow'
disabled = false

[aws.region_aliases]
ap-southeast-2 = 'au'
us-east-1 = 'va'
us-west-2 = 'or'

[kubernetes]
format = 'on [⛵ ($user on )($cluster in )$context \($namespace\)](dimmed green) '
disabled = false

[kubernetes.context_aliases]
'dev.local.cluster.k8s' = 'dev'
'.*/openshift-cluster/.*' = 'openshift'
'gke_.*_(?P<var_cluster>[\w-]+)' = 'gke-$var_cluster'

Right Prompt ​

toml
# Enable right prompt
right_format = '$all'

# Configure modules for right side
[battery]
full_symbol = '🔋 '
charging_symbol = '⚡️ '
discharging_symbol = '💀 '
format = '[$symbol$percentage]($style) '

[[battery.display]]
threshold = 10
style = 'bold red'

[[battery.display]]
threshold = 30
style = 'bold yellow'

[memory_usage]
disabled = false
threshold = -1
symbol = '🐏 '
style = 'bold dimmed green'
format = 'via $symbol [${ram}( | ${swap})]($style) '

Themes and Presets ​

Apply Preset Themes ​

bash
# List available presets
starship preset --list

# Apply a preset
starship preset bracketed-segments -o ~/.config/starship.toml
starship preset nerd-font-symbols -o ~/.config/starship.toml
starship preset no-runtime-versions -o ~/.config/starship.toml
starship preset plain-text-symbols -o ~/.config/starship.toml
starship preset pure-preset -o ~/.config/starship.toml

Custom Color Schemes ​

toml
# Define custom palette
[palettes.catppuccin_mocha]
rosewater = "#f5e0dc"
flamingo = "#f2cdcd"
pink = "#f5c2e7"
mauve = "#cba6f7"
red = "#f38ba8"
maroon = "#eba0ac"
peach = "#fab387"
yellow = "#f9e2af"
green = "#a6e3a1"
teal = "#94e2d5"
sky = "#89dceb"
sapphire = "#74c7ec"
blue = "#89b4fa"
lavender = "#b4befe"
text = "#cdd6f4"
subtext1 = "#bac2de"
subtext0 = "#a6adc8"
overlay2 = "#9399b2"
overlay1 = "#7f849c"
overlay0 = "#6c7086"
surface2 = "#585b70"
surface1 = "#45475a"
surface0 = "#313244"
base = "#1e1e2e"
mantle = "#181825"
crust = "#11111b"

# Use the palette
palette = "catppuccin_mocha"

[directory]
style = "blue"

Minimal Configuration ​

toml
# Minimal prompt configuration
format = """
$directory\
$git_branch\
$git_status\
$character"""

[directory]
style = "blue"

[character]
success_symbol = "[❯](purple)"
error_symbol = "[❯](red)"
vimcmd_symbol = "[❮](green)"

[git_branch]
format = "[$branch]($style)"
style = "bright-black"

[git_status]
format = "[[(*$conflicted$untracked$modified$staged$renamed$deleted)](218) ($ahead_behind$stashed)]($style)"
style = "cyan"
conflicted = "​"
untracked = "​"
modified = "​"
staged = "​"
renamed = "​"
deleted = "​"
stashed = "≡"

Performance Optimization ​

Timeout Configuration ​

toml
# Global command timeout (milliseconds)
command_timeout = 500

# Module-specific timeouts
[cmd_duration]
min_time = 2_000

[custom.slow_command]
command = 'sleep 1 && echo "done"'
when = 'true'
timeout = 100  # milliseconds

Disable Heavy Modules ​

toml
# Disable resource-intensive modules
[package]
disabled = true

[docker_context]
disabled = true

[kubernetes]
disabled = true

# Enable only essential modules
[git_branch]
disabled = false

[git_status]
disabled = false

[directory]
disabled = false

[character]
disabled = false

Async Configuration ​

toml
# Enable async rendering for better performance
[git_status]
ahead = "⇡${count}"
diverged = "⇕⇡${ahead_count}⇣${behind_count}"
behind = "⇣${count}"

Troubleshooting ​

Debug Mode ​

bash
# Enable debug logging
export STARSHIP_LOG=debug
starship init bash

# View logs
tail -f ~/.cache/starship/session_${STARSHIP_SESSION_KEY}.log

# Test configuration
starship config

Configuration Validation ​

bash
# Test configuration syntax
starship config

# Print current configuration
starship print-config

# Explain configuration
starship explain

Common Issues ​

bash
# Font issues - install Nerd Font
# Download from: https://www.nerdfonts.com/
# Install and configure terminal to use Nerd Font

# Performance issues - check module timeouts
starship timings

# Module not showing - check detection settings
starship module [module_name]

# Reset configuration
mv ~/.config/starship.toml ~/.config/starship.toml.backup
starship config

Shell-Specific Issues ​

bash
# Bash: Ensure proper initialization
echo 'eval "$(starship init bash)"' >> ~/.bashrc

# Zsh: Check for conflicts with other prompt tools
# Disable oh-my-zsh themes if using starship
# ZSH_THEME="" in ~/.zshrc

# Fish: Ensure proper function loading
starship init fish | source

# PowerShell: Check execution policy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Integration Examples ​

Git Workflow Integration ​

toml
[git_branch]
format = "on [$symbol$branch(:$remote_branch)]($style) "
symbol = "🌱 "
style = "bold purple"
truncation_length = 20
truncation_symbol = "…"
only_attached = false
always_show_remote = false
ignore_branches = ["master", "main"]

[git_commit]
commit_hash_length = 7
format = '[\($hash$tag\)]($style) '
style = "green bold"
only_detached = true
disabled = false
tag_symbol = " 🏷  "
tag_disabled = false

[git_state]
format = '\([$state( $progress_current/$progress_total)]($style)\) '
style = "bright-black"
cherry_pick = "[🍒 PICKING](bold red)"
bisect = "[📊 BISECTING](bold yellow)"
am = "[📥 APPLYING](bold yellow)"
am_or_rebase = "[📥 APPLYING](bold yellow)"
style = "90"
disabled = false

[git_metrics]
added_style = "bold blue"
deleted_style = "bold red"
only_nonzero_diffs = true
format = '([+$added]($added_style) )([-$deleted]($deleted_style) )'
disabled = false

Development Environment Detection ​

toml
[python]
symbol = "🐍 "
pyenv_version_name = true
format = 'via [${symbol}${pyenv_prefix}(${version} )(\($virtualenv\) )]($style)'
style = "yellow bold"
pyenv_prefix = "pyenv "
python_binary = ["./venv/bin/python", "python", "python3", "python2"]
detect_extensions = ["py"]
detect_files = [".python-version", "Pipfile", "__init__.py", "pyproject.toml", "requirements.txt", "setup.py", "tox.ini"]
detect_folders = []
disabled = false

[nodejs]
format = "via [🤖 $version](bold green) "
version_format = "v${raw}"
symbol = " "
style = "bold green"
disabled = false
not_capable_style = "bold red"
detect_extensions = ["js", "mjs", "cjs", "ts", "tsx"]
detect_files = ["package.json", ".node-version", ".nvmrc"]
detect_folders = ["node_modules"]

[docker_context]
symbol = "🐳 "
style = "blue bold"
format = "via [$symbol$context]($style) "
only_with_files = true
detect_extensions = []
detect_files = ["docker-compose.yml", "docker-compose.yaml", "Dockerfile"]
detect_folders = []
disabled = false

Cloud Platform Integration ​

toml
[aws]
format = 'on [$symbol($profile )(\($region\) )(\[$duration\] )]($style)'
symbol = "☁️  "
style = "bold yellow"
disabled = false
expiration_symbol = "X"
force_display = false

[aws.region_aliases]
ap-southeast-2 = "au"
us-east-1 = "va"
us-west-2 = "or"

[gcloud]
format = 'on [$symbol$account(@$domain)(\($region\))]($style) '
symbol = "☁️  "
style = "bold blue"
disabled = false

[gcloud.region_aliases]
us-central1 = "uc1"
asia-northeast1 = "an1"

[azure]
disabled = false
format = "on [$symbol($subscription)]($style) "
symbol = "ﴃ "
style = "blue bold"

Best Practices ​

Configuration Organization ​

toml
# Organize configuration by sections
# 1. Global settings
add_newline = true
command_timeout = 500

# 2. Core prompt elements
[character]
success_symbol = '[❯](bold green)'

[directory]
style = 'bold cyan'

# 3. Version control
[git_branch]
style = 'bold purple'

# 4. Language detection
[python]
symbol = '🐍 '

# 5. Cloud and containers
[aws]
symbol = '☁️  '

# 6. Custom modules
[custom.git_server]
command = 'git config --get remote.origin.url'

Performance Guidelines ​

toml
# Keep command timeouts reasonable
command_timeout = 500

# Disable unused modules
[package]
disabled = true

# Use efficient detection patterns
[nodejs]
detect_files = ["package.json"]  # Most specific first

# Limit truncation for better performance
[directory]
truncation_length = 3

[git_branch]
truncation_length = 20

Security Considerations ​

toml
# Avoid exposing sensitive information
[username]
show_always = false  # Don't always show username

[hostname]
ssh_only = true  # Only show hostname over SSH

# Be careful with custom commands
[custom.safe_command]
command = 'echo "safe"'  # Avoid commands that could expose secrets
when = 'test -f .safe'   # Use safe conditions

Starship represents the modern standard for shell prompt customization, offering unparalleled flexibility and performance across all major shells and operating systems. Its Rust-based architecture ensures fast startup times and reliable operation, while the TOML configuration format provides a clean, readable way to customize every aspect of your prompt. Whether you prefer a minimal setup or a feature-rich display with comprehensive system information, Starship adapts to your workflow while maintaining excellent performance.