oh-my-posh Documentation

File: README.md Copy Chapter

This repo was made with love using GitKraken.

Sponsors Copy Chapter

Want to become a sponsor?

Join the community Copy Chapter

What started as the offspring of oh-my-posh2 for PowerShell
resulted in a cross platform, highly customizable and extensible prompt theme engine. After 4 years of working
on oh-my-posh, a modern and more efficient tool was needed to suit my personal needs.

:heart: Support :heart: Copy Chapter

- Show your love with a t-shirt!

- One time support, or a recurring donation?

- No coffee, no code.

Features Copy Chapter

• Shell and platform agnostic
• Easily configurable
• The most configurable prompt utility
• Fast
• Secondary prompt
• Right prompt
• Transient prompt

Documentation Copy Chapter

Reviews Copy Chapter

• Repo review by TameWizard

Thanks Copy Chapter

• Chris Benti providing the first influence to start oh-my-posh
• Keith Dahlby for creating posh-git and making life more enjoyable
• Robby Russell for creating oh-my-zsh, without him this would probably not be here
• Janne Mareike Koschinski for providing information on how to get certain information
  using Go (and the amazing README)
• Starship for doing great things

File: website/api/data/README.md Copy Chapter

API Data Directory

This directory contains data files used by the Azure Functions API.

Schema File Copy Chapter

The schema.json file is automatically copied from themes/schema.json during the GitHub Actions
deployment workflow. This file is used by the MCP validator to validate oh-my-posh configurations.

The schema is embedded locally to:

• Improve performance (no external HTTP requests)
• Ensure reliability (no dependency on external services)
• Work offline/in isolated environments

File: website/api/mcp/README.md Copy Chapter

title: MCP Validator Function Copy Chapter

Overview Copy Chapter

This directory contains the Azure Function that implements the Model Context Protocol (MCP) server for
validating oh-my-posh configurations.

Endpoints Copy Chapter

• POST /api/mcp - MCP server endpoint that handles validation requests
• GET /api/mcp - Returns server information and available tools

Supported Tools Copy Chapter

validate_config Copy Section

Validate an oh-my-posh configuration.

• Supports JSON, YAML, and TOML formats
• Returns detailed validation errors with JSON paths

validate_segment Copy Section

Validate a segment snippet (individual prompt segment).

• Validates against the segment schema definition
• Useful for testing individual segments before adding them to a full configuration
• Supports JSON, YAML, and TOML formats

Usage Copy Chapter

As an MCP Server Copy Section

Configure your MCP client to connect to this server:

{
  "mcpServers": {
    "oh-my-posh-validator": {
      "url": "https://ohmyposh.dev/api/mcp",
      "transport": "http"
    }
  }
}

Direct HTTP Requests Copy Section

Get Server Info

curl https://ohmyposh.dev/api/mcp

List Available Tools

curl -X POST https://ohmyposh.dev/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

Validate a Configuration

curl -X POST https://ohmyposh.dev/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "validate_config",
      "arguments": {
        "content": "{\"$schema\":\"https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/
themes/schema.json\",\"blocks\":[]}",
        "format": "json"
      }
    },
    "id": 1
  }'

Validate a Segment Snippet

curl -X POST https://ohmyposh.dev/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "validate_segment",
      "arguments": {
        "content": "{\"type\":\"path\",\"style\":\"powerline\",\"foreground\":\"#ffffff\",\"background\":\"#61AFEF\",\"template\":\" {{ .Path }} \"}",
        "format": "json"
      }
    },
    "id": 2
  }'

Response Format Copy Chapter

The validation result includes:

• valid: Boolean indicating if the configuration is valid
• errors: Array of validation errors (if any)
• warnings: Array of warnings (best practices, deprecations)
• detectedFormat: The detected or specified format
• parsedConfig: The parsed configuration object (for debugging)

Example response:

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{
          \"valid\": true,
          \"errors\": [],
          \"warnings\": [
            {
              \"path\": \"$schema\",
              \"message\": \"Consider adding \\\"$schema\\\" property for better editor support.\",
              \"type\": \"recommendation\"
            }
          ],
          \"detectedFormat\": \"json\",
          \"parsedConfig\": {...}
        }"
      }
    ]
  },
  "id": 1
}

Development Copy Chapter

To test locally:

cd website/api
npm install
npm start

Then send requests to http://localhost:7071/api/mcp

Publishing to MCP Registry Copy Chapter

This server is published to the MCP Registry using GitHub Actions.

Publishing Copy Section

Publishing is triggered automatically when you push a version tag (same as oh-my-posh releases):

git tag v9.0.0
git push origin v9.0.0

The workflow will:

1. Extract version from the tag (e.g., v9.0.0 → 9.0.0)
2. Update server.json version to match
3. Validate the server.json file
4. Authenticate with the MCP Registry using GitHub OIDC
5. Publish the server to the registry

Note: The MCP server version will stay in sync with oh-my-posh versions automatically.

Files Copy Section

• server.json - MCP Registry server configuration
• server.schema.json - JSON schema for validation
• validate-server.js - Validation script
• .github/workflows/publish-mcp.yml - GitHub Actions workflow

Validating server.json Locally Copy Section

cd website/api
npm install
cd mcp
node validate-server.js

File: website/docs/advanced/mcp-server.mdx Copy Chapter

id: mcp-server title: MCP Server sidebar_label: MCP Server Copy Chapter

What is the Oh My Posh MCP Server? Copy Chapter

The Oh My Posh MCP (Model Context Protocol) Server is a validation service that allows you to validate your oh-my-posh
theme configurations against the official JSON schema. It supports JSON, YAML, and TOML formats and provides detailed
error reporting to help you create valid configurations.

Features Copy Chapter

• Multi-format Support: Validates JSON, YAML, and TOML configurations
• Detailed Error Reporting: Get precise validation errors with JSON paths
• Format Auto-detection: Automatically detects the format of your configuration
• Warnings & Recommendations: Receive best practice suggestions and deprecation warnings
• Standards-based: Uses the official oh-my-posh JSON schema
• Remote Access: No installation required - access via HTTPS

Usage Copy Chapter

With MCP Clients Copy Section

Configure your MCP-compatible client (like Claude Desktop, Cline, or other AI assistants) to use the validator:

{
  "mcpServers": {
    "oh-my-posh-validator": {
      "url": "https://ohmyposh.dev/api/mcp",
      "transport": "http"
    }
  }
}

Then ask your AI assistant to validate your oh-my-posh configuration.

Direct HTTP API Copy Section

You can also use the validator directly via HTTP requests.

Get Server Information

curl https://ohmyposh.dev/api/mcp

List Available Tools

curl -X POST https://ohmyposh.dev/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

Validate a Configuration

curl -X POST https://ohmyposh.dev/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "validate_config",
      "arguments": {
        "content": "{\"$schema\":\"https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json\",\"version\":4,\"blocks\":[]}",
        "format": "json"
      }
    },
    "id": 1
  }'

Tool Parameters Copy Chapter

validate_config Copy Section

Parameters:

Returns:

{
  "valid": true,
  "errors": [],
  "warnings": [
    {
      "path": "$schema",
      "message": "Consider adding \"$schema\" property for better editor support.",
      "type": "recommendation"
    }
  ],
  "detectedFormat": "json",
  "parsedConfig": { ... }
}

Response Fields Copy Chapter

Error Format Copy Chapter

Each error in the errors array contains:

Examples Copy Chapter

Valid Configuration Copy Section

{
  "$schema": "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json",
  "version": 4,
  "blocks": [
    {
      "type": "prompt",
      "alignment": "left",
      "segments": [
        {
          "type": "path",
          "style": "powerline",
          "background": "blue",
          "foreground": "white"
        }
      ]
    }
  ]
}

Invalid Configuration Example Copy Section

{
  "blocks": [
    {
      "type": "invalid-type"
    }
  ]
}

Validation Result:

{
  "valid": false,
  "errors": [
    {
      "path": "/blocks/0/type",
      "message": "Value must be one of: prompt, rprompt, line",
      "keyword": "enum"
    }
  ]
}

Integration Examples Copy Chapter

Claude Desktop Copy Section

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/config.json on macOS):

{
  "mcpServers": {
    "oh-my-posh-validator": {
      "url": "https://ohmyposh.dev/api/mcp",
      "transport": "http"
    }
  }
}

Then ask Claude: "Can you validate this oh-my-posh configuration for me?" and paste your config.

Cline (VS Code Extension) Copy Section

Configure Cline to use the MCP server, and it will automatically validate configurations when you're working on
oh-my-posh themes.

Supported Formats Copy Chapter

JSON Copy Section

{
  "$schema": "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json",
  "version": 4,
  "blocks": []
}

YAML Copy Section

$schema: https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json
version: 4
blocks: []

TOML Copy Section

version = 4
blocks = []

Privacy & Security Copy Chapter

• Your configuration content is not stored or logged
• All validation is done in-memory and discarded after processing
• The server only reads the official schema from the repository
• No authentication required - fully anonymous

Source Code Copy Chapter

The MCP server is open source and part of the oh-my-posh repository:

• MCP Server Function
• Validator Module

Troubleshooting Copy Chapter

Format Not Detected Correctly Copy Section

If auto-detection fails, explicitly specify the format:

{
  "arguments": {
    "content": "...",
    "format": "yaml"
  }
}

Parse Errors Copy Section

If you get parse errors, check that your configuration is valid JSON/YAML/TOML syntax before validating the schema.

Schema Errors Copy Section

The validator uses the latest schema from the main branch. If you're using an older oh-my-posh version, some newer
properties might not be recognized.

Contributing Copy Chapter

Found a bug or have a suggestion? Please open an issue on GitHub.

File: website/docs/configuration/block.mdx Copy Chapter

id: block title: Block sidebar_label: Block Copy Chapter

Let's take a closer look at what defines a block.

import Config from "@site/src/components/Config.js";

<Config
data={{
blocks: [
{
type: "prompt",
alignment: "left",
segments: [],
},
],
}}
/>

Settings Copy Chapter

Type Copy Section

Tells the engine what to do with the block. There are two options:

• prompt renders one or more segments
• rprompt renders one or more segments aligned to the right of the cursor. Only one rprompt block is permitted.
  Supported on bash (with ble.sh), zsh, PowerShell, cmd, nu and fish.

Newline Copy Section

Start the block on a new line - defaults to false. For pwsh and cmd this will not print a newline
that's defined on the first block when the prompt is on the first line (when using clear), or when the shell session
starts (1st prompt). To enable the same behavior for bash and zsh, set enable_cursor_positioning to true.
This can have the side effect of swallowing commands you type while the prompt loads, or while the current
command is still ongoing. This is a limitation of the shell and not Oh My Posh.

Alignment Copy Section

• left
• right

Tell the engine if the block should be left or right-aligned.

Filler Copy Section

When you want to join a right and left aligned block with a repeated set of characters, add the character(s)
to be repeated to this property. Add this property to the right aligned block. This supports the use of
color overrides.

<Config
data={{
blocks: [
{
alignment: "right",
filler: ".",
},
],
}}
/>

Filler allows you to specify a template to tweak the text used as filler. This template behaves the same as
Segment templates, however, fewer properties are available.

This can be very useful if you wish to use a filler text when there is no overflow and use
empty space when the right block is hidden or drawn on a newline due to overflow.

<Config
data={{
blocks: [
{
alignment: "right",
overflow: "hide",
filler: "{{ if .Overflow }} {{ else }}-{{ end }}",
},
],
}}
/>

Overflow Copy Section

• break
• hide

When the right aligned block is so long it will overflow the left aligned block, the engine will either
break the block or hide it based on the setting. By default it is printed as is on the same line.

Leading Diamond Copy Section

The character to use as a leading diamond for the first segment in case you always want to start the block
with the same leading diamond, regardless of which segment is enabled or not.

Trailing Diamond Copy Section

The character to use as a trailing diamond for the last segment in case you always want to end the block
with the same trailing diamond, regardless of which segment is enabled or not.

Segments Copy Section

Array of one or more segments.

Force Copy Section

When set to true, the block will always be rendered, even if all segments are empty. Defaults to false.

Restart Cycle Copy Section

When a color cycle is defined, its colors are shared across every block in the prompt and keep
rotating from one block to the next. Set restart_cycle to true to make a block start the cycle over from
its first color instead of continuing where the previous block left off. Defaults to false.

This is useful for a two-line prompt where you always want the second line to begin with the cycle's first
color, regardless of how many segments the first line rendered.

<Config
data={{
blocks: [
{
type: "prompt",
alignment: "left",
segments: [],
},
{
type: "prompt",
alignment: "left",
newline: true,
restart_cycle: true,
segments: [],
},
],
}}
/>

Index Copy Section

The index of the block in the configuration. This is used to override a specific block in a base configuration.
This is a 1-based index, so the first block has an index of 1.

File: website/docs/configuration/colors.mdx Copy Chapter

id: colors title: Colors sidebar_label: Colors Copy Chapter

import Config from "@site/src/components/Config.js";

Standard colors Copy Chapter

Oh My Posh supports multiple different color references, being:

• True color using hex colors (for example #CB4B16).

• 16 ANSI color names.
  These include 8 basic ANSI colors and default

  black red green yellow blue magenta cyan white default

  as well as 8 extended ANSI colors:

  darkGray lightRed lightGreen lightYellow lightBlue lightMagenta lightCyan lightWhite

• 256 color palette using their number representation.
  For example 0 is black, 1 is red, 2 is green, etc.

• The transparent keyword which can be used to create either a transparent foreground override
  or transparent background color using the segment's foreground property.

• The foreground keyword which can be used to reference the current segment's foreground color.

• The background keyword which can be used to reference the current segment's background color.

• The parentForeground keyword which can be used to inherit the previous active segment's foreground color.

• The parentBackground keyword which can be used to inherit the previous active segment's background color.

• The accent keyword which references the OS accent color (Windows and macOS only).

Gradients Copy Chapter

Anywhere a Standard color is expected, you can instead use a linear-gradient with two or
more comma-separated stops:

<Config
data={{
type: "text",
style: "plain",
foreground: "linear-gradient(#FF0000, #0000FF)",
}}
/>

The stops are spread evenly across the segment's visible text and interpolated per character cell.
Each stop can be a hex color or a Palette reference (p:name), so gradients work with
palette and palettes the same way Standard colors do. This applies to foreground,
background, foreground_templates, background_templates, Palette entries, and cycle colors.

Powerline separators, diamond caps, and the parentBackground/parentForeground keywords
automatically pick up the matching edge of the gradient, so a segment next to a gradient still
connects with the right color.

Auto-shade from a single color Copy Section

dark-gradient(#3465A4) and light-gradient(#3465A4) take a single color and run from that
exact color to a darker or lighter shade of it, letting one configured color produce a gradient
effect on a segment too narrow for a real two-stop gradient to render as anything but a solid
color, see Stops and segment width.

<Config
data={{
type: "text",
style: "plain",
background: "dark-gradient(#3465A4)",
}}
/>

The first cell always renders the exact configured color; the last renders the shade. Everything
in between interpolates the same way a two-stop gradient does, so a wide segment shows a gentler
ramp and a narrow one a coarser one. A single-cell segment renders the configured color unmodified.
Each takes exactly one color; dark-gradient/light-gradient with more than one stop is invalid,
same as a linear-gradient with fewer than two.

Supported stops Copy Section

A stop must resolve to a hex color before it can be interpolated:

Keyword stops resolve against the surrounding segments at render time and must land on a hex
color; when the previous segment uses a gradient itself, parentBackground picks up its last
stop, so linear-gradient(parentBackground, p:yellow) connects seamlessly to it. On platforms
where the OS accent color is unavailable, an accent stop is invalid and the gradient falls
back like any other invalid stop.

A background or foreground keyword in a color override inside a gradient
segment resolves to the gradient's color at that position in the text: a leading
`` cap picks up the first stop, a trailing one the color where the
gradient ends, so template caps stay seamless without hardcoding edge colors.

A linear-gradient that resolves to fewer than two supported colors — including a linear-gradient
written with only one stop — renders as a solid color: the last stop goes through the regular color
pipeline, so linear-gradient(red, blue) renders solid blue rather than failing, and
linear-gradient(#3465A4) renders solid #3465A4 rather than shading — matching the color its
separators and width-collapsed form already use. Rejected stops are reported in oh-my-posh debug
output. Use dark-gradient/light-gradient for a one-color
gradient effect instead.

Stops and segment width Copy Section

The gradient always starts and ends exactly on the configured colors: the first stop lands on the
first visible cell, the last stop on the last. Everything in between is interpolated, so a narrow
segment simply shows a coarser gradient. A gradient needs at least two visible cells per stop to
render per cell; narrower segments render the last stop as a solid color across the whole segment,
including its caps and separators, rather than a coarse blend. Streaming placeholders are
exempt: a pending segment's ... placeholder previews the gradient per cell regardless of its
width. Rendering cost is negligible; the
only overhead is the per-cell color escape, which grows the prompt string by a few bytes per
character.

:::caution

• Gradients aren't supported on segments with interactive: true; shell-expanded text throws off
  the cell count the gradient interpolates across.
• A gradient can't span multiple segments; each segment's gradient is self-contained.
• Only the stop-list syntax is supported. Angle or direction keywords (for example to right) are
  reserved but not implemented.
• Terminals without truecolor support fall back to a banded 256-color approximation.

:::

Shades Copy Chapter

Anywhere a Standard color is expected, you can instead use darken(color, percent) or
lighten(color, percent) to shift a single color's lightness toward black or white:

<Config
data={{
type: "text",
style: "plain",
foreground: "#3465A4",
background: "darken(#3465A4, 20)",
}}
/>

percent runs from 0 to 100 and sets how far to travel toward black or white. 0 leaves the
color unchanged, 100 reaches near-black or near-white. The shift happens in the same HCL color
space dark-gradient and light-gradient use, which holds the hue exact instead of muddying it.

The color argument must resolve to a hex color, either a literal value (darken(#3465A4, 20)) or a
Palette reference to one (darken(p:accent, 20)). ANSI color names (green,
lightBlue), 256 color palette numbers and keywords such as foreground and accent render no
color. Run oh-my-posh debug to see the reason.

Those names carry no fixed RGB value. Your terminal's color scheme decides what green looks like,
and Oh My Posh cannot ask the terminal for that value fast enough to do it on every render. To shade
one of them, write its hex value into your Palette once and shade the palette entry:

<Config
data={{
palette: {
accent: "#3465A4",
},
type: "text",
style: "plain",
foreground: "p:accent",
background: "darken(p:accent, 20)",
}}
/>

A darken or lighten call takes a color, nothing more. You cannot nest one inside another, place
one inside a linear-gradient, dark-gradient or light-gradient, or pass it gradient stops or
segment keywords such as parentBackground.

Color templates Copy Chapter

Array of string templates to define the color based on the current context.
Under the hood this uses go's text/template feature extended with sprig and
offers a few standard properties to work with. For segments, you can look at the Template Properties
section in the documentation. The general template properties are listed here.

The following sample is based on the AWS Segment.

<Config
data={{
type: "aws",
style: "powerline",
powerline_symbol: "\uE0B0",
foreground: "#ffffff",
background: "#111111",
foreground_templates: [
'{{if contains "default" .Profile}}#FFA400{{end}}',
'{{if contains "jan" .Profile}}#f1184c{{end}}',
],
}}
/>

The logic is as follows: when foreground_templates contains an array, we will check every template line until there's
one that returns a non-empty string. So, when the contents of .Profile contain the word default, the first template
returns #FFA400 and that's the color that will be used. If it contains jan, it returns #f1184c. When none of the
templates returns a value, the foreground value #ffffff is used as a fallback value.

Color overrides Copy Chapter

You have the ability to override the foreground and/or background color for text in any property that accepts it.
The syntax is custom but should be rather straight-forward: <foreground,background>text</>. For example,
<#ffffff,#000000>this is white with black background</> <#FF479C>but this is pink</>.
Anything between the color start <#FF479C> and end </> will be colored accordingly.

If you want to print a colored bracket that isn't the same as the segment's foreground, you can
do so like this:

<Config
data={{
template: "<#CB4B16>┏[</>",
}}
/>

If you also wanted to change the background color in the previous command, you would do so like this:

<Config
data={{
template: "<#CB4B16,#FFFFFF>┏[</>",
}}
/>

To change only the background color, just omit the first color from the above string:

<Config
data={{
template: "<,#FFFFFF>┏[</>",
}}
/>

Palette Copy Chapter

If your configuration defined the Palette, you can use the Palette reference p: in places where the
Standard color is expected.

Defining a Palette Copy Section

Palette is a set of named Standard colors. To use a Palette, define a "palette" object
at the top level of your configuration:

<Config
data={{
palette: {
"git-foreground": "#193549",
git: "#FFFB38",
"git-modified": "#FF9248",
"git-diverged": "#FF4500",
"git-ahead": "#B388FF",
"git-behind": "#B388FF",
red: "#FF0000",
green: "#00FF00",
blue: "#0000FF",
white: "#FFFFFF",
black: "#111111",
},
}}
/>

Color names (palette keys) can have any string value, so be creative.
Color values, on the other hand, should adhere to the Standard color format, including transparent.

Alternatively, a palette value can be a template that resolves to any valid color value, including
a Palette reference. The template is rendered every time the color is resolved, so it can use any of the
global template properties to switch colors based on context. For example, to use a
different color when a Git segment is active in the prompt:

<Config
data={{
palette: {
"separator-git": '{{ if .Segments.Contains "Git" }}p:bg0{{ else }}p:green{{ end }}',
},
}}
/>

Using a Palette Copy Section

You can now use Palette references in any Segment's foreground, foreground_templates,
background, background_templates properties, and other config properties that expect Standard color value.
Palette reference format is p:. Take a look at the Git segment using Palette references:

<Config
data={{
type: "git",
style: "powerline",
powerline_symbol: "\uE0B0",
foreground: "p:git-foreground",
background: "p:git",
background_templates: [
"{{ if or (.Working.Changed) (.Staging.Changed) }}p:git-modified{{ end }}",
"{{ if and (gt .Ahead 0) (gt .Behind 0) }}p:git-diverged{{ end }}",
"{{ if gt .Ahead 0 }}p:git-ahead{{ end }}",
"{{ if gt .Behind 0 }}p:git-behind{{ end }}",
],
}}
/>

Having all of the colors defined in one place allows you to import existing color configurations (usually with slight
tweaking to adhere to the format), easily change colors of multiple segments at once, and have a more
organized configuration overall. Be creative!

_Palette references_ and **Standard colors** Copy Section

Using Palette does not interfere with using Standard colors in your configuration. You can still use Standard colors
everywhere. This can be useful if you want to use a specific color for a single segment element, or in a
Color override (Battery segment):

<Config
data={{
type: "battery",
style: "powerline",
invert_powerline: true,
powerline_symbol: "\uE0B2",
foreground: "p:white",
background: "p:black",
options: {
discharging_icon: "<#ffa500>-</> ",
charging_icon: "+ ",
charged_icon: "* ",
},
}}
/>

Handling of invalid references Copy Section

Should you use an invalid Palette reference as a color (for example typo p:bleu instead of p:blue),
the Palette engine will use the Transparent keyword as a fallback value. So if you see your prompt segments
rendered with incorrect colors, and you are using a Palette, be sure to check the correctness of your references.

Recursive resolution Copy Section

Palette allows for recursive Palette reference resolution, up to 3 levels deep. You can use a Palette
reference as a color value in Palette. This allows you to define named colors, and use references to those
colors as Palette values. A template value that resolves to a Palette reference follows the same rules,
and the referenced value can itself be a template.
For example, p:foreground and p:background will be correctly set to "#CAF0F80" and "#023E8A":

<Config
data={{
palette: {
"light-blue": "#CAF0F8",
"dark-blue": "#023E8A",
foreground: "p:light-blue",
background: "p:dark-blue",
},
}}
/>

Palettes Copy Chapter

If you want to use a palette conditionally, for example for light or dark mode, you can define multiple
palettes and a template that resolves to the palette key. The template is evaluated at
runtime so your prompt can change at any time based on the outcome of the template.

Take the following configuration:

<Config
data={{
palettes: {
template: '{{ if eq .Shell "pwsh" }}latte{{ else }}frappe{{ end }}',
list: {
latte: {
black: "#262B44",
green: "#59C9A5",
orange: "#F07623",
red: "#e64553",
white: "#E0DEF4",
yellow: "#df8e1d",
blue: "#7287fd",
},
frappe: {
black: "#262B44",
green: "#59C9A5",
orange: "#F07623",
red: "#D81E5B",
white: "#E0DEF4",
yellow: "#F3AE35",
blue: "#4B95E9",
},
},
},
}}
/>

In this case, when the shell is pwsh, the latte palette will be used, otherwise it uses the frappe palette. If you want,
you could also add frappe as the default palette, given that one is used as a fallback when not match can be found based on what
the template resolves to. In case no match is available and no palette is defined, it will also fallback to transparent
for any palette color reference in templates/colors.

If you want to avoid color duplication, you can use palettes in combination with the palette property. This way you can define
a color once and reuse it in multiple palettes. For example:

<Config
data={{
palette: {
black: "#262B44",
green: "#59C9A5",
orange: "#F07623",
},
palettes: {
template: '{{ if eq .Shell "pwsh" }}latte{{ else }}frappe{{ end }}',
list: {
latte: {
red: "#e64553",
white: "#E0DEF4",
yellow: "#df8e1d",
blue: "#7287fd",
},
frappe: {
red: "#D81E5B",
white: "#E0DEF4",
yellow: "#F3AE35",
blue: "#4B95E9",
},
},
},
}}
/>

:::info
If a color is defined in both palette and palettes, the palettes' resolved color will take precedence.
:::

Cycle Copy Chapter

When you want to display the same sequence of colors (background and foreground) regardless of which segments are active, you can
make use of the cycle property. This property is a list of colors which are used one after the other in a continuous loop. A defined
cycle always gets precedence over everything else.

<Config
data={{
cycle: [
{
background: "p:blue",
foreground: "p:white",
},
{
background: "p:green",
foreground: "p:black",
},
{
background: "p:orange",
foreground: "p:white",
},
],
}}
/>

File: website/docs/configuration/debug-prompt.mdx Copy Chapter

id: debug-prompt title: Debug prompt sidebar_label: Debug prompt Copy Chapter

import Config from "@site/src/components/Config.js";

:::info
This feature only works in powershell for the time being.
:::

The debug prompt is displayed when you debug a script from the command line or Visual Studio Code.
The default is [DBG]: .

You can use go text/template templates extended with sprig to enrich the text.
Environment variables are available, just like the console_title_template functionality.

Configuration Copy Chapter

You need to extend or create a custom theme with your debug prompt override. For example:

<Config
data={{
debug_prompt: {
background: "transparent",
foreground: "#ffffff",
template: "Debugging ",
},
}}
/>

Options Copy Chapter

Template ([info][templates]) Copy Chapter

File: website/docs/configuration/general.mdx Copy Chapter

id: general title: General sidebar_label: General Copy Chapter

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

Oh My Posh renders your prompt based on the definition of blocks (like Lego) which contain one or more segments.
A really simple configuration could look like this. The default format is json, but we also support toml and yaml.
There's a schema available which is kept up-to-date and helps with autocomplete and validation of the configuration.

:::info
There are a few themes available which are basically predefined configurations. You can use these as they are, or as a
starting point to create your own configuration.
:::

<Tabs
defaultValue="json"
groupId="sample"
values={[
{ label: 'json', value: 'json', },
{ label: 'yaml', value: 'yaml', },
{ label: 'toml', value: 'toml', },
]
}>

{
  "$schema": "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json",
  "final_space": true,
  "version": 4,
  "blocks": [
    {
      "type": "prompt",
      "alignment": "left",
      "segments": [
        {
          "type": "path",
          "style": "powerline",
          "powerline_symbol": "\uE0B0",
          "foreground": "#ffffff",
          "background": "#61AFEF",
          "options": {
            "style": "folder"
          }
        }
      ]
    }
  ]
}

# yaml-language-server: $schema=https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json
final_space: true
version: 4
blocks:
  - type: prompt
    alignment: left
    segments:
      - type: path
        style: powerline
        powerline_symbol: ""
        foreground: "#ffffff"
        background: "#61AFEF"
        options:
          style: folder

"$schema" = "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json"
final_space = true
version = 4

[[blocks]]
type = "prompt"
alignment = "left"

  [[blocks.segments]]
  type = "path"
  style = "powerline"
  powerline_symbol = ""
  foreground = "#ffffff"
  background = "#61AFEF"

    [blocks.segments.options]
    style = "folder"

With this configuration, a single powerline segment is rendered that shows the name of the folder you're currently in.
To set this configuration in combination with an Oh My Posh executable, use the --config flag to
set a path to a file containing the above code. The --shell universal flag is used to print the prompt without
escape characters to see the prompt as it would be shown inside a prompt function for your shell.

:::caution
The command below will not persist the configuration for your shell but print the prompt in your terminal.
If you want to use your own configuration permanently, adjust the prompt configuration to use your custom
configuration.
:::

oh-my-posh print primary --config sample.json --shell uni

If all goes according to plan, you should see the prompt being printed out on the line below. In case you see a lot of
boxes with question marks, set up your terminal to use a supported font before continuing.

:::tip
The --config flag can accept either a local filepath or a remotely hosted config file.

For example, the following is a valid --config flag:
--config 'https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/jandedobbeleer.omp.json'
:::

Settings Copy Chapter

Maps Copy Section

import Config from "@site/src/components/Config.js";

<Config
data={{
maps: {
user_name: {
jan: "🚀",
root: "⚡"
},
host_name: {
laptop123: "work"
}
}
}}
/>

Terminal features Copy Section

Some escape sequences only work in terminals that support them. The terminal_features setting maps such a
feature to the terminal programs supporting it. Values are matched case-insensitively against the TERM_PROGRAM
environment variable (Windows Terminal is detected via WT_SESSION). Progress sequences are used by the
upgrade and font install commands.

<Config
data={{
terminal_features: {
progress: ["Windows Terminal", "ghostty"]
}
}}
/>

Extends Copy Section

The extends key allows you to extend an existing configuration. This is useful when you want to build upon a base configuration without
duplicating all the settings like a theme. The value should be a path to another configuration file, which can be either local or remote.

Replacing values is done by repeating the value in the new configuration. For example, if you want to change the accent_color in a base configuration,
you can do so by specifying the accent_color key in your new configuration. The new value will override the one in the base configuration.

To override segments and blocks, specify the block using the same type and alignment as the base configuration. You can then add or modify the segments
within that block. Segments are matched by their alias or type, so you can add new segments or modify existing ones without affecting the rest of the configuration.

For more advanced use cases, you can also specify the index of the block or segment you want to override. This allows you to override blocks or segments at
specific positions in the configuration. Be aware that the index is 1-based, so the first block or segment has an index of 1.

JSON Schema Validation Copy Section

As mentioned above, Oh My Posh configurations can utilize JSON Schema to validate their contents. Configurations should include a link to
the external schema document which prescribes the appropriate structure and contents for various elements. If
your code editor is configured to use JSON Schema, it will compare your configuration to the external document, and issue
warnings for discrepancies.

For example, given the following code:

...
"segments": [
  {
    "type": "an_invalid_entry",
    "template": "{{ if gt .Code 0 }}\uf134{{ end }}",
  }
]
...

Warnings will be raised for type, since an_invalid_entry is not in the list of acceptable values, as well as
for the entire segment item (enclosed in {}), since it lacks the required style key. Take advantage of these
warnings, and ignore them at your peril.

Accepted Formats Copy Section

Oh My Posh supports three file formats for configurations: json, yaml, and toml.

Various converters exist to convert between these, although they aren't perfect and will require manual
adjustment. Notably, the schema implementation for json is as follows:

{
  "$schema": "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json"
}

While for yaml:

# yaml-language-server: $schema=https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json

Converters won't catch this change, so you will need to adjust manually.

File: website/docs/configuration/introduction.mdx Copy Chapter

id: introduction title: Introduction sidebar_label: Introduction hide_table_of_contents: true Copy Chapter

import Config from "@site/src/components/Config.js";

Oh My Posh is a custom prompt engine for any shell that has the ability to adjust
the prompt string with a function or variable.

Concept Copy Chapter

Traditionally, prompt tools work with custom scripts per theme (just like Oh My Posh 2 did) or a lot
of CLI configuration switches to define what it looks like. With Oh My Posh, I wanted to start from a single
configuration file that could easily be shared anywhere, removing the need to really grasp what goes on underneath.

When you look at prompts like Agnoster or Paradox, you notice they usually consist of a few building
blocks which contain one or more segments that display some sort of information. The configuration of
Oh My Posh works exactly like that. Blocks are a combination of one or more segments.

The basic layout of the config file is as follows.

<Config
data={{
"blocks": []
}}
/>

A block has properties that indicate its position and the segments it will render.

<Config
data={{
"blocks": [
{
"segments": []
}
]
}}
/>

A segment renders a single context like showing the current folder, user information or git status
when relevant. It can be styled any way you want, resulting in visualizing the prompt you are looking for.

For your convenience, the existing themes from Oh My Posh have been added to version 4, so you
can get started even without having to understand the theming. So, let's no longer waste time on theory, have a look at
the installation guide to get started right away!