How to Set Up the Omarchy CLI Locally: A Complete Installation Guide

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

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:

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:

omarchy --help
omarchy commands --list

These commands should display the top-level help text (documented in manual/14-omarchy-cli.md) and enumerate all available command groups. Test a specific group to ensure helper scripts resolve correctly:

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:

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:

source ~/.bashrc

System-Wide Symlink

Alternatively, create a symbolic link to the main dispatcher in a directory already on your system PATH:

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-<group>-<action>.

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:

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

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 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-<group>-<action>. 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.

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