pockethost 4.1.0 → 4.2.1

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 Formerly published as `phio`. Versions below 3.0.0 are phio's history.
 
+## 4.2.1
+
+### Patch Changes
+
+- Removing a package (even the last one) now removes it from the instance. With a `package.json`, `deploy` and `dev`
+  tell PocketHost that the deploy owns `node_modules`, so whatever isn't shipped is cleaned up.
+  `--no-node-modules` still leaves the instance's `node_modules` alone.
+
+## 4.2.0
+
+### Minor Changes
+
+- Manage instances from the CLI, with the same token you deploy with: `show`, `power on|off`, `rename`, `version`,
+  `versions`, `domain set|clear`, `dev-mode`, `admin-sync`, `auto-vacuum`, `secrets list|set|unset`,
+  `webhooks list|add|rm`, `create` and `delete`. Settings that need the instance off take `--cycle` to power it off,
+  apply the change and power it back on. The token needs write access, and `create` needs a token for all instances.
+- `deploy` and `dev` ship your production `node_modules` when `package.json` has `dependencies`: the packages in
+  `dependencies` and what they need, never `devDependencies`. Works with npm, pnpm, Bun and workspaces, and follows
+  symlinks so the instance gets plain files. `--no-node-modules` turns it off.
+- `deploy --dry-run` lists what would be deployed, and `deploy --out <dir>` writes it to a local folder.
+- Links to API tokens and SSH keys point at `pockethost.io/account/…` (the old `app.pockethost.io` links landed on the
+  home page).
+
 ## 4.1.0
 
 ### Minor Changes

package/README.md

@@ -1,6 +1,6 @@
 # pockethost: the PocketHost CLI
 
-Deploy, sync, and tail logs for your [PocketHost](https://pockethost.io) instances.
+Deploy, sync, tail logs and manage your [PocketHost](https://pockethost.io) instances.
 
 Install globally (Node.js 20+):
 
@@ -37,6 +37,22 @@ pockethost upload <local> [remote]
 pockethost rm <paths...>
 pockethost sftp [instance]   # shuts down Feb 6, 2027
 pockethost logs [instance]
+
+# Instances (same as the dashboard)
+pockethost show [instance]
+pockethost power on|off [instance]
+pockethost rename <new-name> [instance]
+pockethost version <version> [instance]
+pockethost versions
+pockethost domain set <host> [instance]
+pockethost domain clear [instance]
+pockethost dev-mode on|off [instance]
+pockethost admin-sync on|off [instance]
+pockethost auto-vacuum on|off [instance]
+pockethost secrets list|set|unset
+pockethost webhooks list|add|rm
+pockethost create [name]
+pockethost delete <instance>
 ```
 
 - **`pockethost dev`**: watch local changes and deploy them
@@ -50,13 +66,29 @@ pockethost logs [instance]
 - **`pockethost sftp`**: interactive SFTP session. SFTP shuts down on February 6, 2027
 - **`pockethost logs`**: tail instance logs
 
-`dev` and `deploy` accept `-v/--verbose`, `-i/--include`, `-e/--exclude`, and `--sftp` (sync over SFTP instead of
-HTTPS). `deploy` also takes `--commit <sha>` and `-m/--message <note>`.
+`dev` and `deploy` accept `-v/--verbose`, `-i/--include`, `-e/--exclude`, `--no-node-modules`, and `--sftp` (sync
+over SFTP instead of HTTPS). `deploy` also takes `--commit <sha>`, `-m/--message <note>`, `--dry-run` (list what would
+be deployed) and `--out <dir>` (write the deploy set to a local folder instead of deploying).
 
 Default includes: `pb_*`, `package.json`, `bun.lock`, `bun.lockb`, `patches/**`.
 
 Default excludes: `pb_data/**`.
 
+## Managing instances
+
+Everything the dashboard does to an instance has a command. They use the linked instance unless you name one
+(`secrets` and `webhooks` take `-I <instance>`).
+
+- **`show`**: power, URLs, domain, version, settings, secret names and webhooks (`--json` for scripts)
+- **`power on|off`**: `off --wait` waits until the instance has stopped
+- **`rename`**, **`version`**, **`domain set|clear`**, **`dev-mode`**, **`admin-sync`**, **`auto-vacuum`**: these need
+  the instance powered off. Add `--cycle` to power it off, apply the change and power it back on in one step
+- **`secrets set KEY=value…`**: changes only the secrets you name. Give just `KEY` to type the value at a prompt so it
+  stays out of your shell history. `secrets list` shows names only, never values
+- **`webhooks add <endpoint> "<cron>"`**, **`webhooks rm <endpoint>`**, **`webhooks list`**
+- **`create [name]`**: a random available name if you don't give one. `--link` links this folder to it
+- **`delete <instance>`**: the instance must be powered off. Asks you to type its name unless you pass `--yes`
+
 ## Configuration
 
 Link a project directory to an instance:
@@ -85,11 +117,15 @@ Older project files (`.phioconfig`, `package.json` → `pockethost.instanceName`
 3. Commit: the server swaps the file set in atomically (stopping the instance when anything outside `pb_public`
    changes) and starts the instance again.
 
-PocketHost doesn't install npm packages. `package.json`, `bun.lock(b)` and `patches/` are copied as plain files. Bundle
-any npm code your hooks need into `pb_hooks`.
+PocketHost doesn't run `npm install`. Instead, when your project has a `package.json`, the CLI ships your production
+`node_modules` with the deploy: the packages in `dependencies` and everything they need, never `devDependencies`.
+It works with npm, pnpm, Bun and workspaces, and follows symlinks, so the instance gets plain files. Install first
+(`npm install` or similar), then deploy. The instance's `node_modules` ends up matching what you shipped, so packages
+you remove (even the last one) are removed there too. `--no-node-modules` leaves the instance's `node_modules` alone.
 
-Only `pb_*` folders (never `pb_data`), `package.json`, `bun.lock(b)` and `patches/` are deployed. Files in those folders
-on the instance that aren't in your project are removed. `node_modules` and `.git*` are never touched.
+Only `pb_*` folders (never `pb_data`), `package.json`, `bun.lock(b)`, `patches/` and the production `node_modules` are
+deployed. Files in those folders on the instance that aren't in your project are removed. `.git*` files are never
+touched.
 
 ## Authentication
 
@@ -98,9 +134,9 @@ The CLI signs in with a personal access token (`ph_pat_…`) only. Every command
 1. `POCKETHOST_TOKEN`
 2. the token saved by `pockethost login` (or `pockethost token set`)
 
-Create tokens under [Account → API Tokens](https://app.pockethost.io/account/tokens). A token sees only the instances
-you give it; `list`, `link` and `logs` need read access, `deploy` and `dev` need write access. Email/password login
-was removed in 4.0.
+Create tokens under [Account → API Tokens](https://pockethost.io/account/tokens). A token sees only the instances
+you give it. `list`, `link`, `show` and `logs` work with any token. `deploy`, `dev` and the instance commands need
+write access, and `create` needs a token for all instances. Email/password login was removed in 4.0.
 
 Deploy from GitHub Actions:
 
@@ -117,7 +153,7 @@ Docs: https://pockethost.io/docs/deploy-from-ci
 `pockethost dev --sftp`, `pockethost deploy --sftp` and `pockethost sftp` use **SFTP** (`ftp.pockethost.io:2222`)
 with an Ed25519 key stored under `POCKETHOST_HOME` (default `~/.config/pockethost/`), created on first use. Tokens
 can't add SSH keys, so add the public key (`pockethost_deploy_ed25519.pub`) under
-[Account → Keys](https://app.pockethost.io/account/keys) once; the CLI prints it if it's missing. Keys you registered
+[Account → Keys](https://pockethost.io/account/keys) once; the CLI prints it if it's missing. Keys you registered
 with an earlier version (`PocketHost CLI` or `Phio`) keep working. `pockethost info` shows whether the key is on your
 account.
 
@@ -125,13 +161,13 @@ Customer docs: https://pockethost.io/docs/cli
 
 ## Environment variables
 
-| Variable | Purpose |
-| -------- | ------- |
-| `POCKETHOST_TOKEN` | Personal access token (CI); overrides the saved one |
-| `POCKETHOST_INSTANCE_NAME` | Override linked instance name |
-| `POCKETHOST_MOTHERSHIP_URL` | Override mothership API URL |
-| `POCKETHOST_HOME` | Override config directory |
-| `POCKETHOST_PROJECT_DIR` | Override project root detection |
+| Variable                    | Purpose                                             |
+| --------------------------- | --------------------------------------------------- |
+| `POCKETHOST_TOKEN`          | Personal access token (CI); overrides the saved one |
+| `POCKETHOST_INSTANCE_NAME`  | Override linked instance name                       |
+| `POCKETHOST_MOTHERSHIP_URL` | Override mothership API URL                         |
+| `POCKETHOST_HOME`           | Override config directory                           |
+| `POCKETHOST_PROJECT_DIR`    | Override project root detection                     |
 
 Environment variables take precedence over `.pockethostconfig`. The old `PHIO_*` names still work (with a deprecation
 warning) and will be removed in a future major version.