# How to Install a Third-Party Omarchy Plugin: Complete CLI Guide > Install and enable third-party Omarchy plugins using the CLI. This guide shows you how to clone, inspect, and activate custom plugins from any Git repository. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: how-to-guide - Published: 2026-08-23 --- **You can install a third-party Omarchy plugin by running `omarchy plugin add ` to clone the repository into `~/.config/omarchy/plugins//`, then activate it with `omarchy plugin enable ` after inspecting the manifest and source code.** Omarchy, the open-source desktop environment developed by Basecamp, extends its functionality through a plugin architecture that treats each extension as a standalone Git repository. Installing a third-party Omarchy plugin requires cloning the code locally, validating its [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json), and registering it with the running `omarchy-shell`. All plugin management logic resides in the `basecamp/omarchy` repository, specifically within the CLI wrappers located in `bin/` and the runtime registry at `shell/services/PluginRegistry.qml`. ## Prerequisites: The Plugin Manifest Every valid third-party plugin must contain a [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) file at its repository root. This manifest declares the plugin's **ID**, available **kinds** (widget types), and entry points. Without this file, the `omarchy plugin add` command will reject the repository. The manifest format is documented in the Omarchy shell reference at [`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md) lines 14-24. ## Installing a Third-Party Omarchy Plugin from GitHub ### Step 1: Add the Plugin Repository Run the `omarchy plugin add` command followed by the Git URL: ```bash omarchy plugin add https://github.com//.git ``` According to the implementation in `bin/omarchy-plugin-add`, this command performs three actions: - Clones the remote repository into `~/.config/omarchy/plugins//` (where `` is extracted from the manifest) - Validates the presence of [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) - Registers the plugin with the shell's registry but keeps it **disabled** by default ### Step 2: Review the Plugin Code Before enabling any code execution, inspect the cloned directory: ```bash ls ~/.config/omarchy/plugins// cat ~/.config/omarchy/plugins//manifest.json ``` Omarchy keeps newly added plugins disabled specifically to allow this security review. No widgets or scripts run until you explicitly enable the plugin. ### Step 3: Enable the Plugin Activate the plugin using its manifest ID: ```bash omarchy plugin enable ``` As implemented in `bin/omarchy-plugin-enable`, this updates the `PluginRegistry.qml` runtime registry, activates the specified kinds, and places bar widgets according to the manifest's default section configuration. ## Automating Installation with Non-Interactive Mode For CI/CD pipelines or automated setup scripts, bypass confirmation prompts by appending the `--yes` flag: ```bash omarchy plugin add https://github.com/acme/omarchy-weather.git --yes omarchy plugin enable acme.weather --yes ``` This non-interactive mode is documented in [`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md) lines 86-89. ## Manual Installation Without the CLI You can install a third-party Omarchy plugin without using the `omarchy plugin add` command by manually placing the files: 1. Copy your prepared plugin folder to `~/.config/omarchy/plugins//` 2. Run `omarchy-shell shell rescanPlugins` to refresh the registry 3. Execute `omarchy plugin enable ` to activate it This manual workflow mirrors the automated flow but requires you to handle the initial file placement and validation yourself. ## Managing Installed Plugins ### Updating Plugins Fetch the latest changes for all installed plugins with: ```bash omarchy plugin update ``` The `bin/omarchy-plugin-update` wrapper performs a fast-forward pull and displays a diff of changes before applying them, allowing you to review modifications before they take effect. ### Removing Plugins To completely remove a third-party Omarchy plugin: ```bash omarchy plugin remove ``` This deletes the directory at `~/.config/omarchy/plugins//` and removes its entry from the registry, as implemented in `bin/omarchy-plugin-remove`. ## Summary - **Third-party plugins** are standalone Git repositories containing a root-level [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) file - **Installation** uses `omarchy plugin add ` to clone into `~/.config/omarchy/plugins//` - **Security default**: Plugins remain disabled after cloning to allow code review before activation - **Activation** requires `omarchy plugin enable ` to register with `shell/services/PluginRegistry.qml` - **Automation** is supported via the `--yes` flag for non-interactive environments - **Updates** show a diff before fast-forwarding via `omarchy plugin update` ## Frequently Asked Questions ### Where are third-party Omarchy plugins stored on disk? Third-party plugins are cloned into `~/.config/omarchy/plugins//`, where `` corresponds to the identifier declared in the plugin's [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json). The `omarchy plugin add` command handles this directory creation automatically. ### Why does Omarchy disable plugins by default after installation? Omarchy disables newly added plugins as a security measure. This prevents malicious or buggy code from executing immediately upon cloning. You must explicitly run `omarchy plugin enable ` after reviewing the source files, giving you full control over what runs in your desktop environment. ### How do I update a third-party Omarchy plugin to the latest version? Run `omarchy plugin update` to fetch the latest commits from the plugin's remote repository. The command displays a diff of changes before applying a fast-forward pull, ensuring you can review updates before they become active. This is handled by the `bin/omarchy-plugin-update` script. ### Can I install an Omarchy plugin without internet access or the CLI? Yes. You can manually copy a plugin directory into `~/.config/omarchy/plugins//`, then run `omarchy-shell shell rescanPlugins` to force the shell to discover the new manifest, followed by `omarchy plugin enable ` to activate it. This manual method bypasses the Git cloning performed by `omarchy plugin add`.