# Oh My Posh — Full Documentation

> Oh My Posh is the most customizable and fastest prompt theme engine for any shell.
> It renders beautifully themed prompts displaying Git status, language versions, cloud context,
> system metrics and more — 118 segments in all — on Windows, macOS, and Linux.

Website: https://ohmyposh.dev
Repository: https://github.com/JanDeDobbeleer/oh-my-posh
License: MIT
Author: Jan De Dobbeleer

---

## Overview

Oh My Posh is a cross-shell, cross-platform prompt theme engine written in Go. A single
JSON/YAML/TOML configuration file works across PowerShell, Bash, Zsh, Fish, Nu (Nushell),
Cmd (via Clink), Elvish, and Xonsh — on Windows, macOS, and Linux.

Key features:
- 117 prompt segments (Git, language runtimes, cloud, system metrics, and more)
- Blazing-fast rendering with async support and smart caching
- Full Unicode, emoji, and Nerd Font icon support
- Transient and tooltip prompts
- Live configuration reloading

---

## Installation

For step-by-step installation instructions see the skill files:

- [Windows](/skills/ohmyposh/installation/windows.md)
- [macOS](/skills/ohmyposh/installation/macos.md)
- [Linux](/skills/ohmyposh/installation/linux.md)

### Windows (summary)

```powershell
winget install JanDeDobbeleer.OhMyPosh --source winget
```

### macOS (summary)

```bash
brew install jandedobbeleer/oh-my-posh/oh-my-posh
```

### Linux (summary)

```bash
curl -s https://ohmyposh.dev/install.sh | bash -s
```

---

## Fonts

Oh My Posh themes use glyphs and icons from Nerd Fonts. Install a Nerd Font with:

```bash
oh-my-posh font install meslo
```

List every installable font with `oh-my-posh font list`. Recommended font: Meslo LGM NF. Set the font in your terminal emulator after installation.

---

## Shell Integration

For detailed per-shell setup see the skill files:

- [PowerShell](/skills/ohmyposh/shell/powershell.md)
- [Bash](/skills/ohmyposh/shell/bash.md)
- [Zsh](/skills/ohmyposh/shell/zsh.md)
- [Fish](/skills/ohmyposh/shell/fish.md)
- [Nu / Nushell](/skills/ohmyposh/shell/nu.md)
- [Cmd via Clink](/skills/ohmyposh/shell/cmd.md)
- [Elvish](/skills/ohmyposh/shell/elvish.md)
- [Xonsh](/skills/ohmyposh/shell/xonsh.md)

Detect your current shell:

```bash
oh-my-posh get shell
```

Quick reference:

| Shell      | Profile file                          | Init line                                       |
|------------|---------------------------------------|-------------------------------------------------|
| PowerShell | `$PROFILE`                            | `oh-my-posh init pwsh \| Invoke-Expression`    |
| Bash       | `~/.bashrc`                           | `eval "$(oh-my-posh init bash)"`                |
| Zsh        | `~/.zshrc`                            | `eval "$(oh-my-posh init zsh)"`                 |
| Fish       | `~/.config/fish/config.fish`          | `oh-my-posh init fish \| source`               |
| Nu         | `$nu.config-path`                     | `oh-my-posh init nu`                            |
| Cmd        | Clink scripts / oh-my-posh.lua        | `load(io.popen('oh-my-posh init cmd'):read("*a"))()` |
| Elvish     | `~/.elvish/rc.elv`                    | `eval (oh-my-posh init elvish)`                 |
| Xonsh      | `~/.xonshrc`                          | `execx($(oh-my-posh init xonsh))`               |

---

## Configuration & Themes

For detailed customization instructions see [/skills/ohmyposh/configuration.md](/skills/ohmyposh/configuration.md).

Browse themes: https://ohmyposh.dev/docs/themes

Apply a theme:

```powershell
# PowerShell
oh-my-posh init pwsh --config 'jandedobbeleer' | Invoke-Expression
```

```bash
# Bash / Zsh
eval "$(oh-my-posh init bash --config jandedobbeleer)"
```

Export a theme for editing:

```bash
oh-my-posh config export --config jandedobbeleer --output ~/.mytheme.omp.json
```

Enable live reload while editing:

```bash
oh-my-posh enable reload
```

---

## Configuration Schema

Configs are JSON, YAML, or TOML. Schema:
https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json

Minimal JSON structure:

```json
{
  "$schema": "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json",
  "version": 3,
  "blocks": [
    {
      "type": "prompt",
      "alignment": "left",
      "segments": [
        {
          "type": "path",
          "style": "powerline",
          "powerline_symbol": "\ue0b0",
          "foreground": "#ffffff",
          "background": "#61afef",
          "properties": { "style": "folder" }
        }
      ]
    }
  ]
}
```

Top-level fields: `version`, `blocks`, `final_space`, `console_title_template`,
`transient_prompt`, `secondary_prompt`, `palette`, `cycle`.

---

## Popular Segments

| Type           | Description                         |
|----------------|-------------------------------------|
| `path`         | Current directory                   |
| `git`          | Git branch, status, ahead/behind    |
| `node`         | Node.js version                     |
| `python`       | Python version / virtualenv         |
| `go`           | Go version                          |
| `rust`         | Rust version                        |
| `aws`          | AWS profile/region                  |
| `azure`        | Azure subscription                  |
| `kubectl`      | Kubernetes context                  |
| `battery`      | Battery level                       |
| `time`         | Current time                        |
| `os`           | OS icon                             |
| `session`      | Username / hostname                 |
| `exit`         | Last command exit code              |
| `executiontime`| Last command duration               |

Full segments reference: https://ohmyposh.dev/docs/segments/overview

---

## MCP Endpoint

URL: `https://ohmyposh.dev/api/mcp`
Protocol: JSON-RPC 2.0 over HTTP POST (GET returns server info)
Discovery: `https://ohmyposh.dev/.well-known/mcp.json`

Available tools: `validate_config`, `validate_segment`
Supported formats: json, yaml, toml, auto

```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":"{\"version\":3}","format":"json"}},"id":1}'
```

---

## Troubleshooting

- Icons show as boxes — install a Nerd Font and set it in your terminal emulator
- `oh-my-posh` not found — restart terminal or add install directory to `$PATH`
- PowerShell execution policy error — run `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine`
- Fish version error — upgrade to Fish 4.1.0+
- Nu version error — upgrade to Nushell v0.104.0+
- macOS bash error — update bash with `brew install bash`

Full FAQ: https://ohmyposh.dev/docs/faq