Metadata-Version: 2.4
Name: py-simple-service-manager
Version: 0.1.4
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
```

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 --force
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
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/working directory, deleting services, starting and stopping
services, and viewing stdout/stderr. 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
```
