Running a Python CLI on a Schedule with cron and systemd

mytool sync works perfectly when you run it. Scheduled from cron at 3 a.m., it fails with mytool: command not found, or runs and silently does nothing because it could not find its config, or prompts for a token no one will ever type, or — the week the API is slow — starts a second copy while the first is still running and corrupts its state file. Scheduled execution is a different environment from your shell in almost every respect, and a command has to be prepared for it. This guide covers making a Python CLI safe to schedule, then gives complete, working configurations for both cron and systemd timers, with logging, overlap protection and a way to test the scheduled environment before 3 a.m. arrives. It belongs to the long-running and watch-mode topic.

Prerequisites

• A CLI installed as a proper command — with uv tool install or pipx, so it has a stable absolute path. See uv tool install vs pipx for CLIs.
• A Linux or macOS machine with cron, or Linux with systemd for the timer examples.
• Credentials available non-interactively, via environment variables or files.

What is different about a scheduled run

A scheduler starts your command with:

• A minimal PATH — often just /usr/bin:/bin. Commands installed in ~/.local/bin are not found.
• No shell profile. Nothing from .bashrc, .zshrc or .profile runs, so exported variables, aliases and virtual environment activations are all absent.
• A different working directory — usually the home directory, sometimes /.
• No terminal. stdin is not a TTY, and nothing reads stdout or stderr unless you arrange it.
• No person. A prompt waits forever; a failure is noticed only if something reports it.

Every classic "works when I run it" failure comes from one of those five.

Making the command safe to schedule

Most of the work happens in the CLI itself, and it benefits interactive use too:

# src/mytool/cli.py
import os
import sys
import time
from pathlib import Path

import typer
from filelock import FileLock, Timeout

app = typer.Typer()
EX_TEMPFAIL = 75


@app.callback()
def main() -> None:
    """Sync tool, safe to run from cron or a systemd timer."""


@app.command()
def sync(
    state_dir: Path = typer.Option(
        Path(os.environ.get("MYTOOL_STATE_DIR", Path.home() / ".local/state/mytool")),
        help="Where sync state and the lock live (absolute path).",
    ),
    quiet: bool = typer.Option(False, "--quiet", "-q", help="Only print errors."),
) -> None:
    """Sync new items. Idempotent, non-interactive, overlap-safe."""
    token = os.environ.get("MYTOOL_TOKEN")
    if not token:
        typer.echo("error: MYTOOL_TOKEN is not set (scheduled runs cannot prompt)", err=True)
        raise typer.Exit(2)

    state_dir.mkdir(parents=True, exist_ok=True)
    try:
        with FileLock(state_dir / "sync.lock", timeout=0):
            started = time.monotonic()
            count = do_sync(state_dir, token)          # reads + writes state atomically
            if not quiet:
                typer.echo(f"synced {count} items in {time.monotonic() - started:.1f}s", err=True)
    except Timeout:
        typer.echo("another sync is still running; skipping this run", err=True)
        raise typer.Exit(EX_TEMPFAIL)


def do_sync(state_dir: Path, token: str) -> int:
    marker = state_dir / "last-sync"
    marker.write_text(str(int(time.time())))
    return 0


if __name__ == "__main__":
    app()

The command never prompts, fails fast with a precise message when its credential is missing, keeps state at an absolute path that can be overridden, takes a non-blocking lock so overlapping runs skip rather than race (see file locking for concurrent CLI runs), prints one summary line, and exits with a code that says what happened — 0, 2 for configuration problems, 75 for "try again later". A --quiet flag reduces successful runs to silence, which matters for cron's mail-on-output behaviour.

Option 1: cron

cron is on almost every Unix system and is the simplest option. Edit the table with crontab -e:

# m  h  dom mon dow   command
SHELL=/bin/bash
PATH=/usr/local/bin:/usr/bin:/bin
MAILTO=""

0 3 * * *  MYTOOL_TOKEN_FILE=/home/ana/.config/mytool/token /home/ana/.local/bin/mytool sync --quiet >>/home/ana/.local/state/mytool/cron.log 2>&1

Everything in that line is deliberate:

• An absolute path to the command. ~/.local/bin/mytool is where uv tool install and pipx place launchers; find yours with command -v mytool. The launcher pins the right interpreter and virtual environment, so no activation is needed.
• Credentials from a file, readable only by you, via the _FILE convention — never the token itself in the crontab, which other administrators may read.
• Output appended to a log file. Without the redirect, cron mails any output to the user, and on most modern machines that mail goes nowhere. 2>&1 captures errors, which is what you most need to see.
• MAILTO="" disables mail explicitly once you are logging to a file.

cron's limitations are real: no built-in overlap protection (the lock handles that), no catch-up for runs missed while the machine was off, and logs only if you set them up. Where systemd is available, timers remove all three.

Option 2: a systemd timer

A timer is two small unit files: a service describing how to run the command, and a timer describing when. User units need no root access. Put these in ~/.config/systemd/user/:

# ~/.config/systemd/user/mytool-sync.service
[Unit]
Description=mytool sync
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
ExecStart=%h/.local/bin/mytool sync
Environment=MYTOOL_TOKEN_FILE=%h/.config/mytool/token
Environment=PYTHONUNBUFFERED=1
TimeoutStartSec=30min
SuccessExitStatus=75
Nice=10

# ~/.config/systemd/user/mytool-sync.timer
[Unit]
Description=Run mytool sync nightly

[Timer]
OnCalendar=*-*-* 03:00:00
RandomizedDelaySec=10min
Persistent=true

[Install]
WantedBy=timers.target

$ systemctl --user daemon-reload
$ systemctl --user enable --now mytool-sync.timer
$ systemctl --user start mytool-sync.service      # run once now, to test
$ loginctl enable-linger "$USER"                  # keep user timers running when logged out

What systemd adds, without any code:

• Logging. Everything the command writes to stderr goes to the journal with timestamps: journalctl --user -u mytool-sync.
• No overlap. A oneshot service cannot be started again while it is still running; the timer simply waits.
• Missed runs. Persistent=true runs a job that was due while the machine was asleep or off, as soon as it comes back.
• Timeouts and priority. TimeoutStartSec stops a hung run (with SIGTERM, so graceful shutdown applies — see handling SIGTERM and graceful shutdown); Nice=10 keeps the job from competing with interactive work.
• Spread load. RandomizedDelaySec stops a fleet of machines from all hitting your API at exactly 03:00.

SuccessExitStatus=75 tells systemd that "skipped because another run was active" is not a failure worth flagging.

UX considerations

• No colours or progress bars when not on a terminal. Check sys.stderr.isatty() and fall back to plain lines; otherwise the journal and log files fill with escape codes. See detecting a TTY and adapting output.
• One summary line per run. "synced 318 items (2 skipped) in 41s" is what someone scanning logs wants. Put details behind --verbose.
• Distinguish failure kinds by exit code. Configuration errors, transient failures and skipped runs call for different reactions from whoever reads the logs.
• Offer a scheduling helper. A mytool schedule install command that writes the unit files (or prints the crontab line) with the correct absolute paths saves every user from rediscovering them.
• Report stale data interactively. When a person runs mytool status, show when the last scheduled sync happened. It is the fastest way to notice a timer that stopped firing — and the basis of the health checks guide.

Testing the behaviour

You can reproduce the scheduler's environment with env -i, which starts a command with an empty environment. A test that runs the installed CLI that way catches missing-PATH and missing-variable failures before cron does:

# tests/test_scheduled.py
import subprocess
import sys

import pytest

pytestmark = pytest.mark.skipif(sys.platform == "win32", reason="cron-style environment")


def cron_env(tmp_path, **extra):
    return {"PATH": "/usr/bin:/bin", "HOME": str(tmp_path), **extra}


def run(tmp_path, *args, **extra):
    return subprocess.run([sys.executable, "-m", "mytool.cli", "sync", *args],
                          env=cron_env(tmp_path, **extra), capture_output=True, text=True,
                          stdin=subprocess.DEVNULL, timeout=30)


def test_missing_token_fails_fast(tmp_path):
    r = run(tmp_path)
    assert r.returncode == 2
    assert "MYTOOL_TOKEN" in r.stderr


def test_runs_in_minimal_environment(tmp_path):
    r = run(tmp_path, "--quiet", MYTOOL_TOKEN="t")
    assert r.returncode == 0
    assert r.stderr == ""
    assert (tmp_path / ".local/state/mytool/last-sync").exists()


def test_overlapping_run_is_skipped(tmp_path):
    from filelock import FileLock

    state = tmp_path / ".local/state/mytool"
    state.mkdir(parents=True)
    with FileLock(state / "sync.lock"):
        r = run(tmp_path, MYTOOL_TOKEN="t")
    assert r.returncode == 75
    assert "skipping" in r.stderr

For systemd units, systemd-analyze verify ~/.config/systemd/user/mytool-sync.* catches syntax errors, and systemd-analyze calendar "*-*-* 03:00:00" prints when an OnCalendar expression will next fire. Running the service manually with systemctl --user start before enabling the timer is the final check.

Conclusion

Scheduling a CLI is mostly about the CLI: never prompt, read credentials from the environment or files, use absolute paths, lock against overlap, log one useful line, and exit with meaningful codes. With that in place, cron needs one careful line with an absolute path and a log redirect, and a systemd timer adds journald logging, catch-up for missed runs, overlap prevention and timeouts for two short unit files. Test the minimal environment with env -i and the scheduler will hold no surprises.

Frequently asked questions

Related

• Up: Long-running and watch-mode CLIs
• Health checks and heartbeats for long-running CLIs
• File locking for concurrent CLI runs
• Installing and distributing CLIs with pipx
• Detecting CI environments and non-interactive shells