How to Check If a Command Exists in Omarchy: A Complete Guide to `omarchy-cmd-present` and `omarchy-cmd-missing`

Omarchy provides two dedicated helper binaries—omarchy-cmd-present and omarchy-cmd-missing—that wrap standard shell command lookups and return reliable exit codes for scripts, migrations, and tests.

To check if a command exists in Omarchy, you use specialized wrapper scripts located in the bin/ directory. These helpers eliminate the need for raw command -v calls scattered throughout your codebase, providing a consistent, testable interface for verifying command availability. This article explains exactly how these tools work, where they're defined, and how Omarchy's own codebase uses them.

How Omarchy's Command Check Helpers Work

Omarchy ships two approximately 10-line Bash scripts that iterate over arguments and run command -v "$cmd" internally. Because they reside in bin/, they're automatically available on $PATH inside any Omarchy environment.

omarchy-cmd-present: Verify All Commands Exist

Located at bin/omarchy-cmd-present, this helper checks that every command you specify is available.

Behavior	Exit Code
All arguments found as executable commands	0
Any argument missing or not executable	1

omarchy-cmd-missing: Detect Missing Commands

Located at bin/omarchy-cmd-missing, this helper checks if any command you specify is unavailable.

Behavior	Exit Code
At least one argument is missing	0
All arguments present	1

This inverted logic proves especially useful in migration scripts where you want to trigger installation only when a dependency is absent.

Practical Code Examples

Below are exact patterns drawn from the Omarchy source tree, demonstrating how to check if a command exists in real scenarios.

Require Multiple Commands Before Proceeding

#!/bin/bash

# Abort if any required tool is missing

required_cmds=(git jq curl)

if ! omarchy-cmd-present "${required_cmds[@]}"; then
  omarchy-notification-send "Missing required tools"
  exit 1
fi

# Safe to proceed—all commands verified present

git fetch origin
jq '.version' package.json
curl -s https://api.example.com/status

This pattern appears in runtime scripts throughout Omarchy, often combined with omarchy-notification-send to surface failures to the user.

Conditional Execution Based on Optional Tools

#!/bin/bash

# Perform step only when TLP power management is available

if omarchy-cmd-present tlp; then
  tlp-stat --battery
else
  echo "TLP not installed – skipping power-management stats"
fi

Defensive checks like this prevent scripts from failing on systems where optional components aren't installed.

Migration Scripts: Install Missing Dependencies

The file migrations/1786719479.sh demonstrates omarchy-cmd-missing in production:

#!/bin/bash

# Migration: Ensure AGY is installed

if omarchy-cmd-missing agy; then
  echo "Installing AGY because it is not present"
  # ...installation logic follows...

  omarchy-package-install agy
fi

# Continue with AGY-dependent configuration

agy --configure defaults

Migrations use omarchy-cmd-missing because they specifically want to act when something is not present—the helper's 0 exit code signals "work needed."

Test Suite: Stubbing Helper Behavior

In test/shell.d/vscode-theme-test.sh and similar test files, Omarchy verifies fallback logic by replacing the helper:

#!/bin/bash

# Create fake helper that simulates missing command

cat >"$FAKE_BIN/omarchy-cmd-present" <<'EOF'
#!/bin/bash
exit 1    # Pretend command is missing

EOF
chmod +x "$FAKE_BIN/omarchy-cmd-present"

# Prepend fake bin to PATH

export PATH="$FAKE_BIN:$PATH"

# Run script under test—it should take the missing-command branch

./under-test.sh

# Assert expected fallback behavior occurred

This stubbing technique lets tests exercise error paths without actually uninstalling system tools.

Key Source Files and Their Roles

File Path	Purpose
bin/omarchy-cmd-present	Core helper—exits 0 only when all arguments are found
bin/omarchy-cmd-missing	Core helper—exits 0 when any argument is missing
agents/skills/command-metadata.md	Official documentation of helper conventions and recommended usage
migrations/1786719479.sh	Production example of omarchy-cmd-missing in migration scripts
test/shell.d/vscode-theme-test.sh	Test suite demonstrating helper stubbing patterns

Why Omarchy Uses Dedicated Helpers Instead of Raw command -v

The Omarchy source code deliberately avoids inline command -v checks for several architectural reasons:

• Centralized behavior changes: Logging, debugging output, or platform-specific adjustments require editing one file, not dozens.
• Consistent exit codes: Shell scripts avoid ambiguity—0 always means success, with clear semantics per helper.
• Testability: Replacing a named binary is simpler than intercepting shell builtins.
• Self-documenting code: omarchy-cmd-present docker reads more clearly than nested if conditions with &>/dev/null redirections.

This design mirrors Omarchy's broader philosophy of small, composable tools that do one thing predictably.

Summary

• Use omarchy-cmd-present when your script requires specific tools and must fail gracefully (or abort) when they're missing.
• Use omarchy-cmd-missing when you want to detect absence and take action—common in migrations and optional feature detection.
• Both helpers are located in bin/ and automatically available on $PATH in Omarchy environments.
• Exit codes follow a strict contract: 0 for the condition described by the helper name, 1 otherwise.
• The implementation in bin/omarchy-cmd-present and bin/omarchy-cmd-missing is intentionally minimal (~10 lines of Bash) for transparency and reliability.

Frequently Asked Questions

How do I check if a single command exists in Omarchy?

Call omarchy-cmd-present with one argument. It exits 0 if the command exists, 1 otherwise:

if omarchy-cmd-present fzf; then
  echo "fzf is available"
fi

What's the difference between omarchy-cmd-present and omarchy-cmd-missing?

omarchy-cmd-present succeeds (exit 0) only when all listed commands are found. omarchy-cmd-missing succeeds when any listed command is absent. They're logical opposites designed for different use cases—requirement checking versus missing-dependency detection.

Can I use these helpers outside of Omarchy?

You can copy bin/omarchy-cmd-present and bin/omarchy-cmd-missing to any system with Bash. They're self-contained scripts with no Omarchy-specific dependencies. However, they're optimized for Omarchy's $PATH structure and notification integration.

How does Omarchy test command existence checks?

Tests in test/shell.d/ stub the helpers by creating fake binaries that exit with predetermined codes. This avoids modifying the actual system state while still exercising all code branches in scripts under test.

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