toolguard-daemon-control

将长时间运行的进程作为 macOS 启动的服务进行管理。当要求启动、停止、重新启动、检查后台服务/守护程序的状态或管理后台服务/守护程序时使用。处理 launchd plist 创建、服务生命周期和日志访问。对于任何应在当前会话之外持续存在的进程，请使用此选项而不是后台执行。

# toolguard-daemon-control

Manage any executable as a persistent macOS launchd user agent.

## Overview

Services are installed as `~/Library/LaunchAgents/ai.toolguard.<name>.plist` and run as user-level launch agents. They auto-restart on failure and log to `~/Library/Logs/toolguard/`.

## Scripts

All scripts are in `scripts/` relative to this skill's directory. Run them with `bash`.

### install.sh — Create and start a service

```bash
bash scripts/install.sh <service-name> <command> [args...] [--workdir <dir>] [--env KEY=VALUE ...]
```

- `service-name`: Short identifier (e.g., `toolguard-proxy`). Used in plist filename and log paths.
- `command`: Absolute path to the executable.
- `args`: Arguments passed to the command.
- `--workdir <dir>`: Working directory for the process (default: `$HOME`).
- `--env KEY=VALUE`: Environment variables (repeatable).

Example:
```bash
bash scripts/install.sh toolguard-proxy /usr/local/go/bin/go run ./cmd/server --config toolguard.dev.yaml --workdir ~/Documents/toolguard
```

### uninstall.sh — Stop and remove a service

```bash
bash scripts/uninstall.sh <service-name>
```

Unloads the service and removes the plist file. Logs are preserved.

### status.sh — Check service status

```bash
bash scripts/status.sh [service-name]
```

Without arguments, lists all `ai.toolguard.*` services. With a name, shows detailed status for that service.

### logs.sh — View service logs

```bash
bash scripts/logs.sh <service-name> [--follow] [--lines <n>]
```

Shows stdout and stderr logs. Default: last 50 lines.

### list.sh — List all managed services

```bash
bash scripts/list.sh
```

Lists all installed `ai.toolguard.*` services with their running state.

## Notes

- Services run as the current user (no sudo required).
- Services auto-restart on crash (`KeepAlive = true`).
- To run a Go project, use the compiled binary path or wrap in a shell script — launchd does not support `go run` directly. Use `go build` first, then point to the binary.
- Log directory: `~/Library/Logs/toolguard/<service-name>/`
- Plist location: `~/Library/LaunchAgents/ai.toolguard.<service-name>.plist`

---

## 中文说明

# toolguard-daemon-control

将任意可执行文件作为持久化的 macOS launchd 用户代理（user agent）进行管理。

## 概述

服务被安装为 `~/Library/LaunchAgents/ai.toolguard.<name>.plist`，并作为用户级启动代理运行。它们在失败时会自动重启，并将日志记录到 `~/Library/Logs/toolguard/`。

## 脚本

所有脚本都位于相对于本技能目录的 `scripts/` 中。使用 `bash` 运行它们。

### install.sh — 创建并启动服务

```bash
bash scripts/install.sh <service-name> <command> [args...] [--workdir <dir>] [--env KEY=VALUE ...]
```

- `service-name`：短标识符（例如 `toolguard-proxy`）。用于 plist 文件名和日志路径。
- `command`：可执行文件的绝对路径。
- `args`：传递给该命令的参数。
- `--workdir <dir>`：进程的工作目录（默认：`$HOME`）。
- `--env KEY=VALUE`：环境变量（可重复使用）。

示例：
```bash
bash scripts/install.sh toolguard-proxy /usr/local/go/bin/go run ./cmd/server --config toolguard.dev.yaml --workdir ~/Documents/toolguard
```

### uninstall.sh — 停止并移除服务

```bash
bash scripts/uninstall.sh <service-name>
```

卸载该服务并删除 plist 文件。日志会被保留。

### status.sh — 检查服务状态

```bash
bash scripts/status.sh [service-name]
```

不带参数时，列出所有 `ai.toolguard.*` 服务。带名称时，显示该服务的详细状态。

### logs.sh — 查看服务日志

```bash
bash scripts/logs.sh <service-name> [--follow] [--lines <n>]
```

显示 stdout 和 stderr 日志。默认：最后 50 行。

### list.sh — 列出所有受管服务

```bash
bash scripts/list.sh
```

列出所有已安装的 `ai.toolguard.*` 服务及其运行状态。

## 注意事项

- 服务以当前用户身份运行（无需 sudo）。
- 服务在崩溃时会自动重启（`KeepAlive = true`）。
- 要运行 Go 项目，请使用编译后的二进制文件路径或将其包装在 shell 脚本中——launchd 不直接支持 `go run`。请先执行 `go build`，然后指向该二进制文件。
- 日志目录：`~/Library/Logs/toolguard/<service-name>/`
- Plist 位置：`~/Library/LaunchAgents/ai.toolguard.<service-name>.plist`