# How to Set Up the Omarchy CLI Locally: A Complete Installation Guide > Learn how to set up the Omarchy CLI locally with our complete installation guide. Clone the repository, set environment variables, and add the bin directory to your PATH for quick access. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: how-to-guide - Published: 2026-09-12 --- **To set up the Omarchy CLI locally, clone the omacom/omarchy repository, set the `OMARCHY_PATH` environment variable to the repository root, and add the `bin` directory to your system `PATH`.** The Omarchy CLI is a lightweight Bash-based command-line interface distributed with the [omacom/omarchy](https://github.com/omacom/omarchy) repository. Unlike traditional compiled binaries, it operates as a collection of executable scripts coordinated by a central dispatcher, making local setup straightforward for development or testing. This guide walks through configuring your environment to run the Omarchy CLI without a full system installation. ## Prerequisites Before you begin, ensure your system meets these requirements: - **Git** for cloning the repository - **Bash** shell (version 4.0 or later) - Standard Unix utilities (`export`, `ln`, `chmod`) ## Local Setup Instructions Setting up the Omarchy CLI locally involves three core steps: cloning the repository, configuring environment variables, and verifying access. ### Clone the Repository First, download the Omarchy source code to your local machine. The CLI resides in the `bin` directory at the repository root. ```bash git clone https://github.com/omacom/omarchy.git cd omarchy/quattro ``` ### Configure Environment Variables The **Omarchy CLI** requires the `OMARCHY_PATH` variable to locate the repository root and resolve helper script paths. Additionally, you must expose the `bin` directory to your shell's executable search path. For a temporary session setup: ```bash export OMARCHY_PATH="$(pwd)" export PATH="$OMARCHY_PATH/bin:$PATH" ``` The `OMARCHY_PATH` variable tells the main dispatcher (`bin/omarchy`) where to find the `GROUP_DESCRIPTIONS` table and individual command implementations prefixed with `omarchy-`. ### Verify the Installation Confirm the CLI is accessible and functional by querying its help system: ```bash omarchy --help omarchy commands --list ``` These commands should display the top-level help text (documented in [`manual/14-omarchy-cli.md`](https://github.com/omacom/omarchy/blob/main/manual/14-omarchy-cli.md)) and enumerate all available command groups. Test a specific group to ensure helper scripts resolve correctly: ```bash omarchy theme list ``` ## Permanent Installation Options For daily use, consider these persistent installation methods rather than temporary exports. ### Shell Profile Configuration Add the environment variables to your shell's startup file to maintain the setup across sessions: ```bash echo 'export OMARCHY_PATH="/full/path/to/omarchy/quattro"' >> ~/.bashrc echo 'export PATH="$OMARCHY_PATH/bin:$PATH"' >> ~/.bashrc ``` Reload your profile or restart your terminal to apply changes: ```bash source ~/.bashrc ``` ### System-Wide Symlink Alternatively, create a symbolic link to the main dispatcher in a directory already on your system `PATH`: ```bash sudo ln -s "$OMARCHY_PATH/bin/omarchy" /usr/local/bin/omarchy ``` This method requires that `OMARCHY_PATH` remains set in your environment, as the dispatcher relies on it to locate sub-commands in the `bin` directory. ## CLI Architecture Overview Understanding the Omarchy CLI structure helps when contributing or debugging local setups. The **entry point** at `bin/omarchy` parses top-level flags (`--help`, `commands`, etc.) and routes sub-commands to specific helper scripts. It constructs the command table from the `GROUP_DESCRIPTIONS` associative array defined within the same file, mapping human-readable groups like `theme` or `capture` to executable scripts named `omarchy--`. Individual commands reside as standalone Bash scripts in `bin/`: - `bin/omarchy-update` handles system updates - `bin/omarchy-theme-list` enumerates available themes - `bin/omarchy-capture-screenshot` manages screen captures Each script sources standard Omarchy utilities and operates independently, allowing you to invoke them directly or through the main dispatcher. ## Getting Started with Common Commands Once configured, explore the CLI's capabilities through these common operations: ```bash # Display help for the capture group omarchy capture --help # Take a screenshot with smart copy enabled omarchy capture screenshot smart copy # List installed fonts omarchy font list # Run a full system update via the package manager omarchy update ``` All sub-commands support the `--help` flag for detailed usage information, consistent with the documentation in [`manual/14-omarchy-cli.md`](https://github.com/omacom/omarchy/blob/main/manual/14-omarchy-cli.md). ## Summary - The Omarchy CLI consists of a dispatcher (`bin/omarchy`) and helper scripts (`omarchy-*`) requiring no compilation. - **Local setup requires three elements**: the cloned repository, the `OMARCHY_PATH` environment variable pointing to the repository root, and the `bin` directory added to `PATH`. - The `GROUP_DESCRIPTIONS` table inside `bin/omarchy` defines how commands route to specific helper scripts. - For permanent access, modify your shell profile (`~/.bashrc`) or create a system-wide symlink to the dispatcher. - All documentation resides in [`manual/14-omarchy-cli.md`](https://github.com/omacom/omarchy/blob/main/manual/14-omarchy-cli.md) within the repository. ## Frequently Asked Questions ### Do I need to compile anything to run the Omarchy CLI locally? No. The Omarchy CLI is implemented entirely in Bash. The `bin/omarchy` dispatcher and all `omarchy-*` helper scripts are plain text executables that require only a Bash interpreter and the `OMARCHY_PATH` variable to function. ### What happens if `OMARCHY_PATH` is not set? Without the `OMARCHY_PATH` environment variable, the main dispatcher at `bin/omarchy` cannot locate the repository root or resolve paths to individual command scripts. This results in "command not found" errors or failed script execution, even if the `bin` directory is in your `PATH`. ### Where are individual CLI commands implemented? Each command is implemented as a separate executable script in the `bin` directory, following the naming convention `omarchy--`. For example, the `theme list` command maps to `bin/omarchy-theme-list`, while system updates execute `bin/omarchy-update`. The dispatcher references these through the `GROUP_DESCRIPTIONS` table defined in `bin/omarchy`. ### How can I list all available commands in the Omarchy CLI? Run `omarchy commands --list` to display all available groups and actions. This command queries the internal command table built from the `GROUP_DESCRIPTIONS` array and scans the `bin` directory for matching `omarchy-*` executables.