Metadata-Version: 2.4
Name: py-simple-service-manager
Version: 0.1.14
Summary: Cross-platform command-as-service manager for Windows, Linux systemd, and macOS launchd.
Author: GGN_2015
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: System :: Boot
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: py-admin-launch>=0.1.3
Dynamic: license-file

# py-simple-service-manager

`py-simple-service-manager` lets you manage a one-line command as a service on
Linux, Windows, and macOS.

The same Python runner handles command execution, retry attempts, status files,
and stdout/stderr logs. Platform backends only register and control the runner:

- Linux: `systemd` units controlled by `systemctl`
- Windows: Task Scheduler tasks controlled by `schtasks` and PowerShell
- macOS: `launchd` agents/daemons controlled by `launchctl`

## Install

```bash
python -m pip install -e .
```

Administrator relaunch support uses
[`py-admin-launch`](https://pypi.org/project/py-admin-launch/) for Windows UAC,
Linux `pkexec`/`sudo`, and macOS `osascript`/`sudo`.

## Startup modes

- `manual`: do not start at boot.
- `auto`: start once at boot after network components are available.
- `auto-retry`: start at boot and retry after `K` seconds up to `N` times when
  the command exits with a non-zero code.

The retry count is handled by this package's runner, so it works consistently
across all supported platforms.

`pssm logs` and the GUI log tabs read the current log files, not only completed
runs. The runner flushes stdout/stderr to disk as bytes arrive, and Python
commands are launched with unbuffered output automatically.

## Usage

Register a manual service:

```bash
pssm add api -- python -m http.server 9000
```

Register a boot service:

```bash
pssm add api --mode auto -- python -m http.server 9000
```

Register a boot service with retry:

```bash
pssm add worker --mode auto-retry --retry-delay 10 --retry-limit 5 -- python worker.py
```

Set a per-run timeout, or use `None` for no time limit:

```bash
pssm add api --timeout 30 -- python -m http.server 9000
pssm edit api --timeout None
```

Change startup mode later:

```bash
pssm mode worker manual
pssm mode worker auto-retry --retry-delay 10 --retry-limit 5
```

Inspect and control services:

```bash
pssm list
pssm status worker
pssm logs worker
pssm logs worker --stream stderr --lines 100
pssm start worker
pssm stop worker
pssm remove worker
```

Edit the same fields exposed by the GUI:

```bash
pssm edit worker --command "python worker.py --queue default" --cwd /path/to/app
pssm edit worker --mode auto-retry --retry-delay 10 --retry-limit 5 --timeout 60
pssm edit worker --clear-cwd
```

Open the GUI:

```bash
pssm gui
pssm-gui
```

The GUI supports listing services, creating services, editing command/startup
mode/retry settings/timeout/working directory, deleting services, starting and
force-stopping services, viewing stdout/stderr, and viewing start history. The
selected service status shows whether the current run is still active and how
many seconds it has been running. Anything the GUI can change is also available
through the CLI.

Show storage paths and platform details:

```bash
pssm doctor
```

Services are managed in system scope. Commands relaunch with administrator/root
privileges automatically when needed.

## Platform notes

### Linux

Linux requires `systemd` and `systemctl`.

- System scope writes units to `/etc/systemd/system`.
- Boot startup uses `network-online.target` with `Wants=` and `After=`.

### Windows

Windows uses Task Scheduler.

- Services are registered as system tasks:

```bash
pssm add name --mode auto -- your-command
```

System-scope tasks run as `SYSTEM` with highest available privileges. Make sure
the command and Python environment are available to that account.

### macOS

macOS uses `launchd`.

- System scope writes LaunchDaemons to `/Library/LaunchDaemons`.
- Boot startup maps to `RunAtLoad=true`.

## Development

Run tests from source:

```bash
PYTHONPATH=src python -m unittest discover -s tests -v
```

On Windows PowerShell:

```powershell
$env:PYTHONPATH = "src"
python -m unittest discover -s tests -v
```
