runce 0.2.0

Ensure only one instance of your process runs at a time.

Runce

🚀 The One-and-Done Process Wrangler

"Runce and done! No repeats, no retreats!" 🏃‍♂️💨
🔒 Guaranteed Singleton Execution • 📊 Process Tracking • ⏱️ Lifecycle Management

☕ Support

If you find this project helpful, consider supporting me:

Features ✨

• 🚫 No Duplicates: Each command runs exactly once per unique ID
• 📝 Process Tracking: View all managed processes with status
• ⏱️ Execution Time: Track how long processes have been running
• 📂 Log Management: Automatic stdout/stderr capture
• 🛑 Clean Termination: Proper process killing

Installation 📦

pip install runce

Usage

runce <command> [options] [arguments]

Commands

run

Runs a new singleton process.

runce run [options] ARG...

Options:

• --id <run_id>: Unique run identifier (required).
• --working-directory <cwd>: Working directory for the command.
• -t <tail> / --tail <tail>: Tail the output (n lines). Use -t -1 to print the entire output.
• --overwrite: Overwrite existing entry if it exists.
• --run-after <command>: Run a command after the main command finishes.

Example:

runce run --id my-unique-task sleep 60

ls / list

Lists all managed processes.

runce ls [options]

Options:

• -f <format> / --format <format>: Format of the output line (see examples below).

Example:

runce ls
runce ls -f "{pid}\t{name}\t{command}"

status

Checks the status of processes.

runce status [options] [ID...]

Options:

• -f <format> / --format <format>: Format of the output line.

Example:

runce status my-unique-task

kill

Kills running processes.

runce kill [options] ID...

Options:

• --dry-run: Perform a dry run (don't actually kill).
• --remove: Remove the entry after killing.

Example:

runce kill my-unique-task

clean

Cleans up entries for non-existing processes.

runce clean [ID...]

Example:

runce clean

tail

Tails the output of processes.

runce tail [options] [ID...]

Options:

• -n <lines> / --lines <lines>: Number of lines to tail.
• --header <format>: Header format.
• -x / --only-existing: Only show existing processes.
• -t / --tab: Prefix tab space to each line.

Example:

runce tail my-unique-task
runce tail -n 20 my-unique-task

restart

Restarts a process.

runce restart [options] ID...

Options:

• -t <tail> / --tail <tail>: Tail the output after restarting.

Example:

runce restart my-unique-task

Examples 💡

1. Running a Background Service

runce run --id api-server -- python api.py

2. Checking Running Processes

$ runce list
PID     NAME        STATUS      ELAPSED    COMMAND
1234    api-server  ✅ Running  01:23:45   python api.py
5678    worker      ❌ Stopped  00:45:30   python worker.py

3. Preventing Duplicates

$ runce run --id daily-job -- python daily.py
🚀 Started: PID:5678(✅ Running) daily-job

$ runce run --id daily-job -- python daily.py
🚨 Already running: PID:5678(✅ Running) daily-job

Formats

The -f / --format option in the ls and status commands allows you to customize the output format. You can use the following placeholders:

• {pid}: Process ID
• {name}: Run ID / Name
• {pid_status}: Process status ("✅ Running" or "👻 Absent")
• {elapsed}: Elapsed time
• {command}: The command being executed

How It Works

RunCE stores process information in JSON files within a temporary directory (/tmp/runce.v1 on Linux). Before starting a new process, it checks for existing entries with the same ID to prevent duplicates.

Development 🏗️

# Install in development mode
pip install -e .

# Run tests
pytest

# Lint code
flake8 runce