> ## Documentation Index
> Fetch the complete documentation index at: https://docs.badgeify.app/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Integration

> Control and monitor Badgeify programmatically using the command-line interface

<Warning>
  **Version Requirement**: CLI automation is only available in Badgeify version 1.9.2 and later.
  Please update to the latest version if you're running an older release.
</Warning>

# Badgeify Command-Line Interface

Badgeify bundles a lightweight CLI inside the desktop binary so automations can inspect notification badges without launching the UI. Run the `badgeify` executable with one of the supported subcommands to query state and exit immediately.

```bash theme={null}
badgeify <subcommand> [options]
```

The process prints a JSON payload to stdout and terminates with exit code `0` on success and `1` on error. Errors are emitted on stderr.

## Installation & Setup

### Locating the CLI Executable

After installing Badgeify via the dmg, the CLI executable is bundled inside the application package at:

```bash theme={null}
/Applications/Badgeify.app/Contents/MacOS/Badgeify
```

### Making the CLI Accessible

You have several options to use the CLI conveniently:

**Option 1: Create an alias (Recommended)**

Add this line to your shell configuration file (`~/.zshrc` for zsh or `~/.bashrc` for bash):

```bash theme={null}
alias badgeify="/Applications/Badgeify.app/Contents/MacOS/Badgeify"
```

Then reload your shell configuration:

```bash theme={null}
source ~/.zshrc  # or source ~/.bashrc
```

**Option 2: Create a symbolic link**

```bash theme={null}
sudo ln -s /Applications/Badgeify.app/Contents/MacOS/Badgeify /usr/local/bin/badgeify
```

**Option 3: Use the full path**

You can always invoke the CLI using the complete path without any setup:

```bash theme={null}
/Applications/Badgeify.app/Contents/MacOS/Badgeify list
```

### Verify Installation

Test that the CLI is accessible by running:

```bash theme={null}
badgeify --help  # if using alias or symlink
# or
/Applications/Badgeify.app/Contents/MacOS/Badgeify --help
```

## Prerequisites

* Badgeify must already be configured with the apps or groups you want to monitor.
* macOS accessibility permissions are required. If the CLI fails with a `NO_PERMISSIONS` error, grant access via **System Settings → Privacy & Security → Accessibility** and relaunch Badgeify once to register the permission.

## Discover Available IDs

Use `list` to retrieve the apps and groups that can be queried. Each entry exposes an `id`, `type`, `name`, and whether it is currently enabled.

<Note>
  The following examples use `badgeify` as the command. If you haven't set up an alias or symlink, replace `badgeify` with the full path `/Applications/Badgeify.app/Contents/MacOS/Badgeify`.
</Note>

```bash theme={null}
$ badgeify list
{"success":true,"data":[{"id":"com.apple.Mail","type":"app","name":"Mail"}]}
```

The `id` field becomes the argument for other subcommands.

> **Free tier note:** Without an active license, only the first three configured items are returned.

## Query Unread Status

Fetch the current menubar badge for a specific app or group with `status` and the `--id` flag.

```bash theme={null}
$ badgeify status --id com.apple.Mail
{"success":true,"data":{"type":"app","id":"com.apple.Mail","name":"Mail","enabled":true,"isRunning":true,"shown":true,"unread":5,"statusLabel":"5"}}
```

Important fields:

* `unread` – integer badge count (0 when cleared).
* `statusLabel` – raw menubar badge text (mirrors what macOS reports).
* `shown` – whether the item is currently visible in the Badgeify tray.
* `isRunning` – whether the underlying app is running right now.

If the requested ID is unknown, the CLI returns a `NOT_FOUND` error:

```bash theme={null}
$ badgeify status --id unknown
{"success":false,"error":{"code":"NOT_FOUND","message":"No app or group found with ID: unknown","details":{"requestedId":"unknown"}}}
```

> **Free tier note:** For unlicensed users, `status` is limited to the first three configured items and returns a `FORBIDDEN` error for others.

## Exit Codes

* `0` – Command succeeded and JSON was printed to stdout.
* `1` – Validation, permission, or runtime error; JSON error payload printed to stderr.

## Automation Tips

* The CLI sets the `BADGEIFY_CLI_MODE=1` environment variable while running. You can detect this flag inside scripts if needed.
* Poll `badgeify status --id <bundle>` on an interval to react to badge changes from tools like Hammerspoon.
* Parse stdout as JSON to inspect `unread`. For shell scripting, tools such as `jq` make it easy:
  ```bash theme={null}
  badgeify status --id com.apple.Mail | jq '.data.unread'
  ```

## Troubleshooting

| Symptom                             | Likely Cause                                                        | Resolution                                                                                   |
| ----------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `NO_PERMISSIONS` error              | Accessibility access not granted                                    | Open System Settings, add Badgeify to Accessibility, relaunch the app                        |
| CLI exits without printing JSON     | Command failed before reaching the handler                          | Re-run with `badgeify --help` to verify syntax; check stderr for the error payload           |
| Badge count differs from macOS dock | The monitored app may suppress menubar badges or accessibility APIs | Confirm the badge appears in the macOS menu bar. Badgeify reports exactly what macOS exposes |

## Getting Help

If the CLI output looks incorrect or you encounter issues not covered here, please capture the command output and email [support@badgeify.app](mailto:support@badgeify.app) so we can investigate.