@raster-app/cli 0.1.1 → 0.3.0

package/README.md

@@ -14,48 +14,109 @@ Run a single command without installing — the binary is `raster`:
 npx -p @raster-app/cli raster whoami
 ```
 
-A standalone macOS (Apple Silicon) binary ships with each [GitHub release](https://github.com/raster-app/raster-cli/releases) — no Node required.
-
 ## Authenticate
 
-The CLI uses your organization's API key (create one in Raster under Settings → API Keys).
+There are two ways to sign in: an interactive OAuth login tied to your user account, or an organization API key for CI.
 
 ```sh
 raster auth login
 ```
 
-Validates the key against the API and stores it in `~/.config/raster/config.json` (mode `0600`). In CI, set `RASTER_API_KEY` instead — no login needed.
+With no `--api-key`, `raster auth login` signs you in over OAuth. When a browser is available (an interactive session with a display) it opens a **browser authorization-code flow** with a local loopback redirect; otherwise — over SSH or on a headless machine — it falls back to the **device authorization grant**, printing a short code and a URL you approve in a browser on any device. Pass `--browser` or `--device` to force either.
+
+OAuth tokens (access + refresh) are stored in `~/.config/raster/config.json` with owner-only permissions. The CLI refreshes the access token automatically before it expires and rotates the refresh token; when the saved login can no longer be refreshed, it asks you to run `raster auth login` again.
+
+For CI and scripts, use an organization API key instead (create one in Raster under Settings → API Keys):
+
+```sh
+raster auth login --api-key pk_…
+```
+
+Or set `RASTER_API_KEY`. The bearer credential resolves from the `--api-key` flag, then a stored OAuth token, then `RASTER_API_KEY`, then a stored config API key. `raster auth status` shows which credential is active. `raster auth logout` revokes an OAuth token and removes stored credentials.
 
-Key resolution order: `--api-key` flag, then `RASTER_API_KEY`, then the config file. `raster auth status` shows which source is active.
+## Org and library are derived from the key
+
+An API key is scoped to one organization and a set of libraries. `raster auth login` captures that scope into the config file, so commands resolve it locally — no extra request per command:
+
+- **`--org` is optional** — the organization comes from the key.
+- **`--library` is optional when the key has a single library.** When the key can reach several, commands that act on one library ask you to pass `--library <id>` and list the choices.
+
+Pass `--org` / `--library` to override, or to pick a library when the key spans more than one. A key supplied via `RASTER_API_KEY` with no prior login resolves its scope from the API on first use. If a key's library access changes in Raster, re-run `raster auth login` to refresh the cached list, or pass `--library`.
+
+A **broad OAuth login is scoped to your user**, reaching every organization you belong to. Because no single org is implied, commands that act on one organization require you to choose it: pass `--org <id>`, set `RASTER_ORG`, or rely on a `defaultOrg` in config; run `raster whoami` to list the organizations you can reach. Without a selection the command stops with a clear error rather than guessing. An OAuth login narrowed to a single organization resolves that org automatically.
+
+## Global flags
+
+These work on every command, before or after the subcommand.
+
+| Flag | Purpose |
+| --- | --- |
+| `--api-key <key>` | API key (overrides `RASTER_API_KEY` and the config file) |
+| `--org <organizationId>` | Organization id (derived from an API key or an org-scoped OAuth login; for a broad OAuth login pass this, set `RASTER_ORG`, or a config `defaultOrg`) |
+| `--library <libraryId>` | Library id (derived from the key when it has one library) |
+| `--json` | Print the raw API payload to stdout and nothing else |
+| `--verbose` | Log each request to stderr (method, path, masked key, status, duration) |
 
 ## Commands
 
-```text
-raster auth login|logout|status
+Asset ids are always positional. `--library` selects the library when the key can reach more than one. `raster <command> --help` lists every flag.
+
+### `auth`
+
+| Command | Description | Example |
+| --- | --- | --- |
+| `raster auth login` | Sign in over OAuth (browser when available, otherwise a device code; force with `--device`/`--browser`), or validate an API key with `--api-key`. | `raster auth login` |
+| `raster auth logout` | Revoke the OAuth token (if any) and remove stored credentials. | `raster auth logout` |
+| `raster auth status` | Show which credential is in use, its source, and the organization it reaches. | `raster auth status` |
+
+### `whoami`
+
+```sh
 raster whoami
-raster libraries ls|create|rename
-raster assets ls|get|search|download|upload|rm|describe|transfer
-raster tags ls|add|rm
-raster orgs create
 ```
 
-Examples:
+Show the organizations, plan, and libraries the current credential can access. An OAuth login lists every organization you belong to, so you can pick one with `--org`.
+
+### `libraries`
+
+| Command | Description | Example |
+| --- | --- | --- |
+| `raster libraries ls` | List libraries in the organization (`--page`, `--page-size`). | `raster libraries ls` |
+| `raster libraries create --name <name>` | Create a library (`--slug` optional). | `raster libraries create --name "Brand"` |
+| `raster libraries rename --name <name>` | Rename the library. | `raster libraries rename --name "Brand assets"` |
+
+### `assets`
+
+| Command | Description | Example |
+| --- | --- | --- |
+| `raster assets ls` | List assets; filter with `--tag` (up to 5), page with `--page`/`--page-size`. | `raster assets ls --library brand --tag sunset` |
+| `raster assets get <assetId>` | Show one asset's metadata. | `raster assets get asset_123` |
+| `raster assets search <query>` | Search across the organization (`--library` scopes to one). | `raster assets search "golden hour"` |
+| `raster assets download <assetId>` | Download the file (`-o` path, `--force` to overwrite). | `raster assets download asset_123 -o photo.png` |
+| `raster assets upload <files...>` | Upload local files (batched at 20 per request). | `raster assets upload ./photos/*.png` |
+| `raster assets rm <assetIds...>` | Move assets to trash (`--yes` skips the prompt). | `raster assets rm asset_123 asset_456` |
+| `raster assets describe <assetId> --text <text>` | Set an asset's description. | `raster assets describe asset_123 --text "Hero shot"` |
+| `raster assets transfer <assetIds...> --to <libraryId>` | Move assets to another library. | `raster assets transfer asset_123 --to archive` |
+
+### `tags`
+
+| Command | Description | Example |
+| --- | --- | --- |
+| `raster tags ls` | List tags in the library (`--limit`). | `raster tags ls --library brand` |
+| `raster tags add <assetIds...> --tag <tag...>` | Add tags to assets. | `raster tags add asset_123 --tag launch` |
+| `raster tags rm <assetIds...> --tag <tag...>` | Remove tags from assets. | `raster tags rm asset_123 --tag launch` |
+
+### `orgs`
 
 ```sh
-raster libraries ls --org org_123
-raster assets ls --org org_123 --library lib_456 --tag sunset
-raster assets upload --org org_123 --library lib_456 ./photos/*.png
-raster assets search --org org_123 "golden hour" --json | jq '.hits[].id'
-raster orgs create --email you@example.com --save
+raster orgs create --email <email> [--name <name>] [--save]
 ```
 
-`raster <command> --help` documents every flag.
+Create an organization and library with no account (held 30 days until claimed). Prints the claim URL; `--save` stores the minted key. Anonymous — sends no API key.
 
-## Output
+## Output and scripting
 
-- Human-readable tables on stdout; progress and notes on stderr, so stdout stays pipeable.
-- `--json` prints the raw API payload to stdout and nothing else.
-- `--verbose` logs each request (method, path, masked key, status, duration) to stderr.
+Human-readable tables print to stdout; progress and notes go to stderr, so stdout stays pipeable. Add `--json` for machine-readable output — e.g. `raster assets search "sunset" --json | jq '.hits[].id'`.
 
 ## Exit codes
 
@@ -74,9 +135,11 @@ raster orgs create --email you@example.com --save
 
 | Variable | Purpose |
 | --- | --- |
-| `RASTER_API_KEY` | API key (overrides the config file) |
-| `RASTER_API_BASE_URL` | API origin override — https only, except localhost |
+| `RASTER_API_KEY` | API key (sits below a stored OAuth token, above a config-file key) |
+| `RASTER_ORG` | Default organization id for an OAuth login when `--org` is omitted |
 | `RASTER_CONFIG_HOME` | Config directory override (default `~/.config/raster`) |
+| `RASTER_AUTH_ISSUER` | OAuth authorization-server issuer (default `https://raster.app`; a `raster.app` host or localhost only) |
+| `RASTER_OAUTH_CLIENT_ID` | Pin a client id to skip dynamic client registration |
 
 ## Development
 
@@ -88,7 +151,7 @@ bun run gen:types   # regenerate src/api/openapi.d.ts from the live OpenAPI docu
 bun run build       # bundle dist/index.js
 ```
 
-Types are generated from the public OpenAPI document at `https://api.raster.app/openapi.json`; CI fails when the committed types drift from production. The published package bundles its three libraries (`commander`, `zod`, `openapi-fetch`) into `dist/index.js` — installing the CLI pulls zero dependencies. Releases run `scripts/check-tarball.ts`, which fails if the tarball contains anything beyond `dist/`, `package.json`, `README.md`, and `LICENSE`.
+Types are generated from the public OpenAPI document at `https://api.raster.app/openapi.json`; CI fails when the committed types drift from production. The published package bundles its three libraries (`commander`, `zod`, `openapi-fetch`) into `dist/index.js` — installing the CLI pulls zero dependencies.
 
 ## License