Metadata-Version: 2.4
Name: nginx-proxy-manager-ctl
Version: 0.5.3
Summary: CLI for Nginx Proxy Manager API automation
License-Expression: MIT
Requires-Dist: httpx>=0.28.0
Requires-Dist: platformdirs>=4.3.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: rich>=13.9.0
Requires-Dist: typer>=0.15.0
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/NightWatcher314/npmctl
Project-URL: Repository, https://github.com/NightWatcher314/npmctl
Project-URL: Issues, https://github.com/NightWatcher314/npmctl/issues
Description-Content-Type: text/markdown

# npmctl

[English](README.md) | [中文](README-zh.md)

`npmctl` is a Python CLI for automating [Nginx Proxy Manager](https://nginxproxymanager.com/) through its API.

`npmctl` is built as an AI-native operations tool. The repository includes a Codex skill at [`skills/nginx-proxy-manager/SKILL.md`](skills/nginx-proxy-manager/SKILL.md), so an AI agent can manage Nginx Proxy Manager with explicit safety rules, command shapes, and verification steps instead of guessing raw API calls.

It focuses on safe Proxy Host workflows: creating and updating hosts without clobbering unspecified fields, matching existing certificates, safely reissuing custom-manager certificates for replacement domain sets, managing raw `advanced_config` snippets, configuring custom locations, and validating changes. It also covers audit, proxy verify/lint, snapshot/diff/restore, and reusable presets so operators and agents can review and recover NPM state before making changes. When used with a custom multi-agent NPM manager build, it can also manage remote NPM agent nodes and send proxy/certificate operations to a selected node.

`npmctl` talks to Nginx Proxy Manager by sending requests to its REST API. It has been tested against Nginx Proxy Manager `2.14.0` and the user-maintained multi-agent NPM manager in this workspace; compatibility with other Nginx Proxy Manager versions is not guaranteed.

## AI-Native Skill

The included `nginx-proxy-manager` skill teaches agents to use `npmctl` as the stable executor for Nginx Proxy Manager changes.

Key rules encoded in the skill:

- Never put URL paths in `forward_host`; targets are origin URLs like `http://host:port`.
- Use host-level `advanced_config` for host snippets and location-level `advanced_config` for custom location snippets.
- Preserve unspecified fields, existing snippets, and existing locations during updates.
- Verify mutations with `npmctl proxy get DOMAIN -o json`, `npmctl proxy verify DOMAIN`, and `npmctl proxy test DOMAIN --scheme auto --fail-on-5xx` for public hosts.
- Use audit/lint/snapshot/diff before risky changes before risky changes.
- Require explicit user intent for destructive actions such as delete, clearing snippets, restoring snapshots, or removing locations.

## Install

With Homebrew:

```bash
brew tap NightWatcher314/homebrew-formula
brew install npmctl
```

With uv from PyPI:

```bash
uv tool install nginx-proxy-manager-ctl
```

For development:

```bash
UV_NO_CONFIG=1 UV_DEFAULT_INDEX=https://pypi.org/simple uv sync --locked
UV_NO_CONFIG=1 UV_DEFAULT_INDEX=https://pypi.org/simple uv run --locked npmctl --help
```

## Configure

Create a profile and log in:

```bash
npmctl config profile add home --url https://nginx.example.com --use
npmctl auth login --identity admin@example.com
npmctl auth status
```

Use a specific profile for one command:

```bash
NPMCTL_PROFILE=home npmctl proxy list
```

Inspect the active configuration:

```bash
npmctl config get
npmctl doctor
npmctl doctor --agents -o yaml
```

## Multi-Agent Manager Builds

Custom NPM manager builds can expose `/api/agents` plus `agent_id` forwarding for Nginx resources. `npmctl` supports those endpoints:

```bash
npmctl agent list -o json
npmctl agent add --name edge-114 --url http://REMOTE_NPM:81 --identity admin@example.com --password-stdin
npmctl agent test 1
```

Target one remote node for a command, a profile, or the current shell:

```bash
npmctl proxy list --agent-id 1
npmctl cert list --agent-id 1 -o json
npmctl config set-agent-id 1
NPMCTL_AGENT_ID=1 npmctl proxy apply app.example.com --to http://192.168.1.10:8080 --cert auto
```

Use `npmctl config set-agent-id local` to clear the profile default and operate on the manager itself. Remote agent credentials are stored by the manager; prefer a dedicated service/admin account on the remote node.

## Proxy Hosts

List and inspect Proxy Hosts:

```bash
npmctl proxy list
npmctl proxy get app.example.com -o json
```

Create or update a host:

```bash
npmctl proxy apply app.example.com \
  --to http://192.168.1.10:8080 \
  --cert auto \
  --force-ssl \
  --websocket \
  --http2
```

`proxy apply` preserves existing fields that are not specified on the command line. This is intended to make repeated automation safe.

Test a public host with a structured health result. `--scheme auto` tries HTTPS first and falls back to HTTP only when HTTPS cannot be reached. By default 5xx responses exit non-zero; use `--expect-status` when a specific status is required.

```bash
npmctl proxy test app.example.com --scheme auto --timeout 10 --expect-status 200 -o yaml
npmctl proxy test app.example.com --scheme https --allow-5xx -o json
```


## Safety Workflows

Use these command families for safer agent-assisted operations. They are read-only by default except for explicit restore/preset apply operations.

Audit an NPM instance before a maintenance session:

```bash
npmctl audit run -o yaml
npmctl audit run --agent-id 1 -o json
```

Verify or lint proxy hosts after edits. `proxy verify` performs active checks of a specific host, while `proxy lint` performs static checks such as path-in-target mistakes, missing certificates, or risky snippet patterns:

```bash
npmctl proxy verify app.example.com --agent-id 1
npmctl proxy lint app.example.com -o yaml
```

Create a backup before larger changes, compare current state to a snapshot, and restore only with explicit intent:

```bash
npmctl proxy snapshot app.example.com --agent-id 1 --file npm-proxy-before.json
npmctl proxy diff app.example.com --agent-id 1 --file npm-proxy-before.json
npmctl proxy restore app.example.com --agent-id 1 --file npm-proxy-before.json --dry-run
npmctl proxy restore app.example.com --agent-id 1 --file npm-proxy-before.json --yes
```

Reusable presets cover common advanced_config snippets such as Authentik forward-auth, large uploads, long timeouts, SSE/token streaming, and root redirects:

```bash
npmctl preset list
npmctl preset show streaming-sse
npmctl preset apply app.example.com streaming-sse --dry-run
npmctl preset apply app.example.com large-upload --client-max-body-size 500m
```

## Certificates

List certificates, find the best match for a domain, and safely reissue an existing certificate ID on custom NPM manager builds that support certificate reissue:

```bash
npmctl cert list -o json
npmctl cert match app.example.com -o json
npmctl cert reissue-analyze 12 --domains "app.example.com www.example.com" -o yaml
npmctl cert reissue 12 --domains "app.example.com www.example.com" --yes
```

`cert reissue` first performs the same safety analysis as `cert reissue-analyze`. If removing domains would uncover proxy/redirection/dead hosts, use `--detach-uncovered-hosts` only when you intentionally want those hosts to stop referencing the certificate. Stream hosts block reissue and must be handled manually in NPM.

## Advanced Config

Set host-level `advanced_config` from stdin:

```bash
npmctl proxy advanced set app.example.com --stdin <<'NGINX'
if ($request_uri = "/") {
    return 302 /management.html;
}
NGINX
```

Set a custom location and its location-level `advanced_config`:

```bash
npmctl proxy location apply app.example.com /api --to http://192.168.1.10:8081
npmctl proxy location advanced set app.example.com /api --stdin <<'NGINX'
proxy_set_header X-Forwarded-Prefix /api;
NGINX
```

Targets must be origin URLs such as `http://host:port`. Do not put URL paths in `forward_host`; use custom locations, `forward_path`, or Nginx snippets for path behavior.

## Authentication and Storage

By default, `npmctl` saves API tokens but not passwords. To save a password in the active profile:

```bash
NPMCTL_PASSWORD='...' npmctl auth login --identity admin@example.com --save-password
```

Later logins can reuse the saved password:

```bash
npmctl auth login --use-saved-password
```

`npmctl doctor --agents` can diagnose configured remote agents. If manager or remote-agent credentials are stale, npmctl adds a JWT-expired hint that points to `npmctl auth login` for manager tokens or `npmctl agent update AGENT_ID --password-stdin` for remote agent credentials.

Remove only the saved plaintext password while keeping the profile and token:

```bash
npmctl auth forget-password
```

The config file is stored at `~/.config/npmctl/config.json` with mode `0600`, but saved passwords are still plaintext. Only use `--save-password` on machines you trust.

## Publishing

PyPI releases use GitHub Trusted Publishing. After pushing an existing release
tag, dispatch `.github/workflows/publish-pypi.yml` with the tag name:

```bash
gh workflow run publish-pypi.yml --ref main -f tag=v0.5.3
```

The workflow verifies the tag and package versions, builds from that tag, and
publishes with GitHub OIDC. Do not store a long-lived PyPI token in GitHub.

## License

MIT
