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

> Explore Omarchy CLI tutorials to master command-line usage and automation. This guide details scripting, automation, and extension of the omacom/omarchy CLI.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: tutorial
- Published: 2026-09-12

---

**The Omarchy CLI includes comprehensive tutorials within its official manual at [`manual/14-omarchy-cli.md`](https://github.com/omacom/omarchy/blob/main/manual/14-omarchy-cli.md), supplemented by architectural documentation in [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md) and [`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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:

```bash

# 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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/agents/skills/command-metadata.md) lists all supported operations.

### Directory Structure and Environment

As documented in [`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/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:

```bash

# 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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/manual/14-omarchy-cli.md)), router documentation ([`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md)), and file layout guides ([`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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.