` | Switch icon tier (`nerd`, `font_awesome`, `unicode`, `ascii`) and persist it to `.zshrc`. Offers to install a Nerd Font if none is detected. |
| `aporia fonts install` | Download and install JetBrainsMono Nerd Font directly (no need to re-run the full installer). |
| `aporia doctor` | Run health checks: Zsh version, locale, git availability, icon mode. |
| `aporia benchmark` | Profile the git segment, language segment, and render pass — useful when the prompt feels slow. |
| `aporia inspect` | Dump raw segment data for debugging. |
| `aporia list` | Show every registered plugin and its status (active / installed / not installed). |
| `aporia upgrade` | Update Aporia in place (detects Homebrew, git checkout, or manual install) and reports the version change. |
## Plugin System
Aporia ships 23 plugins, all opt-in via the `AP_PLUGINS` array so a fresh install stays minimal. Two — `zsh-autosuggestions` and `zsh-syntax-highlighting` — are treated as essentials and installed automatically.
> [!TIP]
> **New to Aporia plugins?** The **[Plugin Guide](PLUGINS.md)** documents every plugin with configuration examples.
### Highlights
| Plugin | Description | Category |
|---|---|---|
| `docker-ctx` | Docker context in the prompt, read from config — no subprocess | Context |
| `kube-ctx` | `kubectl` context:namespace, parsed from kubeconfig directly | Context |
| `aws-profile` | Active AWS profile and region, colored red for prod-like profiles | Context |
| `gh-context` | GitHub CLI identity, cached per session | Context |
| `vpn-status` | Detects Tailscale, Mullvad, or a generic tun/wg tunnel | Context |
| `telemetry` | CPU/RAM load, shown only above a configurable threshold | Context |
| `target` | Pins an operational IP/host in the prompt to prevent command leakage | Context |
| `sudo` | Warns when a shell has elevated privileges | Productivity |
| `fzf-tab` | Replaces the tab-completion menu with `fzf` | Utility |
| `fast-syntax-highlighting` | Drop-in FSH replacement, faster and themeable | Essential |
See [PLUGINS.md](PLUGINS.md) for the remaining cloud (`azure-ctx`, `gcp-ctx`), environment (`autoswitch-venv`, `nix-shell`), search (`history-substring-search`, `fzf-history`), and interaction (`forgit`, `autopair`, `you-should-use`) plugins.
### Management Commands
* **`aporia install `**: Downloads a third-party plugin.
* **`aporia activate
`**: Enables a plugin and saves it to `~/.zshrc`.
* **`aporia deactivate
`**: Disables a plugin and removes it from `~/.zshrc`.
* **`aporia activate-all`**: Activates every installed-but-inactive plugin at once.
* **`aporia update`**: Pulls the latest changes for all installed plugins.
## Configuration
Set these in your `~/.zshrc` *before* the line that sources the theme:
| Variable | Default | Description |
| :--- | :--- | :--- |
| `AP_THEME` | `deep_blue` | Color preset: `deep_blue`, `light`, `amber`, `crimson_void`, `forest_matrix` |
| `AP_ICON_STYLE` | `nerd` | Icon tier: `nerd`, `font_awesome` |
| `AP_USE_NERD_FONT` | `1` | Set to `0` to use the standard Unicode tier instead of Nerd Font glyphs |
| `AP_ASCII_FALLBACK` | `0` | Set to `1` to force plain ASCII (no special font or Unicode needed) |
| `AP_SHOW_SSH` | `1` | Show SSH context (`user@host`) when connected remotely |
| `AP_SHOW_GIT` | `1` | Show git branch, dirty state, and ahead/behind counts |
| `AP_SHOW_LANGS` | `1` | Show language versions, only inside matching projects |
| `AP_SHOW_EXEC_TIME` | `0` | Show the last command's execution time |
| `AP_EXEC_TIME_THRESHOLD` | `0` | Minimum duration (seconds) before execution time is shown; `0` shows it for every command |
| `AP_SHOW_EXIT_CODE` | `1` | Show non-zero exit codes |
| `AP_SHOW_TIME` | `1` | Show the right-side clock |
| `AP_DIR_DEPTH` | `3` | Number of path segments to show in the directory indicator |
Prefer `aporia theme ` and `aporia icons ` over hand-editing `AP_THEME`/`AP_ICON_STYLE` directly — the CLI commands persist the change to `.zshrc` for you and validate the input.
## Troubleshooting
> [!IMPORTANT]
> **Icons appearing as squares or plain text?**
> 1. Confirm you're using a [Nerd Font](https://www.nerdfonts.com) — run `aporia fonts install` if you don't have one, then set it as your terminal's font (installing it isn't enough; it has to be *selected*).
> 2. Check your locale: run `locale` and confirm `LANG` includes `UTF-8`.
> 3. No Nerd Font available? Run `aporia icons unicode` (or `aporia icons ascii` for zero special characters).
> [!IMPORTANT]
> **Icons look inconsistent — some noticeably bigger than others?**
> This almost always means your terminal profile isn't actually using the font you think it is (e.g. a different Nerd Font family than the one Aporia was tested against). Check what font your terminal profile is set to, and standardize on the same Nerd Font (we recommend JetBrainsMono Nerd Font Mono, via `aporia fonts install`) across every machine you use Aporia on.
> [!IMPORTANT]
> **A setting I changed doesn't seem to take effect?**
> Check for a second Aporia install sourcing the theme in the same shell (see the installation warning above) — the first one to load wins any default the second tries to set. Also check you haven't set the variable manually in the current shell session (`echo $AP_SHOW_EXEC_TIME`, etc.) — a bare assignment in your terminal persists for that session even after `source ~/.zshrc`.
## License
MIT © **Ahmed Mardi (fr3on)**
