Proof Portal

Sign in
Project overview

Omarchy

ProbeLabs65 findings · 95 requirements

A proof layer — requirements, tests and verified fixes — for two of Omarchy's subsystems: the application menu (launcher scripts, QML model, JSONC config, search and selection) and the lock screen (lock scripts, QML, PAM authentication). Scope is deliberately limited to those components of omacom/omarchy; the rest of the distribution is not covered.

Inbox
ReportR-4571GitHub issuePublicReceived

`--help` is being skipped for bin routes that partially resolve to a file

Reported by EFrMG · filed Aug 13, 2026Closed upstream on 2026-08-13 by dhh. GitHub close reason: completed. No closing PR or commit is recorded — "completed" alone is not evidence of a fix.

Open at source
Received and recorded verbatim. Nothing has been checked yet.

At a glance

1 · What is claimed?
Only the report text below — no validator has restated it as checkable claims yet.
2 · What does it affect?
Not yet mapped to any requirement or component.
3 · Is it reproducible?
No validation has been run yet.
4 · What remains unclear?
  • Not validated yet: no claims, no reproducer.
5 · What happens next?
Our staff decide whether the report is valid. Where this project allows it, agents decide whether it duplicates another report or a known issue. No decision has been recorded yet.

Original report

`--help` is being skipped for bin routes that partially resolve to a filerevision 1 · captured 2026-10-04 12:03 UTC via poll

System details

Omarchy 4.0.0.alpha

What's wrong?

--help is silently skipped for routes that only partially resolve to a file.

For example:

omarchy update aur --help    # does NOT show help: it starts a real update

omarchy-update-aur doesn't exist as a binary (only omarchy-update-aur-pkgs does), so update aur only resolves as far as the omarchy-update binary, leaving aur --help as leftover args. The router only checked the first leftover token for --help/-h; since that token is aur, the check never fires, and both aur and --help get forwarded straight into omarchy-update. omarchy-update treats any first arg other than -y as "not skip confirmation" and falls through into omarchy-update-confirm, this being that it enters the update flow instead of printing help.

This isn't specific to aur, as it affects any group with a bare parent binary (omarchy-<group>) where the typed subcommand doesn't match a real child binary, and the trailing --help isn't the immediate next token after where the router actually resolved a real command.

Fix

In bin/omarchy, added remaining_has_help_flag(), which scans the entire leftover argument list for --help/-h instead of only checking index 0. Both dispatch paths (dispatch_fast_or_help and dispatch_or_help) now use it before deciding whether to forward args to the resolved binary as well.

This is a targeted fix: it guarantees --help is never silently forwarded into a real command.

It does not change behavior for a typo without --help, so omarchy update aur alone still forwards to omarchy-update which is a separate, broader change (rejecting unrecognized subcommands outright). That would need a way to distinguish commands with a closed subcommand vocabulary (update, reinstall) from ones that intentionally take freeform positional args (hook <name>, toggle <flag-name>), so it is left out of the following PR.

Testing

  • ./test/cli: 105/105 passing.
  • Manual verification:
  • omarchy update aur --help: now shows update command help and its related commands, instead of starting a real update.
  • omarchy update -y --help: --help still wins even with a real flag ahead of it.
  • omarchy theme list --help: unaffected, confirming that exact-match routes still work as before.
View raw text
### System details

Omarchy 4.0.0.alpha

### What's wrong?


`--help` is silently skipped for routes that only partially resolve to a file.

For example:

```bash
omarchy update aur --help    # does NOT show help: it starts a real update
```

`omarchy-update-aur` doesn't exist as a binary (only `omarchy-update-aur-pkgs` does), so `update aur` only resolves as far as the `omarchy-update` binary, leaving `aur --help` as leftover args. The router only checked the *first* leftover token for `--help`/`-h`; since that token is `aur`, the check never fires, and both `aur` and `--help` get forwarded straight into `omarchy-update`. `omarchy-update` treats any first arg other than `-y` as "not skip confirmation" and falls through into `omarchy-update-confirm`, this being that it enters the update flow instead of printing help.

This isn't specific to `aur`, as it affects any group with a bare parent binary (`omarchy-<group>`) where the typed subcommand doesn't match a real child binary, and the trailing `--help` isn't the immediate next token after where the router actually resolved a real command.

## Fix

In `bin/omarchy`, added `remaining_has_help_flag()`, which scans the **entire** leftover argument list for `--help`/`-h` instead of only checking index 0. Both dispatch paths (`dispatch_fast_or_help` and `dispatch_or_help`) now use it before deciding whether to forward args to the resolved binary as well.

This is a targeted fix: it guarantees `--help` is never silently forwarded into a real command.

It does not change behavior for a typo without `--help`, so `omarchy update aur` alone **still** forwards to `omarchy-update` which is a separate, broader change (rejecting unrecognized subcommands outright). That would need a way to distinguish commands with a closed subcommand vocabulary (`update`, `reinstall`) from ones that intentionally take freeform positional args (`hook <name>`, `toggle <flag-name>`), so it is left out of the following PR.

## Testing

- `./test/cli`: 105/105 passing.

- Manual verification:
  - `omarchy update aur --help`: now shows `update` command help and its related commands, instead of starting a real update.
  - `omarchy update -y --help`: `--help` still wins even with a real flag ahead of it.
  - `omarchy theme list --help`: unaffected, confirming that exact-match routes still work as before.

Validation

Not checked yet. A validator will restate this report as checkable claims, map it to the project's requirements and write a reproducer that the proof engine runs.

Linked

Not linked to any known issue, other report or change yet.

Decision

Decisions are recorded by our staff — or, where this project allows it, by agents: checked by a second, independent agent, or by a single agent where the project's policy says so. Any decision reached so far is shown below.

No decision has been recorded yet.