starship/starship

Profiles

A profile is an alternative format string activated by starship prompt --profile <name>. Profiles live in [profiles] in starship.toml (user profiles) and in default_profiles() inside the binary (internal profiles).

When you'd use one

Transient prompts — render a different (typically shorter) prompt for past commands. Most shells need a custom hook to repaint the previous prompt; you call starship prompt --profile transient from that hook.
Statusline integration — starship statusline claude-code activates Target::Profile("claude-code"), which uses the built-in claude-code profile.
Modal prompts — different prompts for SSH vs local, dev vs prod, etc., toggled by your shell.

Defining one

[profiles]
transient = "$character"
status = "$status"

[profiles] is a IndexMap<String, String> on StarshipRootConfig. Names are arbitrary; values are full format strings (same DSL as the main format).

Built-in profiles

default_profiles() returns:

IndexMap::from_iter([(
    "claude-code".to_string(),
    "$claude_model$git_branch$claude_context$claude_cost".to_string(),
)])

This is the only built-in profile today.

Resolution order

load_formatter_and_modules in src/print.rs looks up Target::Profile(name):

config.user_profiles.get(name).or_else(|| config.internal_profiles.get(name))

User profiles win. If neither has the name, the renderer logs an error and falls back to the literal > for that prompt.

Calling a profile from a shell

The shell's prompt hook needs to call starship prompt --profile <name> instead of starship prompt:

# Bash example: render a transient prompt before each command starts
function starship_transient_prompt() {
    PS1="$(starship prompt --profile transient)"
}
trap starship_transient_prompt DEBUG

The fish init script (src/init/starship.fish) has built-in transient prompt support: if TRANSIENT=1 is set or the user provides a starship_transient_prompt_func, fish renders --final-rendering mode using that profile.

Combining with the right prompt

Profiles only set the left (or "main") prompt. The right prompt always uses right_format regardless of --profile. This is intentional: a transient prompt typically wants to clear the right prompt entirely, which the renderer does because Target::Profile doesn't pick right_format.