# How to Add a New Hardware Detection Command (hw-* Prefix) in Omarchy > Easily add custom hardware detection commands with the hw-* prefix in Omarchy. Create a bash script in bin/ to integrate new hardware detection. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: how-to-guide - Published: 2026-09-13 --- **To add a new hardware detection command in Omarchy, create an executable bash script named `omarchy-hw-` in the `bin/` directory that returns exit code 0 when hardware is present and non-zero when absent, optionally using `# omarchy:hidden=true` to hide it from the help menu.** Omarchy’s hardware detection system uses a strict naming convention and automatic discovery mechanism to expose device checks through the CLI. Any executable script prefixed with `omarchy-hw-` in the repository’s `bin/` folder is automatically recognized by the command router and integrated into the hardware section of the Omarchy menu without manual registration. ## Understanding the Omarchy Hardware Command Convention The hardware detection framework in `omacom/omarchy` follows a predictable pattern based on **file naming**, **exit codes**, and **executable permissions**. Commands must reside in the `bin/` directory and follow the naming template `omarchy-hw-`, where `` describes the hardware component being detected. The CLI routing logic inspects the `bin/` directory for executables beginning with `omarchy-`. When a user runs `omarchy hw-`, the system invokes the corresponding `bin/omarchy-hw-` script. The command’s visibility in the interactive menu depends on a special metadata comment: adding `# omarchy:hidden=true` anywhere in the script hides it from the help menu, while omitting this line makes it appear automatically in the **Hardware** group. ## Step-by-Step Implementation Guide ### Create the Detection Script Start by creating a new file in the `bin/` directory using the required naming convention. The script must use `#!/usr/bin/env bash` as its shebang and be made executable immediately. ```bash touch bin/omarchy-hw-mydevice chmod +x bin/omarchy-hw-mydevice ``` Open the file and add a descriptive header comment explaining what hardware the command detects. This documentation aids both users and maintainers browsing the source code. ### Implement Detection Logic and Exit Codes The detection logic relies on **exit codes** to communicate hardware presence. Return **exit code 0** when the hardware is detected, and any non-zero value when it is absent. Common detection methods include checking `/sys` or `/dev` entries, or using utilities like `lspci`, `lsusb`, or `vulkaninfo`. ```bash #!/usr/bin/env bash # omarchy-hw-mydevice # Detects whether the proprietary MyDevice USB dongle is attached. # # Exit codes: # 0 – device present # 1 – device not present if lsusb -d 1234:5678 >/dev/null 2>&1; then exit 0 else exit 1 fi ``` ### Add Metadata for Menu Visibility Control whether your command appears in the Omarchy menu by adding or omitting the hidden metadata tag. To hide the command from the help menu while keeping it callable via CLI, include: ```bash # omarchy:hidden=true ``` Place this comment anywhere in the script, typically near the top with other metadata. If you want users to discover the command through the interactive menu, leave this line out entirely. ### Write Automated Tests Every hardware command should have a corresponding test in `test/shell.d/`. Create a test script named `hw--test.sh` that sources the base test framework and asserts the expected exit status. ```bash #!/usr/bin/env bash # SPDX-License-Identifier: MIT # Test for omarchy-hw-mydevice source "$(dirname "$0")/base-test.sh" omarchy hw-mydevice status=$? assert_eq "$status" 0 "mydevice should be detected" ``` Make the test executable and run the full suite with `./test/shell` to verify integration. ## Complete Code Examples ### Sample Hardware Detection Script Here is a complete reference implementation for detecting a USB webcam, following the pattern used in `bin/omarchy-hw-webcam`: ```bash #!/usr/bin/env bash # omarchy-hw-webcam # Detects whether a video4linux webcam is present. # # Exit codes: # 0 – webcam found # 1 – no webcam detected [[ -e /dev/video0 ]] && exit 0 || exit 1 ``` ### Sample Test Implementation Corresponding test file at [`test/shell.d/hw-webcam-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/hw-webcam-test.sh): ```bash #!/usr/bin/env bash # SPDX-License-Identifier: MIT # Test for omarchy-hw-webcam source "$(dirname "$0")/base-test.sh" omarchy hw-webcam status=$? assert_eq "$status" 0 "Webcam should be present in test environment" ``` ### Adding the Script to the Repository Use the following commands to stage and commit your new hardware detection command: ```bash git add bin/omarchy-hw-mydevice git add test/shell.d/hw-mydevice-test.sh git commit -m "Add hardware detection for MyDevice USB dongle" ``` ## Integration and Testing Once placed in `bin/` with executable permissions, the new command integrates automatically. The Omarchy menu system scans for `omarchy-hw-*` patterns during initialization, populating the **Hardware** group with any non-hidden commands. No manual menu configuration is required in [`docs/menu.md`](https://github.com/omacom/omarchy/blob/main/docs/menu.md) or elsewhere. Run the shell test suite to confirm your implementation does not break existing detections: ```bash ./test/shell ``` The test harness will execute [`hw-mydevice-test.sh`](https://github.com/omacom/omarchy/blob/main/hw-mydevice-test.sh) and report any assertion failures or integration errors. ## Key Files and References - **`bin/omarchy-hw-webcam`** – Reference implementation for video device detection - **`bin/omarchy-hw-vulkan`** – Reference implementation for GPU driver detection using Vulkan utilities - **[`test/shell.d/hw-webcam-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/hw-webcam-test.sh)** – Example test harness showing assertion patterns for hardware commands - **[`docs/menu.md`](https://github.com/omacom/omarchy/blob/main/docs/menu.md)** – Documentation describing how commands are exposed in the Omarchy menu system - **[`agents/skills/command-metadata.md`](https://github.com/omacom/omarchy/blob/main/agents/skills/command-metadata.md)** – Guidelines for command script metadata and naming conventions ## Summary - **Naming**: Use `bin/omarchy-hw-` for all hardware detection scripts - **Permissions**: Ensure files are executable (`chmod +x`) for discovery to work - **Exit Codes**: Return 0 for hardware present, non-zero for absent - **Visibility**: Add `# omarchy:hidden=true` to hide commands from the menu - **Testing**: Create corresponding tests in `test/shell.d/hw--test.sh` - **Discovery**: Commands appear automatically in the Hardware group; no manual registration needed ## Frequently Asked Questions ### What exit code should my hardware detection command return? Return **exit code 0** when the hardware is detected and any non-zero integer (typically 1) when it is not present. Omarchy’s CLI interprets zero as success (hardware available) and non-zero as failure (hardware unavailable). ### Can I use any programming language for the detection script? While the examples use **bash**, any executable script will work provided it follows the `omarchy-hw-` naming convention, has proper execute permissions, and returns the correct exit codes. However, the existing codebase uses bash consistently for hardware detection. ### How do I hide a hardware command from the interactive menu? Add the comment `# omarchy:hidden=true` anywhere in the script. This metadata tag prevents the command from appearing in the Omarchy help menu while keeping it callable directly via `omarchy hw-`. ### Where should I place tests for my new hardware command? Create a test file named `hw--test.sh` in the `test/shell.d/` directory. Source [`base-test.sh`](https://github.com/omacom/omarchy/blob/main/base-test.sh) and use assertions to verify exit codes, following the pattern established in [`test/shell.d/hw-webcam-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/hw-webcam-test.sh).