## File: README.md [![Release version number badge][release-badge]][release] [![Documentation link badge ohmyposh.dev][docs-badge]][docs] This repo was made with love using GitKraken. [![GitKraken shield][kraken]][kraken-ref] ## Sponsors J [Want to become a sponsor?][sponsor-link] ## Join the community What started as the offspring of [oh-my-posh2](https://github.com/JanDeDobbeleer/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: [![Swag][swag-badge]][swag] - Show your love with a t-shirt! [![GitHub][github-badge]][github-sponsors] - One time support, or a recurring donation? [![Ko-Fi][kofi-badge]][kofi] - No coffee, no code. ## Features * Shell and platform agnostic * Easily configurable * The __most__ configurable prompt utility * Fast * Secondary prompt * Right prompt * Transient prompt ## Documentation [![Documentation][docs-badge]][docs] ## Reviews * [Repo review](https://repo-reviews.github.io//reviews/2023-06-21_TameWizard_JanDeDobbeleer_oh-my-posh) by [TameWizard](https://github.com/TameWizard) ## Thanks * [Chris Benti](https://github.com/chrisbenti/PS-Config) providing the first influence to start oh-my-posh * [Keith Dahlby](https://github.com/dahlbyk/posh-git) for creating posh-git and making life more enjoyable * [Robby Russell](https://github.com/ohmyzsh/ohmyzsh) for creating oh-my-zsh, without him this would probably not be here * [Janne Mareike Koschinski](https://github.com/justjanne) for providing information on how to get certain information using Go (and the amazing [README](https://github.com/justjanne/powerline-go)) * [Starship](https://github.com/starship/starship/blob/master/src/init/mod.rs) for doing great things [kraken]: https://img.shields.io/badge/GitKraken-Legendary%20Git%20Tools-teal?style=plastic&logo=gitkraken [kraken-ref]: https://www.gitkraken.com/invite/nQmDPR9D [swag-badge]: https://img.shields.io/badge/Swag-Get%20some!-blue [swag]: https://swag.ohmyposh.dev [github-badge]: https://img.shields.io/badge/-Sponsor-fafbfc?logo=GitHub%20Sponsors [github-sponsors]: https://github.com/sponsors/JanDeDobbeleer [kofi-badge]: https://img.shields.io/badge/Ko--fi-Buy%20me%20a%20coffee!-%2346b798.svg [kofi]: https://ko-fi.com/jandedobbeleer [docs-badge]: https://img.shields.io/badge/Docs-ohmyposh.dev-blue [docs]: https://ohmyposh.dev [release-badge]: https://img.shields.io/github/v/release/jandedobbeleer/oh-my-posh?label=Release [release]: https://github.com/JanDeDobbeleer/oh-my-posh/releases/latest [sponsor-link]: https://buy.polar.sh/polar_cl_qnmZxboq1IDUJo03mk2Jue6ktqZrCXElnzH2s2xbV2R --- ## File: website/api/data/README.md # API Data Directory This directory contains data files used by the Azure Functions API. ## Schema File 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 --- title: MCP Validator Function --- ## Overview This directory contains the Azure Function that implements the Model Context Protocol (MCP) server for validating oh-my-posh configurations. ## Endpoints - `POST /api/mcp` - MCP server endpoint that handles validation requests - `GET /api/mcp` - Returns server information and available tools ## Supported Tools ### validate_config Validate an oh-my-posh configuration. - Supports JSON, YAML, and TOML formats - Returns detailed validation errors with JSON paths ### validate_segment 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 ### As an MCP Server Configure your MCP client to connect to this server: ```json { "mcpServers": { "oh-my-posh-validator": { "url": "https://ohmyposh.dev/api/mcp", "transport": "http" } } } ``` ### Direct HTTP Requests #### Get Server Info ```bash curl https://ohmyposh.dev/api/mcp ``` #### List Available Tools ```bash 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 ```bash 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 ```bash 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 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: ```json { "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 To test locally: ```bash cd website/api npm install npm start ``` Then send requests to `http://localhost:7071/api/mcp` ## Publishing to MCP Registry This server is published to the [MCP Registry](https://github.com/modelcontextprotocol/registry) using GitHub Actions. ### Publishing Publishing is triggered automatically when you push a version tag (same as oh-my-posh releases): ```bash 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 - `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 ```bash cd website/api npm install cd mcp node validate-server.js ``` --- ## File: website/docs/advanced/mcp-server.mdx --- id: mcp-server title: MCP Server sidebar_label: MCP Server --- ## What is the Oh My Posh MCP Server? 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 - **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 ### With MCP Clients Configure your MCP-compatible client (like Claude Desktop, Cline, or other AI assistants) to use the validator: ```json { "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 You can also use the validator directly via HTTP requests. #### Get Server Information ```bash curl https://ohmyposh.dev/api/mcp ``` #### List Available Tools ```bash 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 ```bash 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 ### validate_config **Parameters:** | Parameter | Type | Required | Description | |-----------|--------|----------|------------------------------------------------------------------| | content | string | Yes | The configuration content as a string (JSON, YAML, or TOML) | | format | string | No | The format: `json`, `yaml`, `toml`, or `auto` (default: `auto`) | **Returns:** ```json { "valid": true, "errors": [], "warnings": [ { "path": "$schema", "message": "Consider adding \"$schema\" property for better editor support.", "type": "recommendation" } ], "detectedFormat": "json", "parsedConfig": { ... } } ``` ## Response Fields | Field | Type | Description | |----------------|---------|--------------------------------------------------------| | valid | boolean | Whether the configuration is valid | | errors | array | List of validation errors (empty if valid) | | warnings | array | List of warnings and recommendations | | detectedFormat | string | The detected or specified format | | parsedConfig | object | The parsed configuration object | ## Error Format Each error in the `errors` array contains: | Field | Type | Description | |---------|--------|----------------------------------------------| | path | string | JSON path to the problematic property | | message | string | Human-readable error message | | keyword | string | The validation keyword that failed | | params | object | Additional parameters about the error | | data | any | The actual data that failed validation | ## Examples ### Valid Configuration ```json { "$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 ```json { "blocks": [ { "type": "invalid-type" } ] } ``` **Validation Result:** ```json { "valid": false, "errors": [ { "path": "/blocks/0/type", "message": "Value must be one of: prompt, rprompt, line", "keyword": "enum" } ] } ``` ## Integration Examples ### Claude Desktop Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/config.json` on macOS): ```json { "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) Configure Cline to use the MCP server, and it will automatically validate configurations when you're working on oh-my-posh themes. ## Supported Formats ### JSON ```json { "$schema": "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json", "version": 4, "blocks": [] } ``` ### YAML ```yaml $schema: https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json version: 4 blocks: [] ``` ### TOML ```toml version = 4 blocks = [] ``` ## Privacy & Security - 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 The MCP server is open source and part of the oh-my-posh repository: - [MCP Server Function][mcp] - [Validator Module][validator] ## Troubleshooting ### Format Not Detected Correctly If auto-detection fails, explicitly specify the format: ```json { "arguments": { "content": "...", "format": "yaml" } } ``` ### Parse Errors If you get parse errors, check that your configuration is valid JSON/YAML/TOML syntax before validating the schema. ### Schema Errors 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 Found a bug or have a suggestion? Please [open an issue][issue] on GitHub. [mcp]: https://github.com/JanDeDobbeleer/oh-my-posh/blob/main/website/api/mcp [validator]: https://github.com/JanDeDobbeleer/oh-my-posh/blob/main/website/api/shared/validator.js [issue]: https://github.com/JanDeDobbeleer/oh-my-posh/issues --- ## File: website/docs/configuration/block.mdx --- id: block title: Block sidebar_label: Block --- Let's take a closer look at what defines a block. import Config from "@site/src/components/Config.js"; ## Settings | Name | Type | | ------------------ | --------- | | `type` | `string` | | `newline` | `boolean` | | `alignment` | `string` | | `filler` | `string` | | `overflow` | `string` | | `leading_diamond` | `string` | | `trailing_diamond` | `string` | | `segments` | `array` | | `force` | `boolean` | | `restart_cycle` | `boolean` | | `index` | `int` | ### Type 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 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 - `left` - `right` Tell the engine if the block should be left or right-aligned. ### Filler 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][color-overrides]. 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. | Name | Type | Description | | ----------- | ------ | --------------------------------------------------------------------- | | `.Overflow` | `text` | if no overflow was needed, this is empty. Otherwise `hide` or `break` | | `.Padding` | `int` | the computed length of the padding between left and right blocks | 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. ### Overflow - `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 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 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 Array of one or more [segments][segment]. ### Force When set to `true`, the block will always be rendered, even if all segments are empty. Defaults to `false`. ### Restart Cycle When a [color cycle][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. ### Index 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`. [ble.sh]: https://github.com/akinomyoga/ble.sh [color-overrides]: /docs/configuration/colors#color-overrides [cycle]: /docs/configuration/colors#cycle [segment]: segment.mdx [override]: /docs/configuration/general#extends --- ## File: website/docs/configuration/colors.mdx --- id: colors title: Colors sidebar_label: Colors --- import Config from "@site/src/components/Config.js"; ## Standard colors Oh My Posh supports multiple different color references, being: - True color using [hex colors][hexcolors] (for example `#CB4B16`). - 16 [ANSI color names][ansicolors]. 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 Anywhere a **Standard color** is expected, you can instead use a `linear-gradient` with two or more comma-separated stops: 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][palette] (`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 `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](#stops-and-segment-width). 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 A stop must resolve to a hex color before it can be interpolated: | Stop | Supported | | ------------------------------------------------------------------ | --------- | | Hex color (`#CB4B16`, `#F0A`) | yes | | [Palette reference][palette] to a hex color (`p:blue`) | yes | | `parentBackground`, `parentForeground`, `background`, `foreground` | yes | | `accent` (Windows and macOS only) | yes | | ANSI color name (`red`, `lightBlue`) | no | | 256 color palette number (`146`) | no | | `transparent` | no | 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](#color-overrides) 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`](#auto-shade-from-a-single-color) for a one-color gradient effect instead. ### Stops and segment width 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 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: `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][palette] 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][palette] once and shade the palette entry: 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 Array of string [templates][templates] to define the color based on the current context. Under the hood this uses go's [text/template][go-text-template] feature extended with [sprig][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][template-properties]. The following sample is based on the [AWS Segment][aws]. 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 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: `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: ┏[", }} /> If you also wanted to change the background color in the previous command, you would do so like this: ┏[", }} /> To change _only_ the background color, just omit the first color from the above string: ┏[", }} /> ## Palette If your configuration defined the Palette, you can use the _Palette reference_ `p:` in places where the **Standard color** is expected. ### Defining a Palette Palette is a set of named **Standard colors**. To use a Palette, define a `"palette"` object at the top level of your configuration: 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][templates] 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][template-properties] to switch colors based on context. For example, to use a different color when a `Git` segment is active in the prompt: ### Using a Palette You can now use _Palette references_ in any [Segment's][segment] `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][git] segment using _Palette references_: 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** 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][battery]): - ", charging_icon: "+ ", charged_icon: "* ", }, }} /> ### Handling of invalid references 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 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": ## Palettes If you want to use a `palette` conditionally, for example for **light or dark mode**, you can define multiple `palettes` and a [template][templates] 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: 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: :::info If a color is defined in both palette and palettes, the palettes' resolved color will take precedence. ::: ## Cycle 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. [hexcolors]: https://htmlcolorcodes.com/color-chart/material-design-color-chart/ [ansicolors]: https://htmlcolorcodes.com/color-chart/material-design-color-chart/ [git]: /docs/segments/scm/git [battery]: /docs/segments/system/battery [template-properties]: /docs/configuration/templates#global-properties [aws]: /docs/segments/cloud/aws [go-text-template]: https://golang.org/pkg/text/template/ [segment]: /docs/configuration/segment [sprig]: https://masterminds.github.io/sprig/ [templates]: templates.mdx [palette]: #palette --- ## File: website/docs/configuration/debug-prompt.mdx --- id: debug-prompt title: Debug prompt sidebar_label: Debug prompt --- 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][go-text-template] [templates][templates] extended with [sprig][sprig] to enrich the text. Environment variables are available, just like the [`console_title_template`][console-title] functionality. ## Configuration You need to extend or create a custom theme with your debug prompt override. For example: ## Options | Name | Type | Description | | ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `foreground` | `string` | [color][colors] | | `foreground_templates` | `string` | [color templates][color-templates] | | `background` | `string` | [color][colors] | | `background_templates` | `string` | [color templates][color-templates] | | `template` | `string` | a go [text/template][go-text-template] template extended with [sprig][sprig] utilizing the properties below - defaults to `[DBG]: ` | ## Template ([info][templates]) | Name | Type | Description | | -------------- | --------- | ------------------------------------------------------------------------- | | `.Root` | `boolean` | is the current user root/admin or not | | `.PWD` | `string` | the current working directory | | `.Folder` | `string` | the current working folder | | `.Shell` | `string` | the current shell name | | `.UserName` | `string` | the current user name | | `.HostName` | `string` | the host name | | `.Code` | `int` | the last exit code | | `.Env.VarName` | `string` | Any environment variable where `VarName` is the environment variable name | [go-text-template]: https://golang.org/pkg/text/template/ [sprig]: https://masterminds.github.io/sprig/ [console-title]: /docs/configuration/title#console-title-template [templates]: /docs/configuration/templates [colors]: /docs/configuration/colors [color-templates]: /docs/configuration/colors#color-templates --- ## File: website/docs/configuration/general.mdx --- id: general title: General sidebar_label: General --- 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][schema] available which is kept up-to-date and helps with autocomplete and validation of the configuration. :::info There are a few [themes][themes] available which are basically predefined configurations. You can use these as they are, or as a starting point to create your own configuration. ::: ```json { "$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 # 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 ``` ```toml "$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][releases], 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. ::: ```bash 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][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 | Name | Type | Default | Description | | --------------------------- | ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `final_space` | `boolean` | | when true adds a space at the end of the prompt | | `pwd` | `string` | | notify terminal of current working directory, values can be `osc99`, `osc7` or `osc51` depending on your terminal. Supports [templates][templates] | | `cursor_style` | `string` | | set the cursor's shape/blink state at the start of the prompt using a DECSCUSR sequence, values can be `blinking_block`, `steady_block`, `blinking_underline`, `steady_underline`, `blinking_bar`, `steady_bar`, `default_steady` or `default_blinking` (the latter two only reset shape/blink, leaving terminal-specific cursors like Windows Terminal's vintage, double underscore or empty box shapes as configured in the terminal profile). Supports [templates][templates], e.g. to vary by `.Env.POSH_VI_MODE` (set by the [`vimode`][vimode] segment's shell hooks) | | `terminal_background` | `string` | | [color][colors] - terminal background color, set to your terminal's background color when you notice black elements in Windows Terminal or the Visual Studio Code integrated terminal | | `accent_color` | `string` | | [color][colors] - accent color, used as a fallback when the `accent` [color][accent] is not supported | | `var` | `map[string]any` | | config variables to use in [templates][templates]. Can be any value | | `shell_integration` | `boolean` | `false` | enable shell integration using FinalTerm's OSC sequences. Works in bash, cmd (Clink v1.14.25+), fish, powershell and zsh. The `FTCS_COMMAND_EXECUTED` mark carries the command line as kitty's `cmdline_url=` parameter | | `enable_cursor_positioning` | `boolean` | `false` | enable fetching the cursor position in bash, zsh, and fish to allow automatic hiding of leading newlines when at the top of the shell | | `patch_pwsh_bleed` | `boolean` | `false` | patch a PowerShell bug where the background colors bleed into the next line at the end of the buffer (can be removed when [this][pwsh-bleed] is merged) | | `upgrade` | `Upgrade` | | enable auto upgrade or the upgrade notice. See [Upgrade] | | `iterm_features` | `[]string` | `false` | enable iTerm2 specific features:
  • `prompt_mark`: add the `iterm2_prompt_mark` [function][iterm2-si] for supported shells
  • `current_dir`: expose the current directory for iTerm2
  • `remote_host`: expose the current remote and user for iTerm2
    • | | `terminal_features` | TerminalFeatures | | map terminal features to the terminals supporting them. See [Terminal features](#terminal-features) | | `maps` | [`Maps`](#maps) | | a list of custom text mappings | | `async` | `boolean` | `false` | load the prompt async. Will either load the standard prompt, or allow you to start typing right away. Supported for `pwsh`, `powershell`, `zsh`, `bash` and `fish` | | `version` | `int` | `4` | the config version, currently at `4` | | `extends` | `string` | | the configuration to [extend] from | | `streaming` | `int` | | enable streaming mode with a timeout in milliseconds for pending segments. See [streaming] | ### Maps | Name | Type | Description | | ------------ | -------- | ------------------------------------------------------------------------------------- | | `user_name` | `object` | text replacement mapping for user names | | `host_name` | `object` | text replacement mapping for host names | | `shell_name` | `object` | text replacement mapping for shell names. This modifies the `.Shell` global property. | import Config from "@site/src/components/Config.js"; ### Terminal features 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. | Name | Type | Default | Description | | ---------- | ---------- | -------------------- | ----------------------------------------------- | | `progress` | `[]string` | `[Windows Terminal]` | terminals supporting OSC 9;4 progress sequences | ### Extends 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][themes]. 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 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][schema] 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: ```json ... "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 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: ```json { "$schema": "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json" } ``` While for yaml: ```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. [releases]: https://github.com/JanDeDobbeleer/oh-my-posh/releases/latest [font]: /docs/installation/fonts [schema]: https://github.com/JanDeDobbeleer/oh-my-posh/blob/main/themes/schema.json [themes]: https://github.com/JanDeDobbeleer/oh-my-posh/tree/main/themes [colors]: /docs/configuration/colors [accent]: /docs/configuration/colors#standard-colors [templates]: /docs/configuration/templates#config-variables [vimode]: /docs/segments/system/vimode [pwsh-bleed]: https://github.com/PowerShell/PowerShell/pull/19019 [iterm2-si]: https://iterm2.com/documentation-shell-integration.html [Upgrade]: /docs/installation/upgrade [extend]: /docs/configuration/general#extends [streaming]: /docs/configuration/streaming --- ## File: website/docs/configuration/introduction.mdx --- id: introduction title: Introduction sidebar_label: Introduction hide_table_of_contents: true --- 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 Traditionally, prompt tools work with custom scripts per theme (just like [Oh My Posh 2][omp] 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. A [block][block] has properties that indicate its position and the [segments][segment] it will render. A [segment][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][themes] from [Oh My Posh][themes] 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! [omp]: https://github.com/JanDeDobbeleer/oh-my-posh2 [block]: /docs/configuration/block [segment]: /docs/configuration/segment [themes]: https://github.com/JanDeDobbeleer/oh-my-posh/tree/main/themes