How to Run Omarchy Commands Without Installation: A Complete Guide

You can run Omarchy commands directly from a repository checkout by invoking the bin/omarchy driver script or adding the bin/ directory to your PATH, no system installation required.

The Omarchy distribution provides a powerful command-line interface for managing screenshots, themes, and system toggles. According to the omacom/omarchy source code, the entire CLI is implemented as a self-contained Bash driver that discovers commands at runtime, allowing you to run omarchy commands without installation on any Linux system with Bash.

Understanding the Self-Contained CLI Driver

The heart of Omarchy's portability lies in bin/omarchy, a single Bash script that functions as the command dispatcher. As implemented in omacom/omarchy, this driver computes its own location at runtime using:

OMARCHY_BIN_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)

This path detection allows the driver to locate sibling scripts in the same bin/ directory regardless of where you run it from.

The driver automatically registers every executable file prefixed with omarchy- by reading the first approximately 80 lines of each script to extract metadata. It builds internal routing tables including COMMAND_ROUTE and GROUP_DESCRIPTIONS to map user input to concrete binaries. When you execute omarchy capture screenshot, the driver resolves the route and execs bin/omarchy-capture-screenshot directly.

Running Commands Without System Installation

You can execute Omarchy utilities immediately after cloning the repository. The process requires no root privileges or permanent system modifications.

Clone and Prepare the Repository

First, obtain the source and ensure the driver has execute permissions:

git clone https://github.com/omacom/omarchy.git
cd omarchy/quattro
chmod +x bin/omarchy

Method 1: Execute via Relative Path

Invoke the driver directly using its relative path:

./bin/omarchy capture screenshot smart
./bin/omarchy theme list
./bin/omarchy toggle nightlight on

Method 2: Add bin Directory to PATH

For a more natural workflow that mimics an installed system, prepend the bin/ directory to your PATH:

export PATH=$PWD/bin:$PATH
omarchy update --check
omarchy theme list

Direct Binary Execution as an Alternative

While the driver provides routing and help functionality, you can bypass it entirely by calling concrete binaries directly:

bin/omarchy-capture-screenshot smart

However, using the driver (bin/omarchy) is recommended because it handles argument routing, help flags (--help), and group-level documentation automatically. The driver also manages the COMMAND_ROUTE logic that connects high-level commands like capture screenshot to their implementation scripts.

Key Source Files and Architecture

According to the omacom/omarchy source code, several files define this architecture:

• bin/omarchy: The core CLI driver containing the register_route and register_command functions that parse metadata and build command maps.
• bin/omarchy-<group>-<command>: Individual command implementations (e.g., bin/omarchy-capture-screenshot) that the driver executes.
• manual/14-omarchy-cli.md: Documentation covering the CLI usage patterns and group hierarchies.

The driver's registration logic scans the first 200 lines of each binary to extract usage information, enabling the help system to display command summaries without executing the target scripts.

Summary

• You can run omarchy commands without installation by cloning the repository and invoking bin/omarchy directly.
• The driver uses runtime path detection (OMARCHY_BIN_DIR) to locate commands regardless of execution location.
• Two invocation methods work: relative path execution (./bin/omarchy) or PATH modification.
• Individual binaries follow the pattern bin/omarchy-<group>-<command> and can be called directly, though the driver provides better tooling.
• No external dependencies beyond standard Bash are required.

Frequently Asked Questions

Do I need to install Omarchy to use the CLI tools?

No. The CLI is fully functional from a repository checkout. The bin/omarchy driver discovers and dispatches commands at runtime using relative path detection, eliminating the need for system-wide installation or package manager setup.

How does the omarchy driver find its commands?

The driver computes its location via $(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd), then registers every omarchy-* script in the same directory. It uses the register_command function to parse the first ~80 lines of each binary for metadata, building the COMMAND_ROUTE table that maps group/command inputs to executable paths.

Can I run specific binaries directly without the driver?

Yes. You can execute concrete binaries like bin/omarchy-capture-screenshot or bin/omarchy-theme-list directly. However, the driver provides essential functionality including argument validation, help text generation, and group-level routing that standalone binaries lack.

What dependencies are required to run commands?

Only a standard Bash environment present on any modern Linux distribution. The driver and all command binaries are self-contained shell scripts with no external package dependencies, making them portable across different systems without installation.

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