# What Is the `--` Separator in Omarchy CLI Commands?

> Understand the Omarchy CLI -- separator. It separates wrapper script arguments from underlying component arguments like qs IPC client. Learn its purpose now.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: internals
- Published: 2026-08-25

---

**The double-dash `--` in Omarchy CLI commands serves as a boundary marker that distinguishes wrapper script arguments from arguments intended for underlying components like the `qs` IPC client.**

In the `basecamp/omarchy` repository, the CLI wrapper scripts rely on a POSIX-standard convention to handle argument parsing safely. Understanding how this separator functions is essential for passing flags, JSON payloads, and option-like values to downstream commands without interference from the Omarchy helper scripts.

## Core Purpose of the `--` Separator

According to the source code in `bin/omarchy-shell`, the `--` acts as a **sentinel value** that halts option parsing for the wrapper. Everything following the separator is treated as positional arguments for the target command, ensuring reliable forwarding to tools like the `qs` IPC client or menu utilities.

### Protecting Option Parsing

Omarchy’s wrapper scripts parse leading flags such as `-q` for quiet mode. Without a separator, arguments like `--width 520` or `-v` would be consumed by the wrapper instead of being passed to the menu UI or IPC client. The `--` marker **preserves these as positional arguments** for the underlying component.

### Disambiguating Function Names

Some Omarchy commands shadow `qs` sub-commands. For example, a function named `show` could be misinterpreted as a `qs` option. Inserting `--` before the actual arguments ensures these names remain ordinary arguments rather than being parsed as option flags for the wrapper.

### Consistent Convention Across Commands

Higher-level Omarchy utilities follow the same pattern. The `omarchy-menu-select` command uses the separator to distinguish between selection options and menu UI configuration, as implemented in `bin/omarchy-menu-select`.

## Practical Examples of `--` Usage

Here are concrete patterns from the `basecamp/omarchy` codebase:

```bash

# Basic IPC call without separator

omarchy-shell shell ping

# Quiet mode flag parsed by omarchy-shell itself

omarchy-shell -q omarchy.indicators refresh

# JSON payload containing special characters

omarchy-shell shell toggle omarchy.menu '{"menu":"root"}'

# Forwarding menu-specific options using the separator

omarchy-menu-select "Select a theme" dark light -- --width 520 --maxheight 500

# Passing arguments that resemble qs options

omarchy-shell shell listPlugins -- --all

```

In the first three examples, `omarchy-shell` interprets the arguments directly. In the fourth and fifth examples, everything after `--` is handed unchanged to the menu system or `qs` command respectively.

## Implementation Across the Codebase

The separator logic is enforced and tested across several key files:

- **`bin/omarchy-shell`**: Contains the core forwarding logic and explicit comments explaining the `--` boundary marker.
- **`bin/omarchy-menu-select`**: Demonstrates separator usage for passing UI-specific flags to the underlying menu renderer.
- **`test/shell.d/*-test.sh`**: Test suites such as [`windows-vm-compose-test.sh`](https://github.com/basecamp/omarchy/blob/main/windows-vm-compose-test.sh) verify correct handling of `--` before compose flags.
- **`default/bash/completions`**: Completion logic parses `# omarchy:args=` metadata and respects the separator when generating shell completions.

## Summary

- The `--` separator acts as a **boundary marker** between Omarchy wrapper arguments and underlying command arguments.
- It **prevents accidental consumption** of flags by the wrapper script, ensuring options like `--width` reach their intended destination.
- The convention is implemented in **`bin/omarchy-shell`** and respected across the Omarchy CLI ecosystem, including menu commands and shell completions.
- Using `--` is essential when passing **JSON payloads**, **negative numbers**, or **flags** to IPC clients like `qs`.

## Frequently Asked Questions

### When must I use the `--` separator in Omarchy CLI commands?

Use the `--` separator whenever you need to pass arguments that start with `-` or `--` to the underlying command rather than to the Omarchy wrapper. This is required for passing configuration flags to menu UIs, JSON objects with leading dashes, or any option-like values to the `qs` IPC client.

### What happens if I omit the `--` separator when passing flags?

If you omit the separator, Omarchy’s wrapper scripts will attempt to parse the flags themselves. According to the implementation in `bin/omarchy-shell`, flags like `-q` are consumed by the wrapper for quiet mode, while unrecognized flags may cause errors or be discarded before reaching the target command.

### Does the `--` separator work with all Omarchy commands?

Most higher-level Omarchy commands that forward arguments to other tools support the `--` convention. The `omarchy-menu-select` utility explicitly uses this pattern, and the completion logic in `default/bash/completions` is designed to respect the separator when parsing command metadata.

### How does the separator handle JSON payloads in Omarchy?

JSON payloads that happen to start with a dash require the `--` separator to prevent the wrapper from interpreting them as option flags. By placing `--` before the JSON string, as shown in `omarchy-shell` examples, the payload is treated as a positional argument and passed intact to the underlying IPC client.