Skip to main content
Glama
README.md
<img src="assets/logo.svg" alt="spm logo" width="96" height="96" align="right">

# SPM

**A simple, cross-platform manager for native system services.**

SPM provides a unified command-line interface for managing native system services across Windows, Linux, and macOS.

It works with each operating system's native service manager:

- **Linux:** systemd
- **macOS:** launchd
- **Windows:** Windows Services

SPM aims to make service management consistent, simple, and intuitive across platforms.

### Built for coding agents

Coding agents such as Claude Code, Codex, and Cursor often start dev servers and
workers with `&` or `nohup`. Those processes die or become orphans when the
session ends, and their output is lost. With spm, an agent starts them as real
native services instead: they keep running, restart on crash and at login, and
their logs stay readable through `spm logs` or the built-in MCP server.

```bash
claude plugin marketplace add eyvant/spm && claude plugin install spm@eyvant-spm
codex mcp add spm -- spm mcp
```

[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=spm&config=eyJjb21tYW5kIjoic3BtIiwiYXJncyI6WyJtY3AiXX0=)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_server-0098FF?logo=visualstudiocode)](https://insiders.vscode.dev/redirect/mcp/install?name=spm&config=%7B%22command%22%3A%22spm%22%2C%22args%22%3A%5B%22mcp%22%5D%7D)

Install spm itself first (see [Install](#install)). See
[Agent and MCP integration](#agent-and-mcp-integration) for every client.

Under the hood, Linux uses systemd and journald, macOS uses launchd LaunchAgents or LaunchDaemons, and Windows uses per-user supervisors with Startup integration or native SCM services for system scope.

> User services do not require elevation. Use `--system` explicitly when a service must run at the machine level.

## Install

Install the latest release on Linux or macOS:

```bash
curl -fsSL https://raw.githubusercontent.com/eyvant/spm/main/install.sh | sh
```

The installer verifies the release checksum, installs `spm` to `~/.local/bin`, and installs completion for the shell named by `$SHELL` when it is Bash, Zsh, or Fish. Make sure `~/.local/bin` is in `PATH`.

Choose a completion shell explicitly, or skip completion installation:

```bash
curl -fsSL https://raw.githubusercontent.com/eyvant/spm/main/install.sh | sh -s -- --completion bash
curl -fsSL https://raw.githubusercontent.com/eyvant/spm/main/install.sh | sh -s -- --no-completion
```

The `SPM_COMPLETION` environment variable also accepts `auto`, `bash`, `zsh`, `fish`, or `none`.

On Windows, run PowerShell:

```powershell
irm https://github.com/eyvant/spm/releases/latest/download/install.ps1 | iex
```

The Windows installer verifies the release checksum, installs `spm.exe` under
`%LOCALAPPDATA%\Programs\spm`, adds it to the user `PATH`, and installs dynamic
PowerShell completion. Use `install.ps1 -NoCompletion` or `-NoPath` when needed.

Uninstall SPM on Linux or macOS:

```bash
curl -fsSL https://raw.githubusercontent.com/eyvant/spm/main/install.sh | sh -s -- --uninstall
```

Uninstall SPM on Windows:

```powershell
& ([scriptblock]::Create((irm https://github.com/eyvant/spm/releases/latest/download/install.ps1))) -Uninstall
```

The uninstallers remove the executable, installed shell completion, and—on
Windows—the PowerShell profile entry and user `PATH` entry. They do not delete
managed services or their data. If services still exist, uninstall stops and
asks you to delete them first (`spm delete all --yes`, and `sudo spm --system
delete all --yes` when applicable); use `--force` or `-Force` only when you
intentionally want to leave those services behind.

Install a specific version:

```bash
curl -fsSL https://raw.githubusercontent.com/eyvant/spm/main/install.sh | \
  sh -s -- --version v0.1.0
```

### Upgrading

Run the installer again; it works while services are running.

`spm` itself is only the command-line tool. Background work is done by two
small runtimes installed next to it:

| Runtime | Platforms | Runs |
| --- | --- | --- |
| `spm-supervisor` | Windows | every service (systemd and launchd supervise services elsewhere) |
| `spm-scheduler` | Windows, macOS | the scheduler daemon and every scheduled-job run |

Release builds of the runtimes are reproducible, and the installer replaces a
runtime only when its file differs from the installed one. Most upgrades
therefore replace just the CLI and restart nothing; a runtime changes when its
code, a dependency or the Go toolchain release changes. `spm-supervisor
version` and `spm-scheduler version` print the start of the file's SHA-256.
When a runtime does change:

- **`spm-scheduler`:** the scheduler daemon is restarted. Services are not
  touched, and a job that is running finishes normally; its next run uses the
  new version.
- **`spm-supervisor`:** each running service is handed over to the new
  supervisor without being stopped. The old supervisor detaches and leaves the
  process running; the new one adopts it, keeping its start time and restart
  count. For system services the installer asks for Administrator approval
  once.

  An upgrade never restarts a service on its own. A service that cannot be
  handed over (for example one still running on the supervisor from spm 0.3.6
  or earlier) keeps running on its current supervisor, and the installer
  reports it with the commands that move it over when a short interruption
  suits you: `spm stop <name>` then `spm run <name>`. If the new supervisor
  fails to start, the previous one takes the service back. Pass
  `-RestartServices` to restart services that cannot be handed over instead.

On macOS, system jobs need `sudo`. Linux needs neither runtime. Pass
`-NoRestart` (Windows) or `--no-restart` (macOS) to keep running processes on
the previous runtime until you restart them yourself.

Or install from source with Go 1.27 or later (the runtimes must sit next to
`spm`, which `go install` does):

```bash
go install github.com/eyvant/spm/cmd/...@latest
```

Verify the installation:

```bash
spm version
spm doctor
```

## Start your first service

From the directory containing your application:

```bash
spm start ./my-server --name my-server
```

On Linux, that one command:

1. Creates a native systemd user service.
2. Uses the current directory as its working directory.
3. Starts the process immediately.
4. Enables it to start again with the user manager.
5. Restarts it if it exits.
6. Sends stdout and stderr to journald.

On Windows it creates an equivalent user service: a detached supervisor owns
the process and its restart policy, a hidden Startup shortcut launches enabled
services at logon, and output is written below
`%APPDATA%\spm\services\NAME`.

On macOS it creates a LaunchAgent in `~/Library/LaunchAgents`; output and saved
configuration live under the user's Application Support directory.

## User and system services

The default scope is per-user on all platforms:

- Linux: runs under the systemd user manager and stores units in
  `~/.config/systemd/user`.
- Windows: runs as the current account, stores state in `%APPDATA%\spm`, and
  starts when that user logs on.
- macOS: runs as the current account through a LaunchAgent and starts at login.

`--system` selects machine-wide services:

- Linux: requires root and stores units in `/etc/systemd/system`.
- Windows: requires an Administrator terminal, stores state in
  `%ProgramData%\spm`, and starts at boot without a user login. The default
  account is `LocalSystem`. Each service gets a private supervisor executable
  and data directory so its account does not depend on an administrator's
  profile or gain access to another service's configuration.
- macOS: requires root, installs a LaunchDaemon in `/Library/LaunchDaemons`,
  stores state in `/Library/Application Support/spm`, and starts at boot.

Windows system services can select an account:

```powershell
spm --system start --user LocalService --name api -- .\api.exe
spm --system start --user NetworkService --name proxy -- .\proxy.exe
spm --system start --user 'DOMAIN\svc-api' --name api -- .\api.exe
spm --system start --user 'DOMAIN\svc-api$' --name api -- .\api.exe
spm --system start --user 'NT SERVICE\spm-api' --name api -- .\api.exe
```

Aliases for `SYSTEM`, `LocalSystem`, `LocalService`, and `NetworkService` are
accepted, as are group Managed Service Accounts (gMSA, ending in `$`) and
`NT SERVICE\...` virtual accounts. For a regular local or domain user, spm
grants `SeServiceLogonRight`, prompts securely, and passes the credential
directly to SCM; spm never writes it to its configuration. System services are
visible in `services.msc`. spm restricts `%ProgramData%\spm` ACLs to
Administrators, SYSTEM, and the selected
service account. `--group` is Unix-specific and rejected on Windows.

Check it:

```bash
spm list
spm logs my-server -f
spm show my-server
```

Manage it later from any directory:

```bash
spm restart my-server
spm stop my-server
spm start my-server
spm delete my-server
```

For services that must survive logout and start after a reboot, run this once:

```bash
spm startup
```

spm detects whether user lingering is already enabled and only prints a reminder when action is needed.

## Common examples

### Node.js

```bash
spm start app.js --name api
```

Use the explicit command form when the application needs arguments:

```bash
spm start --name api -- node app.js --port 3000
```

### Python, Ruby, shell, and custom interpreters

```bash
spm start worker.py --name worker
spm start server.rb --name web
spm start cleanup.sh --name cleanup
spm start worker.ps1 --name windows-worker
spm start worker.ts --name typescript-worker --interpreter bun
```

spm recognizes `.js`, `.mjs`, `.cjs`, `.py`, `.rb`, `.sh`, and `.ps1`.
PowerShell scripts use Windows PowerShell on Windows and `pwsh` on Linux or
macOS. Use `--interpreter` to override the default or handle another type.

### Native commands and application arguments

Put a complete command after `--`:

```bash
spm start --name proxy -- /opt/proxy/bin/proxy --port 8080 --verbose
```

Everything after `--` belongs to the application, even when an argument has the same name as an spm option:

```bash
spm start --name public-api -- ./server --name internal-api --port 3000
```

### Working directory and environment

```bash
spm start app.js \
  --name api \
  --cwd /opt/api \
  --env NODE_ENV=production \
  --env-file /opt/api/.env \
  --restart always \
  --restart-sec 5s
```

Use `--env-file` for secrets. Values passed with `--env` are stored in the generated unit and saved configuration.

## Which command should I use?

| Goal | Command |
| --- | --- |
| Keep a process running | `spm start` |
| Run a job on a schedule and let it exit | `spm schedule` |
| Restart a long-running service periodically | `spm start --cron-restart` |
| Run a service as root or another system user | `sudo spm --system start` |
| Manage several services from a file | `spm apply spm.toml` |

The distinction between `start` and `schedule` is important: use `start` for servers and workers, and `schedule` for backups, checks, synchronization jobs, and other commands that finish.

## Everyday commands

| Command | Purpose |
| --- | --- |
| `spm list` | List managed services |
| `spm list --watch` | Continuously refresh CPU, memory, and status |
| `spm show NAME` | Show an spm configuration and runtime summary |
| `spm status NAME` | Show native `systemctl status` output |
| `spm logs NAME -f` | Follow logs |
| `spm restart NAME` | Restart using the current unit |
| `spm restart --update NAME` | Regenerate the unit from saved configuration, then restart |
| `spm stop NAME` | Stop now, but keep boot enablement |
| `spm disable NAME` | Stop and disable boot startup |
| `spm enable NAME` | Enable and start |
| `spm delete NAME` | Stop and remove the service and companion units |
| `spm cat NAME` | Print the generated unit and drop-ins |
| `spm edit NAME` | Open a persistent systemd drop-in editor |

Lifecycle commands accept several names or `all`:

```bash
spm restart api worker
spm stop all
spm delete all --yes
```

`all` only selects units created by spm. Deleting all services requires `--yes`.

### Logs

```bash
spm logs api                 # last 100 entries
spm logs api -n 20           # last 20 entries
spm logs api -f              # follow
spm logs api worker -f       # merge several services
spm logs                     # merge all spm services
spm logs api --since 1h --grep ERROR
spm logs api --boot --output json
```

Windows/macOS scheduled-task output (`service.log`) and scheduler diagnostics
(`scheduler.log`) rotate at 10 MiB and retain five backups (`.1` through `.5`).
Rotation is applied while data is being written, including during one
long-running scheduled invocation. Linux log capacity remains controlled by
journald.

### Change an existing service

Repeat the original start command with `--force`:

```bash
spm start app.js --name api --env NODE_ENV=production --force
```

Settings omitted from a `--force` update are normally inherited. Clear them explicitly when needed:

```bash
spm start app.js --name api --force --clear-env
spm start app.js --name api --force --no-cron-restart
spm start app.js --name api --force --no-max-memory
```

Small changes can also use `set` and `unset`:

```bash
spm set api --env NODE_ENV=production --restart-sec 5s
spm unset api --env OLD_KEY
```

spm keeps previous saved configurations:

```bash
spm history api
spm rollback api
spm rollback api --revision 2
spm clone api api-test
```

## Scheduled jobs

Create a oneshot job that runs every 30 minutes:

```bash
spm schedule --name checker \
  --cron "*/30 * * * *" \
  --persistent \
  -- node ./scripts/check.js
```

Run it once immediately without waiting for the timer:

```bash
spm run checker
```

Or run immediately while creating the schedule:

```bash
spm schedule --name checker --cron "*/30 * * * *" \
  --run-now -- node ./scripts/check.js
```

Interval timers are also supported:

```bash
spm schedule --name cache-sync \
  --on-boot 5min \
  --interval 30min \
  --randomized-delay 2min \
  -- ./sync-cache
```

`--persistent` catches up a missed calendar run after downtime. `--randomized-delay` helps avoid many hosts starting the same job together. Use `--timezone Asia/Singapore` with `--cron` when the server's local timezone is not appropriate.

Scheduling is available on Linux, Windows, and macOS. Portable cron expressions
use either five fields (`minute hour day month weekday`) or six fields (`second
minute hour day month weekday`) and support numbers, `*`, lists, ranges, and
steps. Windows and macOS use one on-demand scheduler per user/system scope; it
sleeps until the nearest occurrence and asks Task Scheduler or launchd to run
the task under its declared account. Linux continues to use native systemd
timers. Five-field expressions remain compatible and run at second zero.

For example, this six-field expression runs every day at `04:00:30`:

```bash
spm schedule --name precise --cron "30 0 4 * * *" -- ./job
```

### Periodically restart a long-running service

This is different from a scheduled job:

```bash
spm start server.js --name api \
  --cron-restart "0 4 * * *" \
  --timezone Asia/Singapore
```

spm creates and manages a companion systemd timer. Cron expressions use five
fields or six fields with leading seconds. Generated systemd calendar
expressions are validated before installation.

## System services

User mode is the default and does not need sudo. Use system mode only when the process needs system-level privileges, ownership, or dependencies:

```bash
sudo spm --system start /opt/api/server --name api
sudo spm --system status api
sudo spm --system logs api -f
sudo spm --system restart api
```

Run a system service as a non-root account:

```bash
sudo spm --system start /opt/api/server \
  --name api \
  --user www-data \
  --group www-data
```

The executable, working directory, environment file, and writable paths must be accessible to that account. spm resolves relative commands using the target user's home directory and search paths.

Important rules:

- Put global `--system` before the command.
- Keep using `--system` for every later operation on that service.
- User and system services are separate namespaces and may have the same name.
- Do not run `sudo spm` without `--system`; that targets root's user manager instead of the system manager.

User units live in `~/.config/systemd/user`. System units live in `/etc/systemd/system`.

## Declarative configuration

Use `spm.toml` when several services should be reviewed and applied together:

```toml
schema = 1

[[services]]
name = "api"
command = ["node", "app.js", "--port", "3000"] # common defaults
restart = "always"
restart_sec = "3s"

[services.linux]
cwd = "/opt/api"
max_memory = "512M"

[services.windows]
cwd = "C:\\apps\\api"

[services.macos]
cwd = "/Applications/api"

[[services]]
name = "worker"
cwd = "/opt/worker"
script = "worker.py"
args = ["--queue", "default"]
interpreter = "python3"
enable = false

[[services]]
name = "database"
command = ["./database"]

[[services]]
name = "frontend"
command = ["./frontend"]
requires = ["database"]
after = ["database"]

[[services]]
name = "backup"
command = ["./backup", "--incremental"]
schedule = "0 2 * * *"
timezone = "Asia/Singapore"
persistent = true
```

Common values apply everywhere. `[services.linux]`, `[services.windows]`, and
`[services.macos]` only override fields that genuinely differ. All platform
blocks are syntax-checked, while each host applies its own block. Dependencies
use the same `after`, `wants`, and `requires` fields: systemd receives native
dependencies; when spm starts services, Windows and macOS use ordered spm
orchestration. Their native boot/login managers may activate enabled jobs in
parallel, so applications should still tolerate concurrent machine startup.

The common UI remains the default. Platform-native details stay available
through an explicit escape hatch:

```text
spm native systemd status api       # Linux
spm native windows inspect api      # Windows
spm native launchd print api        # macOS
```

Preview and apply:

```bash
spm validate spm.toml
spm diff spm.toml
spm apply --dry-run spm.toml
spm apply spm.toml
```

Export existing services:

```bash
spm export all > spm.toml
```

Apply is declarative for services present in the file: omitted optional settings return to defaults. Services not listed in the file are not deleted. The file's directory is the default working directory.

## Readiness and health checks

Wait for an application to become ready during `spm start`:

```bash
spm start --name api \
  --wait-http http://127.0.0.1:3000/health \
  --wait-timeout 30s \
  -- node server.js
```

HTTP, TCP, and command readiness probes are available through `--wait-http`, `--wait-tcp`, and `--wait-command`. They run in the invoking spm process and do not create background services.

Add a periodic health check:

```bash
spm start --name api \
  --health-http http://127.0.0.1:3000/health \
  --health-interval 30s \
  --health-timeout 5s \
  --health-retries 3 \
  --health-action restart \
  -- node server.js
```

Inspect health state and logs:

```bash
spm health api
spm logs api --health
```

Periodic checks use short-lived systemd oneshot units and timers; spm still does not run a daemon. The default action is `none`, which only records failures. Available actions are `none`, `restart`, and `stop`.

## Resource limits and security

Resource options map directly to systemd cgroup controls:

```bash
spm start --name api \
  --max-memory 512M \
  --max-cpu 200% \
  --max-tasks 100 \
  --open-files 65535 \
  -- node server.js
```

`--max-memory` is a hard cgroup limit. If the process is OOM-killed, its restart policy determines whether it starts again.

Apply a security preset:

```bash
spm start --name api --sandbox basic -- node server.js
spm security api
```

`basic` protects the home directory and system paths. `strict` adds kernel, module, and SUID restrictions. The working directory remains writable. User-mode sandboxing requires unprivileged user namespaces; run `spm doctor` to check support.

Advanced systemd settings are available without editing a unit:

```bash
spm start --name api \
  --after network-online.target \
  --requires redis.service \
  --exec-start-pre '/usr/bin/test -f /opt/api/config.json' \
  --exec-reload '/bin/kill -HUP $MAINPID' \
  --property Nice=5 \
  -- node server.js

spm reload api
```

Core properties controlled by spm, such as `ExecStart`, `WorkingDirectory`, `Environment`, `Restart`, and `User`, cannot be overridden with `--property`.

## Multiple instances

Run several fork-mode instances with a systemd template unit:

```bash
spm start server.js --name api --instances 4 \
  --env 'PORT=300{{instance}}'

spm scale api 8
spm restart api
spm logs api -f
```

Each instance receives `SPM_INSTANCE` and `NODE_APP_INSTANCE`. `{{instance}}` is replaced in arguments, environment values, and PID files. Restarts are rolling and scaling leaves unchanged instances running.

This is not PM2 cluster mode: instances do not share a listening socket. Give each instance a different port behind a load balancer, or make the application use `SO_REUSEPORT`. Instances cannot currently be combined with schedules, cron restart, readiness probes, or health checks.

## Optional: mise integration

If a project uses mise, add `--mise` to run the application through `mise exec --`:

```bash
cd /opt/my-app
mise install
spm start --name api --mise -- node app.js --port 3000
```

The shorter script form works too:

```bash
spm start app.js --name api --mise
```

spm does not pin the resolved Node.js or other tool binary. Tool versions and `[env]` from `mise.toml` are reevaluated whenever the service starts. After changing a version, use a normal restart:

```bash
mise use node@24
spm restart api
```

Use `--no-mise` with `--force` to remove an inherited mise setting. In system mode with `--user`, spm finds mise from the target user's home directory and search paths instead of root's environment.

Snap normally launches mise through `snap run`, which can move child processes out of the service cgroup. spm detects a classic Snap installation and invokes its internal mise executable directly, preserving process cleanup, resource accounting, limits, and unit-scoped logs.

mise support is optional. spm does not install mise or any language runtime.

## Native systemd access

spm creates ordinary systemd units, so native tools continue to work:

```bash
systemctl --user status spm-api.service
journalctl --user --unit spm-api.service --follow
systemctl --user cat spm-api.service
```

`spm status` intentionally shows native systemctl output. `spm show` and `spm describe` show the friendlier spm summary. `spm cat` prints the final unit, while `spm edit` stores manual changes in a drop-in that survives `spm start --force`.

Existing simple units can be imported:

```bash
spm import /etc/systemd/system/api.service --name api
```

spm refuses unit semantics it cannot preserve safely, such as socket activation and oneshot services.

Saved normalized configurations use mode `0600` and live in:

```text
~/.config/spm/services/<name>.json
/etc/spm/services/<name>.json    # system mode
```

## PM2 command map

| PM2 | spm |
| --- | --- |
| `pm2 start index.js --name api` | `spm start index.js --name api` |
| `pm2 ls` | `spm list` |
| `pm2 show api` | `spm show api` |
| `pm2 logs api` | `spm logs api -f` |
| `pm2 restart api` | `spm restart api` |
| `pm2 reload api` | `spm reload api` |
| `pm2 stop api` | `spm stop api` |
| `pm2 delete api` | `spm delete api` |
| `pm2 sendSignal SIGUSR2 api` | `spm signal SIGUSR2 api` |
| `pm2 jlist` | `spm list --json` |
| `pm2 monit` | `spm list --watch` |
| `pm2 start app.js -i 4` in fork mode | `spm start app.js -i 4` |
| `pm2 scale api 8` | `spm scale api 8` |
| `pm2 startup` | `spm startup` |
| `pm2 save` | Not needed; spm enables services when they are created. |
| PM2 ecosystem file | `spm export all > spm.toml`, then `spm apply spm.toml` |

## Agent and MCP integration

`spm` includes a local stdio MCP server so Codex and other MCP clients can
inspect and manage services through focused, structured tools:

```bash
spm mcp
```

The repository also ships an agent skill,
[`plugins/spm/skills/spm/SKILL.md`](plugins/spm/skills/spm/SKILL.md), that
teaches an agent to start long-lived processes with spm instead of `&` or
`nohup`, to check them with bounded log reads, and to ask before deleting or
using `--system`. Any agent that reads `SKILL.md` files can use it; copy the
`spm` directory into the agent's skills folder (for example
`~/.claude/skills/` or `~/.codex/skills/`).

### Claude Code plugin

The plugin bundles the MCP server and the skill:

```bash
claude plugin marketplace add eyvant/spm
claude plugin install spm@eyvant-spm
```

Inside a session, `/plugin marketplace add eyvant/spm` does the same. The
plugin runs the `spm` on your `PATH`, so install spm first.

### Codex

Add it to Codex after installing `spm`:

```bash
codex mcp add spm -- spm mcp
```

Or add the server directly to `~/.codex/config.toml` (or a trusted project's
`.codex/config.toml`):

```toml
[mcp_servers.spm]
command = "spm"
args = ["mcp"]
default_tools_approval_mode = "writes"
```

Restart the Codex client after changing its configuration. The server exposes
read-only tools for listing, inspecting, diagnostics, and bounded log reads,
plus focused write tools for creating and controlling services. The
`spm_run_cli` escape hatch covers all other non-interactive CLI functionality,
including schedules, signals, scaling, configuration revisions, declarative
apply/diff, import/export, health, and native inspection. Interactive editors
and unbounded `logs --follow` or `list --watch` calls are intentionally rejected
because an MCP tool call must finish. The general CLI tool and service deletion
are marked destructive so MCP hosts can request approval. Machine-wide calls
use the tool's `system` option and remain subject to normal platform privilege
checks.

### Claude Code without the plugin

```bash
claude mcp add spm -- spm mcp
```

Run `/mcp` inside Claude Code to verify that the server is connected and its
tools are available.

### Cursor and VS Code

Use the install buttons in [Built for coding agents](#built-for-coding-agents),
or add `{"command": "spm", "args": ["mcp"]}` as a stdio server named `spm` in
`.cursor/mcp.json` or VS Code's `mcp.json` (under `servers`).

### Claude Desktop

For Claude Desktop, add the following entry to
`claude_desktop_config.json` and fully restart the app:

```json
{
  "mcpServers": {
    "spm": {
      "command": "spm",
      "args": ["mcp"]
    }
  }
}
```

Claude Desktop may start with a minimal `PATH`. If it cannot find `spm`, replace
the command with the absolute path to `spm` or `spm.exe`. On Windows the config
file is normally `%APPDATA%\Claude\claude_desktop_config.json`; on macOS it is
`~/Library/Application Support/Claude/claude_desktop_config.json`.

Secrets should stay in an environment file referenced by `env_file`; do not put
secret values directly in MCP tool arguments.

## Shell completion

Bash:

```bash
mkdir -p ~/.local/share/bash-completion/completions
spm completion bash > ~/.local/share/bash-completion/completions/spm.bash
```

Zsh:

```zsh
mkdir -p ~/.zfunc
spm completion zsh > ~/.zfunc/_spm
fpath=(~/.zfunc $fpath)
autoload -Uz compinit && compinit
```

Fish:

```fish
mkdir -p ~/.config/fish/completions
spm completion fish > ~/.config/fish/completions/spm.fish
```

Completion understands subcommands, options, enum values, and managed service names. It switches to system services when `--system` is present.

PowerShell:

```powershell
spm completion powershell | Out-String | Invoke-Expression
```

## Troubleshooting

Start with:

```bash
spm doctor
spm status NAME
spm logs NAME -n 100
```

For system mode:

```bash
sudo spm --system doctor
sudo spm --system status NAME
```

`doctor` checks systemd features, manager access, `XDG_RUNTIME_DIR`, lingering, journald, unit permissions, mise, user namespaces, and whether the spm executable path is stable. `FAIL` returns a non-zero exit status; `WARN` reports a risk without failing.

Every command also has focused help:

```bash
spm --help
spm start --help
spm schedule --help
spm logs --help
```

## Build and test

```bash
go test -race ./...
go vet ./...
go build -o spm ./cmd/spm
```

Release builds inject the version with ldflags:

```bash
go build \
  -ldflags "-X github.com/eyvant/spm/internal/app.version=0.1.0" \
  -o spm ./cmd/spm
```

GitHub Actions runs tests, vet, builds, and real lifecycle integration tests on
Ubuntu, Windows Server, and macOS runners. Every platform exercises user and
system scopes, lifecycle operations, logs, restart behavior, dependencies, and
declarative validate/apply/diff. Linux additionally verifies native systemd
units and timers, Windows verifies Startup shortcuts, SCM dependencies and
service accounts, and macOS verifies LaunchAgents and LaunchDaemons. Releases
include Linux, Windows, and macOS archives.

## License

spm is available under the [MIT License](LICENSE).

## Current limitations

- Linux requires systemd. Windows 10/11 and Windows Server use the per-user
  Startup folder and the Service Control Manager. macOS uses launchd.
- Windows currently supports the core lifecycle, logs, restart policies,
  readiness checks, user/system scopes, and selectable system accounts.
  Health timers, instances, resource limits, and systemd unit import remain
  Linux-specific. Scheduled system tasks on Windows currently use SYSTEM,
  LocalService, or NetworkService. macOS supports the common lifecycle, logs,
  declarations, restart policies, readiness checks, dependencies, and both
  LaunchAgent and LaunchDaemon scopes.
- Cross-platform schedules use native activation plus shared SPM semantics;
  see [the scheduling design](docs/cross-platform-scheduling.md).
- PM2 cluster-mode socket sharing, watch mode, deployment, and remote management are not implemented.
- `--instances` provides fork-mode instances, not PM2 cluster mode.
- spm does not install language runtimes or runtime managers.

TDQS

A4.4/5.0

Scored across 12 tools

Disambiguation5/5

Each tool targets a distinct service-management action; start vs enable and stop vs disable are explicitly differentiated in their descriptions, and spm_run_cli is positioned as a fallback only when no focused tool exists. No two tools appear to do the same thing.

Naming Consistency4/5

All tools use the spm_ prefix and snake_case, with a consistent verb_noun pattern for lifecycle and query operations. spm_doctor is the only noun-only name, a minor deviation from the otherwise predictable convention.

Tool Count5/5

Twelve tools is well within the appropriate range for a service manager, covering discovery, inspection, lifecycle, diagnostics, and an escape hatch without bloat. Each tool earns its place.

Completeness5/5

The set covers create/read/update/delete and full lifecycle operations (start, stop, restart, enable, disable), plus logs and diagnostics; configuration updates and advanced operations are available through spm_run_cli. No obvious dead ends exist for the stated domain.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues