Omarchy CLI Tutorials: Complete Guide to Command-Line Usage and Automation

The Omarchy CLI includes comprehensive tutorials within its official manual at manual/14-omarchy-cli.md, supplemented by architectural documentation in docs/cli-router.md and docs/file-layout.md that explain how to script, automate, and extend the command-line interface.

The Omarchy CLI functions as the text-based entry point to the entire Omarchy ecosystem, exposing every internal tool that powers the graphical menu, hot-keys, and background services. These omarchy CLI tutorials cover both user-facing commands and the underlying routing logic implemented in the source code. Whether you need to capture screenshots, switch themes, or automate menu interactions, the documentation provides executable examples and architectural context to help you master the interface.

Getting Started with the Omarchy CLI

The primary tutorial resource resides in manual/14-omarchy-cli.md, which offers a quick-start overview, common command patterns, and practical examples for diving into command groups. According to the Omarchy source code, the CLI entry point is the bin/omarchy script, which parses the first argument as a group (such as capture, theme, or audio) and dispatches execution to the corresponding implementation under bin/.

To begin exploring the available functionality:

# Display top-level help and list all command groups

omarchy --help

# List every available command as structured JSON for scripting

omarchy commands --json

Understanding CLI Architecture

The Omarchy CLI operates through a router system defined in docs/cli-router.md. This architecture treats the first argument as a group identifier, looking up descriptions in the GROUP_DESCRIPTIONS table within bin/omarchy before delegating to specific command implementations.

Command Routing and Groups

The router mechanism parses initial arguments to determine the target group, then routes to the appropriate handler under the bin/ directory. The GROUP_DESCRIPTIONS metadata table in the main bin/omarchy script defines available groups and their descriptions, while the command-metadata specification in agents/skills/command-metadata.md lists all supported operations.

Directory Structure and Environment

As documented in docs/file-layout.md, all CLI binaries reside in the bin/ directory and interact with the shared environment variable $OMARCHY_PATH. This layout ensures that individual command scripts can access the Omarchy environment consistently, whether invoked directly or through the router.

Practical Command Examples

The following executable examples demonstrate common operations covered in the official tutorials:

# Change the current theme to Nord

omarchy theme set nord

# Take a screenshot of the active window and copy to clipboard

omarchy capture screenshot windows copy

# Record fullscreen video with microphone audio

omarchy capture screenrecording --fullscreen --with-microphone-audio

# Open the Omarchy graphical menu from terminal

omarchy menu

# Jump directly to the theme picker via menu summon

omarchy menu summon style.theme

Each command follows the routing convention where omarchy <group> <action> maps to the corresponding implementation in bin/.

Official Tutorial Resources

The Omarchy repository maintains four primary documentation sources that constitute the official CLI tutorial set:

User Manual (manual/14-omarchy-cli.md)

This document provides the high-level tutorial content, including menu integration examples and the "Opening the menu from the terminal" section that explains how to script graphical interactions.

CLI Router Documentation (docs/cli-router.md)

This architectural guide explains how groups and sub-commands are resolved, how to add new commands to the system, and how the router delegates execution to specific binaries.

File Layout Reference (docs/file-layout.md)

This resource shows where CLI binaries live, how they use $OMARCHY_PATH, and how the directory structure supports the modular command architecture.

Command Metadata (agents/skills/command-metadata.md)

This file contains the canonical list of all command groups and their descriptions, serving as the reference for the GROUP_DESCRIPTIONS table used by the router in bin/omarchy.

Summary

• The Omarchy CLI tutorials are distributed across the user manual (manual/14-omarchy-cli.md), router documentation (docs/cli-router.md), and file layout guides (docs/file-layout.md) in the official repository.
• The CLI router in bin/omarchy parses the first argument as a group (e.g., capture, theme, audio) and dispatches to implementations under bin/ using the GROUP_DESCRIPTIONS metadata.
• Practical automation is supported through JSON command listing (omarchy commands --json) and scriptable menu access (omarchy menu summon).
• Environment configuration relies on $OMARCHY_PATH as documented in the file layout specification.

Frequently Asked Questions

How do I list all available omarchy CLI commands?

Use the omarchy commands helper with the --json flag to output structured data suitable for scripting. This command queries the command metadata and outputs every available group and sub-command defined in the router.

Where is the omarchy CLI entry point located?

The main entry point is bin/omarchy, which implements the routing logic and contains the GROUP_DESCRIPTIONS table. This script parses arguments and delegates to specific command implementations located in the bin/ directory.

Can I script the omarchy graphical menu from the terminal?

Yes. The omarchy menu command provides scriptable access to the graphical interface, allowing you to open the main menu or summon specific panels like the theme picker using omarchy menu summon style.theme.

How does omarchy route CLI arguments to specific commands?

According to docs/cli-router.md, the router treats the first argument as a group identifier (such as capture or theme), looks up the implementation in GROUP_DESCRIPTIONS within bin/omarchy, and executes the corresponding binary or function under the bin/ directory.

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