{"id":13523584,"url":"https://github.com/vjeantet/alerter","last_synced_at":"2026-02-19T20:00:51.067Z","repository":{"id":44364924,"uuid":"48335712","full_name":"vjeantet/alerter","owner":"vjeantet","description":"Send User Alert Notification on Mac OS X from the command-line.","archived":false,"fork":false,"pushed_at":"2026-02-16T17:54:46.000Z","size":567,"stargazers_count":1032,"open_issues_count":3,"forks_count":66,"subscribers_count":37,"default_branch":"master","last_synced_at":"2026-02-16T21:31:37.942Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vjeantet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null},"funding":{"github":"vjeantet","open_collective":"macos-alerter"}},"created_at":"2015-12-20T20:16:02.000Z","updated_at":"2026-02-16T17:54:50.000Z","dependencies_parsed_at":"2023-09-23T14:35:24.548Z","dependency_job_id":null,"html_url":"https://github.com/vjeantet/alerter","commit_stats":{"total_commits":33,"total_committers":6,"mean_commits":5.5,"dds":"0.24242424242424243","last_synced_commit":"0a654d1e38b7aeb94242757a84354b111dd1f6cf"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/vjeantet/alerter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vjeantet%2Falerter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vjeantet%2Falerter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vjeantet%2Falerter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vjeantet%2Falerter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vjeantet","download_url":"https://codeload.github.com/vjeantet/alerter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vjeantet%2Falerter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29629630,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T18:02:07.722Z","status":"ssl_error","status_checked_at":"2026-02-19T18:01:46.144Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T06:01:01.551Z","updated_at":"2026-02-19T20:00:51.050Z","avatar_url":"https://github.com/vjeantet.png","language":"Swift","funding_links":["https://github.com/sponsors/vjeantet","https://opencollective.com/macos-alerter"],"categories":["Command Line","Objective-C"],"sub_categories":["Dependency Management"],"readme":"# Alerter\n\nAlerter is a command-line tool for sending macOS notifications (alerts), built with Swift and Swift Package Manager.\nThe program exits when the user interacts with the alert or when it is dismissed, printing the result to stdout as plain text or JSON.\n\nAlerts are macOS notifications that stay on screen until dismissed. Requires macOS 13.0 or later.\n\nTwo kinds of alerts can be triggered: **Reply Alert** and **Actions Alert**.\n\n\u003e [!IMPORTANT]\n\u003e **Version 26.xxx** — Alerter has been completely rewritten in Swift with the Swift Package Manager. \\\n\u003e The CLI syntax now uses double dashes (--message, --title, --json...) and installation is done via Homebrew: `brew install vjeantet/tap/alerter`. \\\n\u003e See the [release notes](docs/release-notes-26.2.md) for all the details.\n\n\n## Reply alert\nDisplays a notification with a \"Reply\" button that opens a text input field.\n\n## Actions alert\nDisplays a notification with one or more action buttons to click on.\n\n## Features\n* Set the alert icon, title, subtitle, and image.\n* Capture text typed by the user in reply-type alerts.\n* Delay: defer notification delivery by a given number of seconds.\n* Schedule: deliver a notification at a specific time (HH:mm or yyyy-MM-dd HH:mm).\n* Timeout: automatically close the alert after a delay.\n* Customize the close button label.\n* Customize the actions dropdown label.\n* Play a sound when delivering the notification.\n* Plain text or JSON output for alert events (closed, timeout, replied, activated, etc.).\n* Ignore Do Not Disturb mode.\n* Gracefully close the notification on SIGINT and SIGTERM.\n\n## Installation\n\n### Homebrew (recommended)\n\n```bash\nbrew install vjeantet/tap/alerter\n```\n\n### MacPorts\n\n```bash\nsudo port install alerter\n```\n\n### Manual\n\n1. Download the zipped precompiled binary from the\n[releases section](https://github.com/vjeantet/alerter/releases).\n2. Extract the binary.\n3. Place it in a directory listed in your `$PATH` (e.g. `/usr/local/bin`).\n\n### Build from source\n\n```bash\ngit clone https://github.com/vjeantet/alerter.git\ncd alerter\nswift build -c release\n# Binary is at .build/release/alerter\n```\n\n## Release workflow\n\nVersioning uses the format `YY.N` (e.g. `26.1`, `26.2`). The version is bumped automatically.\n\n```\n1. ./scripts/release.sh                    # bump version, build, sign, notarize, tag, GitHub Release\n2. ./scripts/update-homebrew-formula.sh     # update formula in vjeantet/homebrew-tap\n3. ./scripts/update-macports-portfile.sh    # update local macports/Portfile, then submit PR to macports-ports\n```\n\n## Usage\n\n```\n$ ./alerter --message|--group|--list [VALUE|ID|ID] [options]\n```\n\nExamples:\n\nDisplay piped data with a sound\n\n```\n$ echo 'Piped Message Data!' | alerter --sound default\n```\n\n![Display piped data with a sound](/img1.png?raw=true \"\")\n\nMultiple actions and custom dropdown list\n```\n./alerter --message \"Deploy now on UAT ?\" --actions \"Now,Later today,Tomorrow\" --dropdownLabel \"When ?\"\n```\n\n![Multiple actions and custom dropdown list](/img2.png?raw=true \"\")\n\nYes or No?\n```\n./alerter --title ProjectX --subtitle \"new tag detected\" --message \"Deploy now on UAT ?\" --closeLabel No --actions Yes --appIcon http://vjeantet.fr/images/logo.png\n```\n\n![Yes or No](/img3.png?raw=true \"\")\n\nWhat is the name of this release?\n```\n./alerter --reply \"Type release name\" --message \"What is the name of this release?\" --title \"Deploy in progress...\"\n```\n\n![What is the name of this release](/img4.png?raw=true \"\")\n\n## Options\n\nAt a minimum, you must specify either `--message`, `--remove`, or `--list`.\n\n-------------------------------------------------------------------------------\n\n`--message VALUE`  **[required]**\n\nThe message body of the notification.\n\nNote that if this option is omitted and data is piped to the application, that\ndata will be used instead.\n\n-------------------------------------------------------------------------------\n\n`--reply TEXT`\n\nDisplays the notification as a reply-type alert. TEXT is used as placeholder text in the input field.\n\n-------------------------------------------------------------------------------\n\n`--actions VALUE1,VALUE2,\"VALUE 3\"`\n\nThe available notification actions.\nWhen more than one value is provided, a dropdown is displayed.\nYou can customize the dropdown label with the `--dropdownLabel` option.\nCannot be combined with `--reply`.\n\n-------------------------------------------------------------------------------\n\n`--dropdownLabel VALUE`\n\nThe label for the actions dropdown (only used when multiple `--actions` values are provided).\nCannot be combined with `--reply`.\n\n-------------------------------------------------------------------------------\n\n`--closeLabel VALUE`\n\nA custom label for the notification's \"Close\" button.\n\n-------------------------------------------------------------------------------\n\n`--title VALUE`\n\nThe title of the notification. Defaults to 'Terminal'.\n\n-------------------------------------------------------------------------------\n\n`--subtitle VALUE`\n\nThe subtitle of the notification.\n\n-------------------------------------------------------------------------------\n\n`--delay NUMBER`\n\nWait NUMBER seconds before delivering the notification. Defaults to 0 (immediate delivery).\nIf a signal (SIGINT/SIGTERM) is received during the delay, the process exits silently without delivering.\nWhen combined with `--timeout`, the timeout starts after the notification is delivered.\nCannot be combined with `--at`.\n\n-------------------------------------------------------------------------------\n\n`--at TIME`\n\nDeliver the notification at a specific time. Accepts two formats:\n- `HH:mm` — next occurrence of that time (e.g. `14:30`). If the time matches the current minute, delivers immediately; if it has already passed today, schedules for tomorrow.\n- `yyyy-MM-dd HH:mm` — a specific date and time (e.g. `2026-03-15 09:00`). Must be in the future.\n\nTimes are interpreted in the system's local timezone.\nIf a signal (SIGINT/SIGTERM) is received while waiting, the process exits silently without delivering.\nWhen combined with `--timeout`, the timeout starts after the notification is delivered.\nCannot be combined with `--delay`.\n\n-------------------------------------------------------------------------------\n\n`--timeout NUMBER`\n\nAutomatically close the notification after NUMBER seconds. Defaults to 0 (no timeout).\n\n-------------------------------------------------------------------------------\n\n`--sound NAME`\n\nThe name of a sound to play when the notification appears. The names are listed\nin Sound Preferences. Use 'default' for the default notification sound.\n\n-------------------------------------------------------------------------------\n\n`--json`\n\nOutput the result as a JSON object describing the alert event.\n\n-------------------------------------------------------------------------------\n\n`--group ID`\n\nSpecifies the 'group' a notification belongs to. For any 'group' only _one_\nnotification will ever be shown, replacing previously posted notifications.\n\nA notification can be explicitly removed with the `--remove` option, described\nbelow.\n\nExamples:\n\n* The sender's name, to scope notifications by tool.\n* The sender's process ID, to scope notifications by process.\n* The current working directory, to scope notifications by project.\n\n-------------------------------------------------------------------------------\n\n`--remove ID`  **[required]**\n\nRemoves a previously sent notification with the specified 'group' ID,\nif one exists. Use the special group \"ALL\" to remove all notifications.\n\n-------------------------------------------------------------------------------\n\n`--list ID` **[required]**\n\nLists details about the specified 'group' ID. Use the special group\n\"ALL\" to list all currently active notifications.\n\nOutput is a JSON array of notifications.\n\n-------------------------------------------------------------------------------\n\n`--sender ID`\n\nMakes the notification appear as if it was sent by the specified application,\nincluding using its icon. Defaults to `com.apple.Terminal`.\n\nWhen this option is used, clicking the notification will launch the impersonated\napplication instead of alerter.\n\n-------------------------------------------------------------------------------\n\n`--appIcon PATH`\n\nThe path or URL of an image to display instead of the application icon.\n\n**WARNING: This option relies on a private API and may break in future macOS releases.**\n\n-------------------------------------------------------------------------------\n\n`--contentImage PATH`\n\nThe path or URL of an image to display inside the notification.\n\n**WARNING: This option relies on a private API and may break in future macOS releases.**\n\n-------------------------------------------------------------------------------\n\n`--ignoreDnd`\n\nSends the notification even if Do Not Disturb is enabled.\n\n**WARNING: This option relies on a private API and may break in future macOS releases.**\n\n-------------------------------------------------------------------------------\n\n\n## Shell script example\n```bash\nANSWER=\"$(./alerter --message 'Start now ?' --closeLabel No --actions 'YES,MAYBE,one more action' --timeout 10)\"\ncase $ANSWER in\n    \"@TIMEOUT\") echo \"Timeout man, sorry\" ;;\n    \"@CLOSED\") echo \"You clicked on the default alert' close button\" ;;\n    \"@CONTENTCLICKED\") echo \"You clicked the alert's content !\" ;;\n    \"@ACTIONCLICKED\") echo \"You clicked the alert default action button\" ;;\n    \"MAYBE\") echo \"Action MAYBE\" ;;\n    \"NO\") echo \"Action NO\" ;;\n    \"YES\") echo \"Action YES\" ;;\n    **) echo \"? --\u003e $ANSWER\" ;;\nesac\n```\n\n## Support \u0026 Contributors\n\n### Code Contributors\n\nThis project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].\n\nThis project is based on a fork of [terminal notifier](https://github.com/julienXX/terminal-notifier) by [@JulienXX](https://github.com/julienXX).\n\n## License\n\nAll work is available under the MIT license.\n\nCopyright (C) 2012-2026 Valère Jeantet \u003cvalere.jeantet@gmail.com\u003e, Eloy Durán \u003celoy.de.enige@gmail.com\u003e, Julien Blanchard\n\u003cjulien@sideburns.eu\u003e\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of\nthis software and associated documentation files (the \"Software\"), to deal in\nthe Software without restriction, including without limitation the rights to\nuse, copy, modify, merge, publish, distribute, sublicense, and/or sell copies\nof the Software, and to permit persons to whom the Software is furnished to do\nso, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvjeantet%2Falerter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvjeantet%2Falerter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvjeantet%2Falerter/lists"}