{"id":20119145,"url":"https://github.com/abridoux/bugle","last_synced_at":"2025-05-06T14:32:12.750Z","repository":{"id":45269881,"uuid":"315467886","full_name":"ABridoux/bugle","owner":"ABridoux","description":"A command-line tool to post and listen to distributed notifications to execute scripts.","archived":false,"fork":false,"pushed_at":"2021-12-26T11:17:07.000Z","size":59,"stargazers_count":23,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-09T13:46:51.559Z","etag":null,"topics":["command-line-tool","distributed-notifications","macos"],"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/ABridoux.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-11-23T23:40:55.000Z","updated_at":"2023-12-08T10:24:29.000Z","dependencies_parsed_at":"2022-09-13T16:10:20.204Z","dependency_job_id":null,"html_url":"https://github.com/ABridoux/bugle","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ABridoux%2Fbugle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ABridoux%2Fbugle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ABridoux%2Fbugle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ABridoux%2Fbugle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ABridoux","download_url":"https://codeload.github.com/ABridoux/bugle/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252703453,"owners_count":21790887,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["command-line-tool","distributed-notifications","macos"],"created_at":"2024-11-13T19:14:36.098Z","updated_at":"2025-05-06T14:32:12.464Z","avatar_url":"https://github.com/ABridoux.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bugle\n\nA simple command line tool to post and listen to distributed notifications to execute scripts.\n\n## Usage\n\n### Manage observations\n\n**Bugle** uses Plist files to know what notifications to listen, and what scripts to execute when the notification is received.\n\nA notification reception can execute several scripts as they are stored in an array. Here is an example.\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003c!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\"\u003e\n\u003cplist version=\"1.0\"\u003e\n\u003cdict\u003e\n    \u003ckey\u003eUserDidFallAsleep\u003c/key\u003e\n    \u003carray\u003e\n        \u003cstring\u003e/Users/homer/Desktop/ring.sh\u003c/string\u003e\n        \u003cstring\u003e/Users/Shared/shower.sh\u003c/string\u003e\n    \u003c/array\u003e\n    \u003ckey\u003eUserDidWakeUp\u003c/key\u003e\n    \u003carray\u003e\n        \u003cstring\u003e/Users/homer/Desktop/showTask.sh\u003c/string\u003e\n    \u003c/array\u003e\n\u003c/dict\u003e\n\u003c/plist\u003e\n```\n\nWhen the notification \"UserDidFallAsleep\" is received, both */Users/homer/Desktop/ring.sh* and */Users/Shared/shower.sh* will be executed.\nIt's possible to edit a Plist file manually. Otherwise, **Bugle** offers two commands to add and remove an observer from a file.\n\n#### Add an observer\n\n```bash\nbugle add \\\n    -n UserDidFallAsleep \\\n    -s /Users/homer/Desktop/ring.sh \\\n    -f UserObservations.plist\n```\n\n##### Registered domains\n\nIf the notification domain is registered, it's possible to specify the domain and rely on [auto-completion](#completion). The list of registered domains can be found [here](#domains). For instance with the registered domain \"kerberos\".\n\n```bash\nbugle add \\\n    -d kerberos -n ADPasswordChanged \\\n    -s /Users/homer/Desktop/ring.sh \\\n    -f KerberosObservations.plist\n```\n\n##### Script execution\n\nIt is required to add a shebang at the beginning of the script file.\n\n#### Remove an observer\n\n```bash\nbugle remove \\\n    -n UserDidFallAsleep \\\n    -s /Users/homer/Desktop/ring.sh \\\n    -f UserObservations.plist\n```\n\n##### Registered domains\n\nIf the notification domain is registered, it's possible to specify the domain and rely on [auto-completion](#completion). The list of registered domains can be found [here](#domains). For instance with the registered domain \"kerberos\".\n\n```bash\nbugle remove \\\n    -d kerberos -n ADPasswordChanged \\\n    -s /Users/homer/Desktop/ring.sh \\\n    -f KerberosObservations.plist\n```\n\n### Listen\n\nTo start listening to notifications, run `bugle listen` with the observations file.\n\n```bash\nbugle listen -f UserObservations.plist\n```\n\n### Post\n\nIt's also possible to post notifications, whether it be to test the scripts execution or for another purpose.\n\n```bash\nbugle post -n UserDidFallAsleep\n```\n\n##### Registered domains\n\nIf the notification domain is registered, it's possible to specify the domain and rely on [auto-completion](#completion). The list of registered domains can be found [here](#domains). For instance with the registered domain \"kerberos\".\n\n```bash\nbugle post -d kerberos -n ADPasswordChanged\n```\n\n## Install\n\nYou can find a notarized version of the executable as both **PKG** or **ZIP** in the [releases](https://github.com/ABridoux/bugle/releases) section.\n\nThe following script will download the latest version and install it at */usr/local/bin/*.\n\n```bash\ncurl -LO https://github.com/ABridoux/bugle/releases/latest/download/bugle.zip \u0026\u0026 \\\nunzip bugle.zip \u0026\u0026 \\\nrm bugle.zip \u0026\u0026 \\\ninstall bugle /usr/local/bin \u0026\u0026 \\\nrm bugle\n```\n\n### Completion\n\nYou can install the completion for **Bugle** by running `bugle install-completion-script`. You might have to source again your shell file or to restart the terminal.\n\nIf the completion script does not install properly, you can try to do it manually with with the command `bugle --generate-completion-script` by following this [guide](https://github.com/apple/swift-argument-parser/blob/main/Documentation/07%20Completion%20Scripts.md).\n\n## Domains\n\n**Bugle** tries to offer a less error-prone way to register to notifications. This is done by adding a domain to the register. This allows to specify a notification with auto-completion and remove the need to write the reverse DNS each time. You can find the list of registered domains by running `bugle domain` and the domain notification name and details with \n\n```bash\nbugle domain [domain name]\n```\n\n### Registering a domain\n**Bugle** is open-source, and anyone is welcome to offer a new domain record. This is done by providing a Swift file in the *Declarations* folder. This file will hold 3 pieces of information:\n- a reference URL where the notifications list for the domain can be found\n- the reverse DNS of the domain (e.g. \"com.apple.KerberosPlugin\")\n- an array of the domain notifications. Each notification is a dictionary with the notification name and the details about when it is sent.\n\nTo hold those information, a `Domain` should be declared as a `static Domain` property in a `Domain` extension. The compiler will ensure no property is forgotten.  \n \nHere is an example Swift file used for Kerberos (not exhaustive).\n\n```swift\npublic static let kerberos = Domain(\n    name: \"kerberos\",\n    referenceURL: URL(string: \"https://www.apple.com/business/docs/site/Kerberos_Single_Sign_on_Extension_User_Guide.pdf\")!,\n    reverseDNS: \"com.apple.KerberosPlugin\",\n    notifications: [\n        Notification(\n            name: \"ConnectionCompleted\",\n            details: \"The Kerberos SSO extension has run its connection process.\"\n        ),\n        Notification(\n            name: \"ADPasswordChanged\",\n            details: \"The user has changed the Active Directory password with the extension\"\n        )\n    ]\n)\n```\n\n### New domain record process\n\nTo add a new domain record, here is a process that you can follow.\n\n1. Fork the project (upper-right corner button)\n2. Create a new branch from \"develop\", naming it \"feature/domain-record-[domain name]\"\n3. Add the Swift file in the folder *Sources/Bugle/Declarations*\n4. Commit your changes and push them to your forked repository\n5. Open a merge-request from your branch to \"Bugle/develop\" and assign [ABridoux](https://github.com/ABridoux) or tag me in the merge request comment.\n\nFrom here, I'll take a look as soon as I can and merge your branch if the JSON has no errors. Otherwise, maybe I'll ask to make some modifications.\nIf you prefer, you can also [send me an email](mailto:alexis1bridoux@gmail.com) with the JSON file. I'll add it to the records.\n\nThe added domain record will then be bundled in the next release.\n\n### Registered domains\n\n- [Apple Kerberos Plugin](https://www.apple.com/business/docs/site/Kerberos_Single_Sign_on_Extension_User_Guide.pdf)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabridoux%2Fbugle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabridoux%2Fbugle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabridoux%2Fbugle/lists"}