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

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:

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

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