@photon-ai/cli 0.2.1 → 0.4.0

package/README.md

@@ -3,60 +3,86 @@
 Typed terminal UI for the [Photon Dashboard](https://photon.codes). Replaces the web UI for everyday work — manage projects, Spectrum users / lines / platforms, billing, and your developer profile from a terminal.
 
 ```sh
-npx @photon-ai/cli login        # try it without installing
-bun add -g @photon-ai/cli       # or install for daily use
+npx @photon-ai/cli login          # try it without installing
+npm install -g @photon-ai/cli     # or install for daily use
 ```
 
+Runs on Node.js >= 18. Bun is also supported but not required.
+
 ---
 
 ## Install
 
-Four options. Pick whichever fits.
+### One-off — no install
+
+```sh
+npx @photon-ai/cli login
+npx @photon-ai/cli projects ls
+```
+
+Each invocation pulls the latest release on demand. Good for scripts, throwaway machines, or trying the CLI before committing. Works with `npx`, `pnpx`, or `bunx`.
 
-### 1. Homebrew (macOS / Linux)
+### Global install
 
 ```sh
-brew install photon-hq/photon/photon
+npm install -g @photon-ai/cli
 photon login
 ```
 
-Auto-updates with `brew upgrade photon`. No runtime dependencies — the formula installs a self-contained binary.
+After install, both `photon` and the shorter `pho` alias are on your `PATH`.
 
-### 2. One-off — no install (`npx` / `bunx`)
+Also works with other package managers:
 
 ```sh
-npx  @photon-ai/cli login
-bunx @photon-ai/cli projects ls
+pnpm add -g @photon-ai/cli
+yarn global add @photon-ai/cli
+bun add -g @photon-ai/cli
 ```
 
-Each invocation pulls the latest release on demand. Good for scripts, throwaway machines, or trying the CLI before committing. Requires Bun on `PATH` (the bundle has a `#!/usr/bin/env bun` shebang) — install it once with:
+### Standalone binary
+
+For CI environments or systems where you don't want any runtime. Replace `<os>` and `<arch>` with your platform:
 
 ```sh
-curl -fsSL https://bun.sh/install | bash
+# <os>: darwin | linux    <arch>: arm64 | x64
+curl -L -o /usr/local/bin/photon \
+  https://github.com/photon-hq/cli/releases/latest/download/photon-<os>-<arch>
+chmod +x /usr/local/bin/photon
+photon --version
 ```
 
-### 3. Global install — daily use (`bun add -g`)
+Available for macOS (arm64 / x64) and Linux (x64 / arm64). Each binary ships with a corresponding `.sha256` checksum on the same release page.
+
+---
+
+## Update
+
+The CLI shows a notification when a new version is available. To update:
 
 ```sh
-bun add -g @photon-ai/cli
-photon login
+npm update -g @photon-ai/cli
+photon --version
 ```
 
-After install, `photon` is on your `PATH`. The `pho` alias (see below) is created automatically the first time you run `photon`.
+Or with other package managers:
 
-### 4. Standalone binary — no Bun, no Node
+```sh
+pnpm update -g @photon-ai/cli
+yarn global upgrade @photon-ai/cli
+bun update -g @photon-ai/cli
+```
 
-For CI environments or systems where you don't want any runtime:
+If you're using a standalone binary, re-download the latest release:
 
 ```sh
-# pick your platform from https://github.com/photon-hq/cli/releases/latest
 curl -L -o /usr/local/bin/photon \
-  https://github.com/photon-hq/cli/releases/latest/download/photon-darwin-arm64
+  https://github.com/photon-hq/cli/releases/latest/download/photon-<os>-<arch>
 chmod +x /usr/local/bin/photon
-photon --version
 ```
 
-Available for macOS (arm64 / x64) and Linux (x64 / arm64). Each binary ships with a corresponding `.sha256` checksum on the same release page.
+`npx` / `pnpx` / `bunx` users always get the latest release automatically — no manual update needed.
+
+To suppress the update notification, set `PHOTON_NO_UPDATE_NOTIFIER=1`.
 
 ---
 
@@ -78,14 +104,14 @@ photon billing show
 
 ### The `pho` alias
 
-`pho` is a shortcut for `photon`, useful for high-frequency commands. It's created automatically as a sibling symlink the first time you run `photon` after installing — so no setup needed for global installs:
+`pho` is a shortcut for `photon`, useful for high-frequency commands. Every global install (npm / pnpm / yarn / bun) wires up both `photon` and `pho` automatically — they're declared as sibling `bin` entries that point at the same binary, so no setup is needed:
 
 ```sh
 pho ls          # photon projects ls
 pho whoami
 ```
 
-(`npx` / `bunx` users don't get `pho` since they're already typing the full package name; the alias is only created when running through an installed `photon` binary.)
+For `npx` / `bunx`, the package name itself is what you type, so `npx @photon-ai/cli` runs `photon` (the first declared bin). To run `pho` explicitly through `npx`, use `npx --package=@photon-ai/cli pho`.
 
 ---
 
@@ -180,6 +206,7 @@ photon
 │   ├── delete [id] [-y]                                permanent delete
 │   ├── regenerate-secret [id] [-y]                     rotate Spectrum secret
 │   ├── open [id]                                       open dashboard in browser
+│   ├── upgrade [id] [tier]                             subscribe / open Stripe portal
 │   └── check-phone <number>                            availability check
 ├── profile show / init / update                        developer / org profile
 ├── spectrum
@@ -191,7 +218,7 @@ photon
 └── billing
     ├── plans                                           available plans
     ├── show                                            current subscription
-    ├── checkout --plan <price-id>                      Stripe Checkout (browser)
+    ├── checkout [tier] [--plan <price-id>]             Stripe Checkout (browser)
     └── manage                                          Stripe Customer Portal
 ```