Prompt configuration¶

This page describes prompt-level options for Spaceship.

Terminology¶

The prompt consists of sections. All sections are combined into a prompt order.

When the prompt is being rendered, just goes over the prompt order and executes each section. If you want to add a custom section, add it to the order. You can add or remove sections from the prompt order at any time.

Typically, a section consist of a prefix, symbol, content and suffix. The symbol and the content are painted in color. Here's an example with a package section:

is 📦 3.16.5

Above, is is a prefix, 📦 is a symbol, 3.16.5 is the content and `` (a space) is the suffix.

Each part can be configured via corresponding options. Options are just environment variables and have this signature SPACESHIP_<SECTION>_<OPTION>:

# SPACESHIP_<SECTION>_<OPTION>
  SPACESHIP_PACKAGE_PREFIX="via·"
  SPACESHIP_PACKAGE_SUFFIX=" "
  SPACESHIP_PACKAGE_COLOR="green"

Above PACKAGE is a section and PREFIX, SUFFIX and COLOR are options for prefix, suffix and color correspondingly.

Info

Colors for sections can be basic colors or color codes.

Prompt order¶

The prompt order is the order in which sections are executed and rendered. You can specify the order of prompt section using SPACESHIP_PROMPT_ORDER option.

The default prompt order is:

SPACESHIP_PROMPT_ORDER=(
  time          # Time stamps section
  user          # Username section
  dir           # Current directory section
  host          # Hostname section
  git           # Git section (git_branch + git_status)
  hg            # Mercurial section (hg_branch  + hg_status)
  package       # Package version
  node          # Node.js section
  bun           # Bun section
  deno          # Deno section
  ruby          # Ruby section
  python        # Python section
  elm           # Elm section
  elixir        # Elixir section
  xcode         # Xcode section
  swift         # Swift section
  golang        # Go section
  php           # PHP section
  rust          # Rust section
  haskell       # Haskell Stack section
  java          # Java section
  lua           # Lua section
  dart          # Dart section
  julia         # Julia section
  crystal       # Crystal section
  docker        # Docker section
  aws           # Amazon Web Services section
  gcloud        # Google Cloud Platform section
  venv          # virtualenv section
  conda         # conda virtualenv section
  dotnet        # .NET section
  kubectl       # Kubectl context section
  terraform     # Terraform workspace section
  ibmcloud      # IBM Cloud section
  exec_time     # Execution time
  async         # Async jobs indicator
  line_sep      # Line break
  battery       # Battery level and status
  jobs          # Background jobs indicator
  exit_code     # Exit code section
  char          # Prompt character
)

You can add or remove sections using spaceship add and spaceship remove commands, like this:

# Removes git out of the prompt
spaceship remove git

# Adds git back to the prompt
spaceship add git

Right prompt order¶

You can also add items to the right prompt by specifying them in the SPACESHIP_RPROMPT_ORDER option. By default, SPACESHIP_RPROMPT_ORDER is an empty array.

Configuring sections¶

You can customize every section of the prompt with section's options. Check out each section's documentation for more information.

Besides built-in sections, you can add external section to your prompt or build a custom one.

Browse built-in sections Browse all sections

Prompt-level options¶

This group of options defines a behavior of prompt and standard parameters for sections displaying.

Variable	Default	Meaning
`SPACESHIP_PROMPT_ASYNC`	`true`	Render prompt asynchronously or not
`SPACESHIP_PROMPT_ADD_NEWLINE`	`true`	Adds a newline character before each prompt line
`SPACESHIP_PROMPT_SEPARATE_LINE`	`true`	Make the prompt span across two lines
`SPACESHIP_PROMPT_FIRST_PREFIX_SHOW`	`false`	Shows a prefix of the first section in prompt
`SPACESHIP_PROMPT_PREFIXES_SHOW`	`true`	Show prefixes before prompt sections or not
`SPACESHIP_PROMPT_SUFFIXES_SHOW`	`true`	Show suffixes before prompt sections or not
`SPACESHIP_PROMPT_DEFAULT_PREFIX`	`via·`	Default prefix for prompt sections
`SPACESHIP_PROMPT_DEFAULT_SUFFIX`	``	Default suffix for prompt section

Here is a breakdown of these options:

Asynchronous rendering¶

The SPACESHIP_PROMPT_ASYNC option defines whether the prompt is rendered asynchronously or not. By default, the prompt is rendered asynchronously.

The synchronous sections are displayed immediately. The asynchronous sections are processed in the background and are displayed when the information is ready to be displayed.

The async section is used as a placeholder for not yet available asynchronous sections.

Prompt spacing¶

Spaceship adds and empty line between each prompt. You can disable this behavior by setting SPACESHIP_PROMPT_ADD_NEWLINE to false.

The prompt is also separated by a line break if SPACESHIP_PROMPT_SEPARATE_LINE is set to true.

Displaying the first section prefix¶

Spaceship hides the prefix of the first section in the prompt. You can enable this behavior by setting SPACESHIP_PROMPT_FIRST_PREFIX_SHOW to true.

Displaying prefixes and suffixes¶

You can disable the displaying of prefixes and suffixes by setting SPACESHIP_PROMPT_PREFIXES_SHOW and SPACESHIP_PROMPT_SUFFIXES_SHOW to false.

Additionally, you can change the default prefix and suffix by setting SPACESHIP_PROMPT_DEFAULT_PREFIX and SPACESHIP_PROMPT_DEFAULT_SUFFIX. These options will be used to render prefixes or suffixes unless the corresponding section option is set.