{"id":20620541,"url":"https://github.com/blacklight/platypush-webext","last_synced_at":"2026-03-12T14:14:42.234Z","repository":{"id":41617836,"uuid":"274000081","full_name":"blacklight/platypush-webext","owner":"blacklight","description":"Extension for interacting with Platypush instances from a browser","archived":false,"fork":false,"pushed_at":"2023-03-05T01:44:39.000Z","size":1094,"stargazers_count":3,"open_issues_count":23,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-17T05:11:43.987Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Vue","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/blacklight.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-21T23:36:02.000Z","updated_at":"2025-01-06T04:26:22.000Z","dependencies_parsed_at":"2025-01-17T05:11:17.498Z","dependency_job_id":"b6cbc0d5-8892-420c-8061-84705363ddda","html_url":"https://github.com/blacklight/platypush-webext","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blacklight%2Fplatypush-webext","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blacklight%2Fplatypush-webext/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blacklight%2Fplatypush-webext/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blacklight%2Fplatypush-webext/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blacklight","download_url":"https://codeload.github.com/blacklight/platypush-webext/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242277697,"owners_count":20101542,"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":[],"created_at":"2024-11-16T12:14:50.143Z","updated_at":"2026-03-12T14:14:42.221Z","avatar_url":"https://github.com/blacklight.png","language":"Vue","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Platypush browser extension\n\nThis extension allows you to run Platypush commands on remote hosts as well as\ncustom scripts, build custom actions as scripts that can access both the browser\nAPI and Platypush API, and attach hooks to events generated by remote Platypush systems.\n\nArticle on the motivations behind this extensions and some examples to get started: https://blog.platypush.tech/article/One-browser-extension-to-rule-them-all\n\nThis extension is not meant to be used as a standalone browser extension, but rather as a companion to the Platypush server.\n\nIt is meant to be used in conjunction with the Platypush server, which provides the backend functionality and APIs that the extension relies on.\n\n**Note**: this extension is currently _only compatible with Firefox_, as it relies on permissions only available on Manifest V2 - now unsupported on Chromium-based browsers.\n\n## Installation\n\n### Official releases\n\nThe official version is available on the [Firefox Add-ons store](https://addons.mozilla.org/en-US/firefox/addon/platypush/).\n\n### Manual installation\n\nInstall the dependencies:\n\n```bash\nnpm install\n```\n\nGenerate the extension .zip file:\n\n```bash\nnpm run build-zip\n```\n\nOpen `about:debugging#/runtime/this-firefox` in Firefox, click on \"Load\nTemporary Add-on\" and select the generated `.zip` file - it should be located\nunder the `dist-zip` directory.\n\n### Dev installation\n\n```bash\nnpm run build:dev\n```\n\n### Testing\n\n```\nnpm run watch:dev\n```\n\nThen follow the procedure for manual installation above to load the extension\nin Firefox. Any changes to the source files will be automatically picked up.\n\n## Configuration\n\nOnce installed, click on the popup icon in the browser toolbar and configure your Platypush service.\n\n![Screenshot of the add device form](https://platypush-static.s3.nl-ams.scw.cloud/screenshots/webext/add-device.png)\n\n### Authentication\n\nYou have two options to authenticate:\n\n- You can use a Platypush API token, which you can generate in the Platypush web interface.\n  This is probably more portable and reliable, as it does not require you to\n  log in to the Platypush web interface in the browser, and the extension won't\n  stop working if you log out of the web interface.\n\n- You can just enter the URL of your Platypush server and log in with your\n  username and password.\n\n### Backup and restore\n\nYou can backup your configuration directly to one of your remote Platypush\nhosts by clicking on the \"Backup\" button in the configuration tab.\n\n![Screenshot of the configuration tab](https://platypush-static.s3.nl-ams.scw.cloud/screenshots/webext/config.png)\n\nThe configuration file will automatically be backed up under\n`\u003cWORKDIR\u003e/webext/config.json` (usually\n`~/.local/share/platypush/webext/config.json`).\n\nFrom the configuration tab you can also restore the configuration from a remote\nhost, a URL or a local file.\n\nIt is also possible to manually modify the configuration JSON, if you know what\nyou are doing.\n\n## Usage\n\nOnce you have your extension configured, you can use it to run commands on your\nPlatypush services directly from the browser.\n\nIt also provides a native JavaScript API that you can use to run more complex\ncommands, or also to run commands that run entirely in your browser - similar\nto what e.g. GreaseMonkey/TamperMonkey do.\n\n### Running and storing actions\n\nSelect one of your configured devices and click the \"_Run Action_\" button to\nrun a command on it.\n\nYou'll have a nice autocomplete form to help you find the command you want to\nrun (your custom defined procedures will also be available in the list), as\nwell as documentation about the command and its parameters.\n\n![Screenshot of the run action tab](https://platypush-static.s3.nl-ams.scw.cloud/screenshots/webext/run.png)\n\nClick on _Run_ to execute the command, or on _Save Action_ if you want to save\nit to in your list.\n\nThe save action form will let you define a name for the action, a description,\nan icon (it supports [FontAwesome](https://fontawesome.com/icons) classes), an\nicon color, a category, a list of devices (actions can be installed on multiple\ndevices), and, quite importantly, a keybinding that can be used to run the\naction anywhere in the browser.\n\n![Screenshot of the save action tab](https://platypush-static.s3.nl-ams.scw.cloud/screenshots/webext/edit-action.png)\n\nI personally find the keybinding the feature of this extension that I use the most.\n\nWhile it's possible to run actions from the extension popup or the right click,\nI find it very convenient to map the 10 actions I use the most (lights and\nmusic control, save the current web page to Wallabag etc.) to the\n`Ctrl+Alt+\u003c0-9\u003e` keys, so that I can run them from anywhere in the browser.\n\n### Script mode\n\nThe _Request_ mode is the most straightforward way to run commands directly on\nyour Platypush services, but you can also configured more complex actions by\nleveraging the _Script_ mode in the _Run_ tab.\n\n![Screenshot of the run action tab in script mode](https://platypush-static.s3.nl-ams.scw.cloud/screenshots/webext/script.png)\n\nIn this mode you can write a JavaScript `async` callback that will be run\nwhen the action is executed.\n\nThe callback will receive two arguments:\n\n- `app`: an object that provides access to the Platypush API, which you can use\n  to run commands on your Platypush services.\n- `args`: an object that contains the parameters passed to the action when it\n  was run.\n\nThe `app` object exposes many useful methods that you can use to run commands,\naccess the browser API, and more. A comprehensive example is available\n[here](https://gist.github.com/BlackLight/d80c571705215924abc06a80994fd5f4).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblacklight%2Fplatypush-webext","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblacklight%2Fplatypush-webext","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblacklight%2Fplatypush-webext/lists"}