shell-jobrunner

Job runner with logging

Installation

Install system-wide:

$ pip install shell-jobrunner

Install just for the current user:

$ pip install --user shell-jobrunner

Uninstallation

$ pip uninstall jobrunner

Examples

Run sleep 5 in the background
```
$ job sleep 5
```
Run ls when the last job finishes and it passed (exit code 0)
```
$ job -B. ls
```
Run ls when last job finishes (pass / fail)
```
$ job -b. ls
```

Monitor job execution

$ job -W
Sat Aug 10, 2019 20:48:23  No jobs running, load: 0/0/0

Retry a job
```
$ job --retry ls
```

Query Examples

NOTE . is available as an alias to the most recently executed job (as in the Examples above).

View recently executed job log file

$ job ls
$ view `job`   # Opens the output from ls using "view"

View two most recently executed

$ job echo 1
$ job echo 2
$ view `job -n0 -n1`

Query by job name

$ job echo foo
$ job echo bar
$ view `job -g foo`

Show job info by name
```
$ job ls
$ job -s ls
```

Configuration

The default configuration file location is ~/.config/jobrc, but can be

overridden using the –rc-file option.

Sample rcfile:

[mail]
program = mail
# For notifications over chat applications (like Google Chat), use chatmail as
# your mail program instead. "chatmail" must be specified rather than a differently
# named link to the script, else some options provided to job (such as --rc-file)
# will not be passed through to it.
# program = chatmail
domain = example.com
[ui]
watch reminder = full|summary  # default=summary
[chatmail]
at all = all|none|no id # default=none
reuse threads = true|false # default true
[chatmail.google-chat-userhooks]
user1 = https://chat.googleapis.com/v1/spaces/...
[chatmail.google-chat-userids]
# Retrieve this using your browser inspector on an existing mention of this user.
# It should show up as "user/some_long_integer" somewhere in the span's metadata.
user1 = <long integer>

System Notifications (Systemd user service example)

If you want to enable notifications when jobs finish, one way to do this is to use the –notifier argument.

~/.config/systemd/user/job-notify.service:

[Unit]
Description=Jobrunner Notifier

[Service]
Type=simple
ExecStart=env job --notifier jsonNotify.py
RestartSec=30
Restart=always

[Install]
WantedBy=default.target

~/.local/bin/jsonNotify.py:

#!/usr/bin/env python3

from json import load
import subprocess
from sys import stdin

cmd = ["notify-send"]
data = load(stdin)
rc = data.get("rc", 0)
if rc != 0:
    cmd += ["--urgency=critical"]
cmd += [data["subject"], data["body"]]
subprocess.run(cmd)

Hacking

Primary workflow

It’s highly recommend to work inside a virtualenv using pipenv.

Create new virtualenv and install an editable version of jobrunner:

pipenv --three install --dev
pipenv run pip install -e .

Autoformat the code and check linters:

pipenv run ./format.sh

Run tests:

pipenv run pytest

Run CI checks locally

This allows you to run something similar to the azure pipelines locally using docker.
It will use PIP_INDEX_URL and / or ~/.config/pip/pip.conf to configure a pypi mirror.
This will also update Pipfile*.lock.

./test-docker.py [--versions 2.7 3.7 3.8] [--upgrade] [--ignore-unclean]

Metadata

Release files for shell-jobrunner 2.7.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for shell-jobrunner 2.7.1
File	Size	Uploaded
shell_jobrunner-2.7.1.tar.gz	85.9 kB	Jun 19, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for shell-jobrunner 2.7.1
File	Interpreter	ABI	Platform	Reset
shell_jobrunner-2.7.1-py3-none-any.whl 49.1 kB Jun 19, 2025	Python 3	none	any	Details

Total release size: 135.0 kB

Release files / shell_jobrunner-2.7.1.tar.gz

Download URL	shell_jobrunner-2.7.1.tar.gz
Size	85.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`4cbdcd77873f5473ac849f63b18dcc73e66447c06e38e9e29e106ab9a259766b`
BLAKE2b-256 checksum How to use checksums	`b47f9c1033b661b2995d38bfb6ee8d470e60c439b9f7f14c09eea5ccd50896b4`
Upload date	Jun 19, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.12.9`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/wwade/jobrunner
Publishing commit: github.com/wwade/jobrunner/tree/03b06a65a22b157773e32487e0cf08ea983997b5

Workflow

Publishing configuration: github.com/wwade/jobrunner/blob/03b06a65a22b157773e32487e0cf08ea983997b5/.github/workflows/python-publish.yml
Publishing logs: github.com/wwade/jobrunner/actions/runs/15765526593/attempts/1

Artifact

Subject: shell_jobrunner-2.7.1.tar.gz
SHA-256 checksum: 4cbdcd77873f5473ac849f63b18dcc73e66447c06e38e9e29e106ab9a259766b Verifying attestations

Release files / shell_jobrunner-2.7.1-py3-none-any.whl

Download URL	shell_jobrunner-2.7.1-py3-none-any.whl
Size	49.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`9c2806cd081a44773ed50d6a538243c7ed0c549918094038bc7189389e677d4e`
BLAKE2b-256 checksum How to use checksums	`f11eb01b45706ca3bb6fbfb7ae51d4af474607023f81f9c32daeed4f14fa5fa6`
Upload date	Jun 19, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.12.9`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/wwade/jobrunner
Publishing commit: github.com/wwade/jobrunner/tree/03b06a65a22b157773e32487e0cf08ea983997b5

Workflow

Publishing configuration: github.com/wwade/jobrunner/blob/03b06a65a22b157773e32487e0cf08ea983997b5/.github/workflows/python-publish.yml
Publishing logs: github.com/wwade/jobrunner/actions/runs/15765526593/attempts/1

Artifact

Subject: shell_jobrunner-2.7.1-py3-none-any.whl
SHA-256 checksum: 9c2806cd081a44773ed50d6a538243c7ed0c549918094038bc7189389e677d4e Verifying attestations