{"id":18572406,"url":"https://github.com/a/zapusk","last_synced_at":"2026-01-04T01:34:34.237Z","repository":{"id":248525636,"uuid":"828937315","full_name":"A/zapusk","owner":"A","description":"Job runner for developers and desktop users supports configured jobs, shell-command execution, scheduling and notifications","archived":false,"fork":false,"pushed_at":"2024-07-15T18:34:01.000Z","size":1128,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-14T20:55:40.475Z","etag":null,"topics":["desktop-automation","job-runner","job-scheduler"],"latest_commit_sha":null,"homepage":"","language":"Python","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/A.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2024-07-15T12:30:55.000Z","updated_at":"2024-11-13T01:23:27.000Z","dependencies_parsed_at":"2024-07-15T14:57:24.583Z","dependency_job_id":null,"html_url":"https://github.com/A/zapusk","commit_stats":null,"previous_names":["a/zapusk"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/A%2Fzapusk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/A%2Fzapusk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/A%2Fzapusk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/A%2Fzapusk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/A","download_url":"https://codeload.github.com/A/zapusk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244141585,"owners_count":20404835,"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":["desktop-automation","job-runner","job-scheduler"],"created_at":"2024-11-06T23:06:06.406Z","updated_at":"2026-01-04T01:34:34.202Z","avatar_url":"https://github.com/A.png","language":"Python","readme":"# Zapusk\n\n![Zapusk Screenshot](.imgs/zapusk.png)\n\nZapusk is a versatile job runner designed for desktop environments. It simplifies the process of managing background tasks by providing robust features such as pre-configured job execution, background shell command execution, cron-like scheduling, log tailing, and notifications. Zapusk's detailed JSON output also enables powerful data manipulation and analysis when paired with tools like jq.\n\n## Table of Contents\n\n- [Key Features](#key-features)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Basic Commands](#basic-commands)\n  - [Advanced Usage](#advanced-usage)\n- [Configuration](#configuration)\n- [Examples](#examples)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Key Features\n\n- **Preconfigured Jobs:** Run jobs defined in your configuration files.\n- **Background Command Execution:** Run shell commands in the background with optional log tailing.\n- **Cron-like Scheduling:** Schedule tasks using flexible cron syntax.\n- **Log Tailing:** View logs in real-time.\n- **Job Management:** Cancel running jobs and check their statuses.\n- **Job Groups:** Share settings like callbacks and parallelism between jobs.\n- **Colored JSON Output:** Easily readable JSON output.\n- **Waybar Integration:** Display job statuses and notifications on Waybar.\n- **Custom Working Directory:** Run scripts and callbacks in a specified working directory.\n\n## Installation\n\nInstall Zapusk using `pip`:\n\n```sh\npip install zapusk\n```\n\n## Usage\n\nZapusk requires `zapusk-server` to be started. Zapusk offers a command-line interface for managing and executing jobs. Here's a quick reference:\n\n### Basic Commands\n\n```sh\nUsage:\n  zapusk -h | --help\n  zapusk --version\n  zapusk run \u003cjob_config_id\u003e [--colors|--no-colors] [--tail]\n  zapusk exec \u003ccommand\u003e [--name=\u003cname\u003e] [--group=\u003cgroup\u003e] [--tail] [--schedule=\u003ccron_expression\u003e] [--colors|--no-colors]\n  zapusk cancel \u003cjob_id\u003e [--scheduled] [--colors|--no-colors]\n  zapusk tail \u003cjob_id\u003e\n  zapusk list [--filter=\u003cstate\u003e|--scheduled] [--colors|--no-colors]\n  zapusk config_jobs [--colors|--no-colors]\n  zapusk config_groups [--colors|--no-colors]\n  zapusk waybar\n\nOptions:\n  -h --help                     Show this screen.\n  --version                     Show version.\n  --colors                      Enable colors.\n  --no-colors                   Disable colors.\n  --filter=\u003cstate\u003e              Filter jobs by status.\n  -n --name=\u003cname\u003e              Name for a command.\n  -g --group=\u003cgroup\u003e            Job group to run the command in.\n  -t --tail                     Tail logfile immediately.\n```\n\n### Examples\n\n```sh\n# Run npm install in the background\nzapusk exec \"npm i\"\n\n# Run pytest and tail its log\nzapusk exec \"pytest -v\" -t\n\n# Schedule a command to run every minute\nzapusk exec \"ping -c4 google.com\" --schedule \"*/1 * * * *\"\n\n# Run a job defined in ~/.config/zapusk/config.yaml\nzapusk run youtube_dl\n\n# Cancel a job by its ID\nzapusk cancel 42\n\n# See logs for a job by its ID\nzapusk tail 42\n```\n\n## Configuration\n\nHere is an example configuration file for Zapusk. It defines job groups and individual jobs, specifying commands, schedules, notifications, and working directories.\n\n```yaml\n# The port the server starts on and the client connects to\nport: 9876\n\n# Enable colored JSON output\ncolors: True\n\njob_groups:\n  - id: unsplash\n    parallel: 1\n  - id: sleep\n    parallel: 2\n  - id: cmd\n    parallel: 10\n    on_finish: notify-send -a \"zapusk\" \"Command Finished\" \"{job.name} has finished\" --icon kitty\n    on_fail: notify-send -a \"zapusk\" \"Command Failed\" \"{job.name} has failed\" --icon kitty\n  - id: cronie\n    parallel: 1\n    on_finish: notify-send -a \"zapusk\" \"Scheduled Job Finished\" \"{job.name} has finished\" --icon kitty\n    on_fail: notify-send -a \"zapusk\" \"Scheduled Job Failed\" \"{job.name} has failed\" --icon kitty\n\njobs:\n  - name: Unsplash Download\n    id: unsplash\n    args_command: \"zenity --entry --text 'Collection ID'\"\n    command: ~/.bin/jobs/unsplash_dl.sh\n    cwd: /path/to/working/directory\n\n  - name: Sleep\n    id: sleep\n    group: sleep\n    args_command: \"zenity --entry --text 'Sleep Time'\"\n    command: sleep\n    on_finish: notify-send -a \"zapusk\" \"Job Finished\" \"{job.name} has finished\" --icon kitty\n    on_fail: notify-send -a \"zapusk\" \"Job Failed\" \"{job.name} has failed\" --icon kitty\n\n  - name: Cronie\n    id: cronie\n    group: cronie\n    schedule: \"*/10 * * * *\"\n    command: sleep 2\n```\n\n## Advanced Usage\n\n### Running Preconfigured Jobs\n\nRun jobs defined in your configuration file using their `id`.\n\n```yaml\n# Job configuration in ~/.config/zapusk/config.yaml\njobs:\n  - name: Unsplash Download\n    id: unsplash\n    args_command: \"zenity --entry --text 'Collection ID'\"\n    command: ~/.bin/jobs/unsplash_wallpaper_collection_download.sh\n    cwd: /path/to/working/directory\n    on_finish: notify-send -a \"Zapusk\" \"Wallpapers downloaded\" --icon kitty\n    on_fail: notify-send -a \"Zapusk\" \"Wallpaper download failed\" --icon kitty\n```\n\n```sh\n# Run the `unsplash` job:\nzapusk run unsplash\n```\n\n### Background Command Execution\n\nRun commands in the background with optional log tailing:\n\n```sh\nzapusk exec \"npm i\" -t\n```\n\n### Scheduling Commands\n\nSchedule commands to run at specific intervals using cron syntax:\n\n```sh\nzapusk exec \"ping -c4 google.com\" --schedule \"*/1 * * * *\"\n```\n\nPre-configured jobs can also be scheduled:\n\n```yaml\njobs:\n  - name: Cronie\n    id: cronie\n    group: cronie\n    schedule: \"*/10 * * * *\"\n    command: sleep 2\n```\n\n### Managing Jobs\n\nCancel a running or scheduled job by its ID:\n\n```sh\nzapusk cancel 42\n```\n\nTail the logs of a running job by its ID:\n\n```sh\nzapusk tail 42\n```\n\nList all pending, running, and finished jobs:\n\n```sh\nzapusk list\n```\n\n### Callbacks\n\nUse `on_finish` and `on_fail` callbacks for notifications.\n\nFor job group callbacks:\n\n```yaml\njob_groups:\n  - id: my_group\n    parallel: 10\n    on_finish: notify-send -a \"zapusk\" \"Command Finished\" \"{job.name} has finished\" --icon kitty\n    on_fail: notify-send -a \"zapusk\" \"Command Failed\" \"{job.name} has failed\" --icon kitty\n```\n\nFor individual job callbacks:\n\n```yaml\njobs:\n  - name: Sleep\n    id: sleep\n    group: sleep\n    command: ~/.bin/jobs/sleep\n    cwd: /path/to/working/directory\n    on_finish: notify-send -a \"zapusk\" \"Job Finished\" \"{job.name} has finished\" --icon kitty\n    on_fail: notify-send -a \"zapusk\" \"Job Failed\" \"{job.name} has failed\" --icon kitty\n```\n\n## Waybar Integration\n\nZapusk integrates with Waybar to display job statuses and notifications directly on your desktop.\n\n```json\n// Example integration with wofi and jq\n\"custom/zapusk\": {\n  \"exec\": \"zapusk waybar\",\n  \"on-click\": \"zapusk config_jobs --no-colors | jq -r \\\".[].id\\\" | wofi --dmenu | xargs -I{} zapusk run {}\",\n  \"tooltip\": true,\n  \"return-type\": \"json\",\n  \"format\": \"{}\",\n  \"interval\": 1\n}\n```\n\n\n## License\n\nZapusk is licensed under the MIT License. See the [LICENSE](LICENSE.md) file for more information.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa%2Fzapusk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fa%2Fzapusk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa%2Fzapusk/lists"}