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

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 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

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 using omarchy-plugin-validate
4. Rescans the shell via omarchy-shell shell rescanPlugins to make the plugin available

Add and Enable in One Step

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

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

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

omarchy plugin update

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

Automated Updates

omarchy plugin update --yes

Bypass confirmation prompts for unattended operation.

---

Removing Plugins from Omarchy

The omarchy plugin remove command safely uninstalls plugins.

Interactive Removal

omarchy plugin remove

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

Remove by ID

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

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:

# 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}