Metadata-Version: 2.4
Name: macpmd
Version: 1.0.0b4
Summary: macOS process manager — a PM2 equivalent using launchd for persistence
Project-URL: Source, https://gitlab.com/waterjuice/macpmd
Author: WaterJuice
License-Expression: Unlicense
License-File: LICENSE
Keywords: cli,daemon,launchd,macos,pm2,process-manager
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# macpmd

A macOS process manager — a PM2 equivalent using launchd for persistence and crash recovery.

macpmd makes it easy to manage long-running processes on macOS. Start, stop, restart, and monitor processes from the command line. Processes are automatically registered with launchd so they survive reboots and recover from crashes.

## Features

- **Process management** — add, start, stop, restart, and delete processes
- **Batch operations** — operate on multiple processes at once, or use `--all`
- **Process listing** — view all processes with status, PID, uptime, restart count, and launchd state
- **Log management** — stdout/stderr redirected to `~/.local/share/macpmd/logs/` with automatic rotation
- **Log tailing** — view recent output, follow in real-time, or show all process logs with coloured prefixes
- **Exit code logging** — process exit codes and signals are recorded in the log
- **launchd integration** — plists auto-installed in `~/Library/LaunchAgents/` for boot persistence and crash recovery
- **Sudo support** — start processes with `--sudo` for elevated privileges
- **Zero dependencies** — stdlib only, no external packages required
- **Coloured output** — TTY-aware ANSI colours for status display

## Requirements

- Python 3.12+
- macOS (uses launchd and launchctl)

## Installation

```bash
pip install macpmd
```

Or run directly with uv:

```bash
uvx macpmd
```

## Quick Start

```bash
# Add a process (name auto-derived as "server")
macpmd add "node server.js"

# Add with an explicit name
macpmd add "python3 worker.py" --name my-worker

# Add with sudo
macpmd add "python3 server.py" --name my-app --sudo

# List all processes
macpmd list

# View logs
macpmd logs my-app
macpmd logs my-app --follow
macpmd logs --all
macpmd logs --all --follow

# Start a stopped process
macpmd start my-app

# Start all stopped processes
macpmd start --all

# Restart a process
macpmd restart my-app

# Stop multiple processes
macpmd stop my-app worker

# Stop all processes
macpmd stop --all

# Remove a process entirely
macpmd delete my-app
```

## How It Works

macpmd spawns processes in new sessions (`start_new_session`) so they survive the parent terminal closing. Process state is tracked in `~/.local/share/macpmd/state.json` and logs are written to `~/.local/share/macpmd/logs/<name>.log`.

When you add a process, a launchd plist is automatically installed in `~/Library/LaunchAgents/` with:

- **`KeepAlive: true`** — launchd restarts the process if it crashes
- **`RunAtLoad: true`** — the process starts automatically at login

This gives you PM2-style process management backed by macOS's native process supervisor.

## Development

```bash
# Set up development environment
make dev

# Run linting and type checking
make check

# Auto-format code
make format

# Build wheel and docs
make build
```

## Licence

Released under the [Unlicense](https://unlicense.org/) — public domain.
