# How to Add, Update, and Remove Plugins in Omarchy: Complete CLI Guide

> Easily add update and remove Omarchy plugins using the CLI. Learn commands like omarchy plugin add and explore options for automated management.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-02

---

**Use `omarchy plugin add`, `omarchy plugin update`, and `omarchy plugin remove` to manage shell plugins in the `~/.config/omarchy/plugins` directory, with optional `--enable` and `--yes` flags for automation.**

Omarchy's plugin system treats every plugin as a directory under `~/.config/omarchy/plugins`. The core lifecycle commands live in the `bin/` folder of the [omacom/omarchy](https://github.com/omacom/omarchy) repository and provide URL validation, manifest checking, and seamless integration with the running omarchy-shell.

---

## Adding Plugins to Omarchy

The **`omarchy plugin add`** command handles the complete installation workflow.

### Basic Installation

```bash
omarchy plugin add https://github.com/acme/omarchy-weather.git

```

This command, implemented in `bin/omarchy-plugin-add`, performs the following:

1. **Validates the URL** via `omarchy-git-url-check` to block malicious sources
2. **Clones** the repository into `~/.config/omarchy/plugins/`
3. **Validates** the plugin's [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json) using `omarchy-plugin-validate`
4. **Rescans** the shell via `omarchy-shell shell rescanPlugins` to make the plugin available

### Add and Enable in One Step

```bash
omarchy plugin add https://github.com/acme/omarchy-weather.git --enable

```

The `--enable` flag immediately registers the plugin with your running shell.

### Non-Interactive Installation

```bash
omarchy plugin add https://github.com/acme/omarchy-weather.git --yes

```

The `--yes` flag skips all prompts—essential for automation scripts.

---

## Updating Plugins in Omarchy

The **`omarchy plugin update`** command keeps your Git-managed plugins current.

### Update a Specific Plugin

```bash
omarchy plugin update acme.weather

```

Specify the plugin by its **manifest ID** (not the repository URL). The `bin/omarchy-plugin-update` script:

- Fetches the latest commits from the remote
- Displays a diff when `delta` is installed
- Fast-forwards the checkout
- Re-validates the plugin manifest
- Forces a shell rescan

### Update All Git-Managed Plugins

```bash
omarchy plugin update

```

Omit the ID to update every Git-based plugin in your installation.

### Automated Updates

```bash
omarchy plugin update --yes

```

Bypass confirmation prompts for unattended operation.

---

## Removing Plugins from Omarchy

The **`omarchy plugin remove`** command safely uninstalls plugins.

### Interactive Removal

```bash
omarchy plugin remove

```

Run without arguments to select from a list using the `gum` UI library.

### Remove by ID

```bash
omarchy plugin remove acme.weather

```

The `bin/omarchy-plugin-remove` implementation handles safety cleanup:

- **Disables** the plugin if currently enabled
- **Backs up** non-Git plugins before deletion
- **Deletes** Git checkouts entirely
- **Rescans** the shell to remove references

### Force Removal

```bash
omarchy plugin remove acme.weather --yes

```

Skip confirmation with `--yes` for scripted environments.

---

## Enabling and Positioning Plugins

After adding a plugin, use **`omarchy plugin enable`** to activate it with precise bar placement:

```bash

# Enable with automatic placement

omarchy plugin enable acme.weather

# Place in a specific section

omarchy plugin enable acme.weather --section right

# Position by index

omarchy plugin enable acme.weather --section left --index 2

# Relative positioning

omarchy plugin enable acme.weather --after clock
omarchy plugin enable acme.weather --before battery

```

The `bin/omarchy-plugin-enable` script supports `--section` (`left`, `center`, `right`), `--index`, `--before`, and `--after` for bar-widget placement.

---

## Common Implementation Details

All plugin commands share these validation and integration layers:

| Helper | Purpose |
|--------|---------|
| `omarchy-git-url-check` | Security validation before cloning |
| `omarchy-plugin-validate` | [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json) schema verification |
| `omarchy-shell shell rescanPlugins` | Runtime shell reload |
| `gum` | Interactive UI (when `--yes` is absent) |

---

## Summary

- **Add plugins** with `omarchy plugin add <git-url> [--enable] [--yes]` — clones, validates, and integrates
- **Update plugins** with `omarchy plugin update [<id>] [--yes]` — fetches latest, shows diffs, fast-forwards
- **Remove plugins** with `omarchy plugin remove <id> [--yes]` — disables, backs up, and cleans up
- **Enable plugins** with `omarchy plugin enable <id> [--section/--index/--before/--after]` — activates with bar placement
- All commands operate on `~/.config/omarchy/plugins` and trigger shell rescans automatically

---

## Frequently Asked Questions

### What is the default plugin directory in Omarchy?

Omarchy stores all plugins in `~/.config/omarchy/plugins`. Each plugin is a subdirectory containing at minimum a [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json) file that declares its ID, version, and capabilities.

### Can I automate plugin management without interactive prompts?

Yes. Every plugin command accepts the `--yes` flag to bypass `gum`-powered interactive prompts. Use this flag in CI/CD pipelines or personal dotfiles bootstrap scripts.

### How does Omarchy validate plugin safety before installation?

The `omarchy-git-url-check` helper validates source URLs before cloning, and `omarchy-plugin-validate` verifies the [`manifest.json`](https://github.com/omacom/omarchy/blob/main/manifest.json) structure. Git-managed plugins can be updated safely; non-Git plugins are backed up before removal to prevent data loss.

### What happens if I update a plugin that has local changes?

The `bin/omarchy-plugin-update` script performs a fast-forward merge. If local modifications exist that cannot be fast-forwarded, the update will fail and preserve your working state—review and commit local changes before updating.