From 072e360ae8ce675bef3871ca328f3cdda3ea06da Mon Sep 17 00:00:00 2001 From: Owen Date: Tue, 15 Sep 2026 17:03:16 -0400 Subject: [PATCH] Update docs --- .github/workflows/docs-on-pr-close.yml | 2 +- docs/pangolin.md | 1 + docs/pangolin_configure.md | 6 ++++- docs/pangolin_service.md | 29 ++++++++++++++++++++ docs/pangolin_service_install.md | 16 +++++++++++ docs/pangolin_service_install_client.md | 33 +++++++++++++++++++++++ docs/pangolin_service_install_site.md | 27 +++++++++++++++++++ docs/pangolin_service_logs.md | 16 +++++++++++ docs/pangolin_service_logs_client.md | 23 ++++++++++++++++ docs/pangolin_service_logs_site.md | 23 ++++++++++++++++ docs/pangolin_service_status.md | 16 +++++++++++ docs/pangolin_service_status_client.md | 18 +++++++++++++ docs/pangolin_service_status_site.md | 18 +++++++++++++ docs/pangolin_service_uninstall.md | 16 +++++++++++ docs/pangolin_service_uninstall_client.md | 18 +++++++++++++ docs/pangolin_service_uninstall_site.md | 18 +++++++++++++ docs/pangolin_up.md | 3 +++ docs/pangolin_up_client.md | 9 +++++++ docs/pangolin_up_site.md | 25 +++++++++++++++++ 19 files changed, 315 insertions(+), 2 deletions(-) create mode 100644 docs/pangolin_service.md create mode 100644 docs/pangolin_service_install.md create mode 100644 docs/pangolin_service_install_client.md create mode 100644 docs/pangolin_service_install_site.md create mode 100644 docs/pangolin_service_logs.md create mode 100644 docs/pangolin_service_logs_client.md create mode 100644 docs/pangolin_service_logs_site.md create mode 100644 docs/pangolin_service_status.md create mode 100644 docs/pangolin_service_status_client.md create mode 100644 docs/pangolin_service_status_site.md create mode 100644 docs/pangolin_service_uninstall.md create mode 100644 docs/pangolin_service_uninstall_client.md create mode 100644 docs/pangolin_service_uninstall_site.md create mode 100644 docs/pangolin_up_site.md diff --git a/.github/workflows/docs-on-pr-close.yml b/.github/workflows/docs-on-pr-close.yml index 7d2da2f..c2d97cf 100644 --- a/.github/workflows/docs-on-pr-close.yml +++ b/.github/workflows/docs-on-pr-close.yml @@ -30,7 +30,7 @@ jobs: - name: Set up Go uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 with: - go-version: 1.25 + go-version: 1.26 - name: Generate markdown documentation run: make docs diff --git a/docs/pangolin.md b/docs/pangolin.md index 1c48179..e4e1579 100644 --- a/docs/pangolin.md +++ b/docs/pangolin.md @@ -23,6 +23,7 @@ Pangolin CLI * [pangolin reset-dns](pangolin_reset-dns.md) - Force-clear stale DNS overrides * [pangolin scp](pangolin_scp.md) - Run scp using just-in-time SSH certificates * [pangolin select](pangolin_select.md) - Select account information to use +* [pangolin service](pangolin_service.md) - Manage background services that keep a site or client running persistently * [pangolin ssh](pangolin_ssh.md) - Run an interactive SSH session * [pangolin status](pangolin_status.md) - Status commands * [pangolin up](pangolin_up.md) - Start a connection diff --git a/docs/pangolin_configure.md b/docs/pangolin_configure.md index 0b5549f..3f613ee 100644 --- a/docs/pangolin_configure.md +++ b/docs/pangolin_configure.md @@ -5,12 +5,15 @@ Configure a local AI client to use a Pangolin AI gateway resource ### Synopsis Writes local config files (e.g. ~/.claude/settings.json) so an AI client talks to a Pangolin -resource acting as an AI gateway. Supported clients: claude, codex, opencode. +resource acting as an AI gateway. Supported clients: claude, codex, opencode, gemini. If [key] is omitted, an API key is fetched automatically for public resources (private/site resources need no key). Pass [key] to configure with a credential obtained elsewhere without making any API calls for it. +Pass --reset to undo this: it deletes exactly the settings this command writes (it can't +restore values they replaced) and leaves the rest of those files untouched. + ``` pangolin configure [key] [flags] ``` @@ -20,6 +23,7 @@ pangolin configure [key] [flags] ``` -h, --help help for configure --org string Organization ID (defaults to your active org) + --reset Remove the settings this command writes for instead of writing them --resource string Resource niceId or domain to configure against (defaults to auto-pick/prompt) ``` diff --git a/docs/pangolin_service.md b/docs/pangolin_service.md new file mode 100644 index 0000000..b011073 --- /dev/null +++ b/docs/pangolin_service.md @@ -0,0 +1,29 @@ +## pangolin service + +Manage background services that keep a site or client running persistently + +### Synopsis + +Install, remove, and monitor background services that run 'pangolin up site' +or 'pangolin up client' persistently, restarting them automatically if they +crash or the machine reboots. + +Backed by systemd on Linux, launchd on macOS, and a Windows Service on +Windows. Must be run as root (Linux/macOS) or from an elevated prompt +(Windows). The client (machine client) service isn't available on Windows +yet, since 'pangolin up client' itself doesn't support Windows. + +### Options + +``` + -h, --help help for service +``` + +### SEE ALSO + +* [pangolin](pangolin.md) - Pangolin CLI +* [pangolin service install](pangolin_service_install.md) - Install and start a background service +* [pangolin service logs](pangolin_service_logs.md) - Follow a background service's logs +* [pangolin service status](pangolin_service_status.md) - Show a background service's status +* [pangolin service uninstall](pangolin_service_uninstall.md) - Stop and remove a background service + diff --git a/docs/pangolin_service_install.md b/docs/pangolin_service_install.md new file mode 100644 index 0000000..4a66db2 --- /dev/null +++ b/docs/pangolin_service_install.md @@ -0,0 +1,16 @@ +## pangolin service install + +Install and start a background service + +### Options + +``` + -h, --help help for install +``` + +### SEE ALSO + +* [pangolin service](pangolin_service.md) - Manage background services that keep a site or client running persistently +* [pangolin service install client](pangolin_service_install_client.md) - Install and start the client background service +* [pangolin service install site](pangolin_service_install_site.md) - Install and start the site (Newt) background service + diff --git a/docs/pangolin_service_install_client.md b/docs/pangolin_service_install_client.md new file mode 100644 index 0000000..27545a2 --- /dev/null +++ b/docs/pangolin_service_install_client.md @@ -0,0 +1,33 @@ +## pangolin service install client + +Install and start the client background service + +### Synopsis + +Install a background service for this machine client, then start it +immediately. + +Intended for machine clients (--id/--secret), which don't have an +interactively logged-in user to restart them. On Windows this only supports +the service itself - 'pangolin up client' has no standalone Windows console +mode (that's handled by the Pangolin desktop app); the service runs the +tunnel directly in-process instead. + +``` +pangolin service install client [flags] +``` + +### Options + +``` + --endpoint string Pangolin server endpoint + -h, --help help for client + --id string Client ID + --org string Organization ID + --secret string Client secret +``` + +### SEE ALSO + +* [pangolin service install](pangolin_service_install.md) - Install and start a background service + diff --git a/docs/pangolin_service_install_site.md b/docs/pangolin_service_install_site.md new file mode 100644 index 0000000..099f707 --- /dev/null +++ b/docs/pangolin_service_install_site.md @@ -0,0 +1,27 @@ +## pangolin service install site + +Install and start the site (Newt) background service + +### Synopsis + +Install a background service for this site, then start it immediately. + +``` +pangolin service install site [flags] +``` + +### Options + +``` + --disable-clients Disable accepting client connections + --disable-ssh Disable Pangolin SSH + --endpoint string Pangolin server endpoint + -h, --help help for site + --id string Site ID + --secret string Site secret +``` + +### SEE ALSO + +* [pangolin service install](pangolin_service_install.md) - Install and start a background service + diff --git a/docs/pangolin_service_logs.md b/docs/pangolin_service_logs.md new file mode 100644 index 0000000..0b19a56 --- /dev/null +++ b/docs/pangolin_service_logs.md @@ -0,0 +1,16 @@ +## pangolin service logs + +Follow a background service's logs + +### Options + +``` + -h, --help help for logs +``` + +### SEE ALSO + +* [pangolin service](pangolin_service.md) - Manage background services that keep a site or client running persistently +* [pangolin service logs client](pangolin_service_logs_client.md) - Follow the client background service logs +* [pangolin service logs site](pangolin_service_logs_site.md) - Follow the site (Newt) background service logs + diff --git a/docs/pangolin_service_logs_client.md b/docs/pangolin_service_logs_client.md new file mode 100644 index 0000000..8d71bb0 --- /dev/null +++ b/docs/pangolin_service_logs_client.md @@ -0,0 +1,23 @@ +## pangolin service logs client + +Follow the client background service logs + +### Synopsis + +Stream the client service's log output. + +``` +pangolin service logs client [flags] +``` + +### Options + +``` + -h, --help help for client + -n, --lines int Number of prior lines to show before following (default 20) +``` + +### SEE ALSO + +* [pangolin service logs](pangolin_service_logs.md) - Follow a background service's logs + diff --git a/docs/pangolin_service_logs_site.md b/docs/pangolin_service_logs_site.md new file mode 100644 index 0000000..a7437fa --- /dev/null +++ b/docs/pangolin_service_logs_site.md @@ -0,0 +1,23 @@ +## pangolin service logs site + +Follow the site (Newt) background service logs + +### Synopsis + +Stream the site service's log output. + +``` +pangolin service logs site [flags] +``` + +### Options + +``` + -h, --help help for site + -n, --lines int Number of prior lines to show before following (default 20) +``` + +### SEE ALSO + +* [pangolin service logs](pangolin_service_logs.md) - Follow a background service's logs + diff --git a/docs/pangolin_service_status.md b/docs/pangolin_service_status.md new file mode 100644 index 0000000..35c429d --- /dev/null +++ b/docs/pangolin_service_status.md @@ -0,0 +1,16 @@ +## pangolin service status + +Show a background service's status + +### Options + +``` + -h, --help help for status +``` + +### SEE ALSO + +* [pangolin service](pangolin_service.md) - Manage background services that keep a site or client running persistently +* [pangolin service status client](pangolin_service_status_client.md) - Show the client background service status +* [pangolin service status site](pangolin_service_status_site.md) - Show the site (Newt) background service status + diff --git a/docs/pangolin_service_status_client.md b/docs/pangolin_service_status_client.md new file mode 100644 index 0000000..043eb66 --- /dev/null +++ b/docs/pangolin_service_status_client.md @@ -0,0 +1,18 @@ +## pangolin service status client + +Show the client background service status + +``` +pangolin service status client [flags] +``` + +### Options + +``` + -h, --help help for client +``` + +### SEE ALSO + +* [pangolin service status](pangolin_service_status.md) - Show a background service's status + diff --git a/docs/pangolin_service_status_site.md b/docs/pangolin_service_status_site.md new file mode 100644 index 0000000..a2a6ed4 --- /dev/null +++ b/docs/pangolin_service_status_site.md @@ -0,0 +1,18 @@ +## pangolin service status site + +Show the site (Newt) background service status + +``` +pangolin service status site [flags] +``` + +### Options + +``` + -h, --help help for site +``` + +### SEE ALSO + +* [pangolin service status](pangolin_service_status.md) - Show a background service's status + diff --git a/docs/pangolin_service_uninstall.md b/docs/pangolin_service_uninstall.md new file mode 100644 index 0000000..9e353af --- /dev/null +++ b/docs/pangolin_service_uninstall.md @@ -0,0 +1,16 @@ +## pangolin service uninstall + +Stop and remove a background service + +### Options + +``` + -h, --help help for uninstall +``` + +### SEE ALSO + +* [pangolin service](pangolin_service.md) - Manage background services that keep a site or client running persistently +* [pangolin service uninstall client](pangolin_service_uninstall_client.md) - Stop and remove the client background service +* [pangolin service uninstall site](pangolin_service_uninstall_site.md) - Stop and remove the site (Newt) background service + diff --git a/docs/pangolin_service_uninstall_client.md b/docs/pangolin_service_uninstall_client.md new file mode 100644 index 0000000..61e50c1 --- /dev/null +++ b/docs/pangolin_service_uninstall_client.md @@ -0,0 +1,18 @@ +## pangolin service uninstall client + +Stop and remove the client background service + +``` +pangolin service uninstall client [flags] +``` + +### Options + +``` + -h, --help help for client +``` + +### SEE ALSO + +* [pangolin service uninstall](pangolin_service_uninstall.md) - Stop and remove a background service + diff --git a/docs/pangolin_service_uninstall_site.md b/docs/pangolin_service_uninstall_site.md new file mode 100644 index 0000000..c9f1af8 --- /dev/null +++ b/docs/pangolin_service_uninstall_site.md @@ -0,0 +1,18 @@ +## pangolin service uninstall site + +Stop and remove the site (Newt) background service + +``` +pangolin service uninstall site [flags] +``` + +### Options + +``` + -h, --help help for site +``` + +### SEE ALSO + +* [pangolin service uninstall](pangolin_service_uninstall.md) - Stop and remove a background service + diff --git a/docs/pangolin_up.md b/docs/pangolin_up.md index 6d29953..00d428f 100644 --- a/docs/pangolin_up.md +++ b/docs/pangolin_up.md @@ -17,6 +17,7 @@ pangolin up [flags] ``` --attach Run in attached (foreground) mode, (default: detached (background) mode) + --disable-relay Disable relay connections (default false) --endpoint string Client endpoint (required if not logged in) -h, --help help for up --holepunch Enable holepunching (default true) @@ -34,6 +35,7 @@ pangolin up [flags] --prefer-local-routes Add tunnel routes with a high metric so overlapping local/connected routes take precedence (default false) --secret string Client secret (optional, will use user info if not provided) --silent Disable TUI and run silently when detached + --subnet-router Enable this client to act as a subnet router: traffic forwarded from the local network is NATed to this client's own tunnel IP before going out over the tunnel. Linux only, requires CAP_NET_ADMIN. (default false) --tls-client-cert path TLS client certificate path --tunnel-dns When enabled, DNS queries are routed through the tunnel for remote resolution. To ensure queries are tunneled correctly, you must define the DNS server as a Pangolin resource and enter its address as an Upstream DNS Server. --upstream-dns strings List of DNS servers to use for external DNS resolution if overriding system DNS @@ -43,4 +45,5 @@ pangolin up [flags] * [pangolin](pangolin.md) - Pangolin CLI * [pangolin up client](pangolin_up_client.md) - Start a client connection +* [pangolin up site](pangolin_up_site.md) - Start a site connection (Newt) diff --git a/docs/pangolin_up_client.md b/docs/pangolin_up_client.md index 89fcc57..9750ea0 100644 --- a/docs/pangolin_up_client.md +++ b/docs/pangolin_up_client.md @@ -6,6 +6,13 @@ Start a client connection Bring up a client tunneled connection. +On Windows, only machine clients are supported: --id, --secret, and +--endpoint must all be passed explicitly. Interactive login isn't +supported - use the desktop app for that. The tunnel also can't run +directly from a console process there, so this installs the same +background service 'pangolin service install client' would, tails its +logs, and removes the service again when you press Ctrl+C. + ``` pangolin up client [flags] ``` @@ -14,6 +21,7 @@ pangolin up client [flags] ``` --attach Run in attached (foreground) mode, (default: detached (background) mode) + --disable-relay Disable relay connections (default false) --endpoint string Client endpoint (required if not logged in) -h, --help help for client --holepunch Enable holepunching (default true) @@ -31,6 +39,7 @@ pangolin up client [flags] --prefer-local-routes Add tunnel routes with a high metric so overlapping local/connected routes take precedence (default false) --secret string Client secret (optional, will use user info if not provided) --silent Disable TUI and run silently when detached + --subnet-router Enable this client to act as a subnet router: traffic forwarded from the local network is NATed to this client's own tunnel IP before going out over the tunnel. Linux only, requires CAP_NET_ADMIN. (default false) --tls-client-cert path TLS client certificate path --tunnel-dns When enabled, DNS queries are routed through the tunnel for remote resolution. To ensure queries are tunneled correctly, you must define the DNS server as a Pangolin resource and enter its address as an Upstream DNS Server. --upstream-dns strings List of DNS servers to use for external DNS resolution if overriding system DNS diff --git a/docs/pangolin_up_site.md b/docs/pangolin_up_site.md new file mode 100644 index 0000000..a77a8d5 --- /dev/null +++ b/docs/pangolin_up_site.md @@ -0,0 +1,25 @@ +## pangolin up site + +Start a site connection (Newt) + +### Synopsis + +Bring up a site tunnel using Newt, embedded directly in the Pangolin CLI. + +This accepts the same flags and environment variables as the standalone +newt binary. Run 'pangolin up site --help' to see them. + +``` +pangolin up site [flags] +``` + +### Options + +``` + -h, --help help for site +``` + +### SEE ALSO + +* [pangolin up](pangolin_up.md) - Start a connection +