pockethost 4.0.0 → 4.2.0

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 Formerly published as `phio`. Versions below 3.0.0 are phio's history.
 
+## 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
+
+- New file commands that work over HTTPS with your token, replacing SFTP:
+  - `pockethost files [path] [-r]` lists files on the instance.
+  - `pockethost pull [paths...]` downloads files into the current folder (everything except `pb_data` by default;
+    `--data` includes it, and `node_modules` is skipped unless you name it). Files that haven't changed since the last
+    pull are skipped.
+  - `pockethost upload <local> [remote]` uploads a file or folder, for example an existing `pb_data` or your
+    `node_modules` (deploys never touch `node_modules`). Large files go up in 32 MB chunks, eight files at a time.
+  - `pockethost rm <paths...> [-r]` deletes files, for example a migration that keeps the instance from starting.
+  - Add `-I <instance>` to target an instance other than the linked one. `pb_data` needs the instance powered off.
+- `pockethost sftp`, `deploy --sftp` and `dev --sftp` print a notice: SFTP shuts down on February 6, 2027.
+
 ## 4.0.0
 
 ### Major Changes

package/LICENSE.md

@@ -0,0 +1,16 @@
+The MIT License (MIT)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+and associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

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+):
 
@@ -31,24 +31,64 @@ pockethost list          # alias: pockethost ls
 pockethost link [instance]
 pockethost dev [instance]
 pockethost deploy [instance]
-pockethost sftp [instance]
+pockethost files [path]
+pockethost pull [paths...]
+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
 - **`pockethost deploy`**: deploy once
 - **`pockethost login`**: open Account → API Tokens and save the token you paste
 - **`pockethost token`**: save, clear, or check the token
-- **`pockethost sftp`**: interactive SFTP session (uses system `sftp` when available)
+- **`pockethost files`**: list files on the instance (`-r` for everything below a folder)
+- **`pockethost pull`**: download instance files into this folder (`--data` includes `pb_data`)
+- **`pockethost upload`**: upload a file or folder, such as an existing `pb_data`
+- **`pockethost rm`**: delete files on the 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:
@@ -77,11 +117,14 @@ 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 `package.json` has `dependencies`, 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. `--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
 
@@ -90,9 +133,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:
 
@@ -109,7 +152,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.