@raster-app/cli 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +14 -26
  2. package/dist/index.js +666 -10170
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -8,7 +8,9 @@ Command-line client for the [Raster](https://raster.app) API. Browse, search, up
8
8
  npm install -g @raster-app/cli
9
9
  ```
10
10
 
11
- Run a single command without installing — the binary is `raster`:
11
+ Installing the CLI pulls zero dependencies.
12
+
13
+ To run a single command without installing, call the `raster` binary through `npx`:
12
14
 
13
15
  ```sh
14
16
  npx -p @raster-app/cli raster whoami
@@ -16,13 +18,13 @@ npx -p @raster-app/cli raster whoami
16
18
 
17
19
  ## Authenticate
18
20
 
19
- **OAuth is the default** — an interactive login tied to your user account. For CI and automation, use an organization API key instead.
21
+ OAuth is the default: an interactive login tied to your user account. For CI and automation, use an organization API key instead.
20
22
 
21
23
  ```sh
22
24
  raster auth login
23
25
  ```
24
26
 
25
- `raster auth login` signs you in over OAuth (no API key needed). When a browser is available, 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.
27
+ `raster auth login` signs you in over OAuth (no API key needed). When a browser is available, it opens a browser authorization-code flow with a local loopback redirect. Over SSH or on a headless machine, it uses the device authorization grant instead: it prints a short code and a URL you approve in a browser on any device. Pass `--browser` or `--device` to force either.
26
28
 
27
29
  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.
28
30
 
@@ -36,14 +38,14 @@ Or set `RASTER_API_KEY`. The bearer credential resolves from the `--api-key` fla
36
38
 
37
39
  ## Org and library are derived from the key
38
40
 
39
- 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:
41
+ 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 without an extra request:
40
42
 
41
- - **`--org` is optional** — the organization comes from the key.
42
- - **`--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.
43
+ - `--org` is optional. The organization comes from the key.
44
+ - `--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.
43
45
 
44
46
  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`.
45
47
 
46
- 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.
48
+ A broad OAuth login is scoped to your user and reaches 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 an error. An OAuth login narrowed to a single organization resolves that org automatically.
47
49
 
48
50
  ## Global flags
49
51
 
@@ -90,14 +92,14 @@ Show the organizations, plan, and libraries the current credential can access. A
90
92
  | Command | Description | Example |
91
93
  | --- | --- | --- |
92
94
  | `raster assets ls` | List assets; filter with `--tag` (up to 5), page with `--page`/`--page-size`. | `raster assets ls --library brand --tag sunset` |
93
- | `raster assets get <assetId>` | Show one asset's metadata — including its variants, and duration plus stream details for video. | `raster assets get asset_123` |
95
+ | `raster assets get <assetId>` | Show one asset's metadata, including its variants, and duration plus stream details for video. | `raster assets get asset_123` |
94
96
  | `raster assets search <query>` | Search across the organization (`--library` scopes to one). | `raster assets search "golden hour"` |
95
97
  | `raster assets download <assetId>` | Download the file (`-o` path, `--force` to overwrite). | `raster assets download asset_123 -o photo.png` |
96
98
  | `raster assets upload <files...>` | Upload local files (batched at 20 per request). Pass `--parent <assetId>` to attach a single image as a variant of an existing asset. | `raster assets upload ./photos/*.png` |
97
99
  | `raster assets rm <assetIds...>` | Move assets to trash (`--yes` skips the prompt). | `raster assets rm asset_123 asset_456` |
98
100
  | `raster assets describe <assetId> --text <text>` | Set an asset's description. | `raster assets describe asset_123 --text "Hero shot"` |
99
101
  | `raster assets transfer <assetIds...> --to <libraryId>` | Move assets to another library. | `raster assets transfer asset_123 --to archive` |
100
- | `raster assets promote <assetId> --variant <variantId>` | Make a variant the asset's default — the pixels change at the same URL, and the old default is kept as a variant. | `raster assets promote asset_123 --variant asset_456` |
102
+ | `raster assets promote <assetId> --variant <variantId>` | Make a variant the asset's default. The pixels change at the same URL, and the old default is kept as a variant. | `raster assets promote asset_123 --variant asset_456` |
101
103
 
102
104
  ### `tags`
103
105
 
@@ -113,11 +115,11 @@ Show the organizations, plan, and libraries the current credential can access. A
113
115
  raster orgs create --email <email> [--name <name>] [--save]
114
116
  ```
115
117
 
116
- 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.
118
+ Create an organization and library with no account (held 30 days until claimed). Prints the claim URL; `--save` stores the new key. The command is anonymous and sends no API key.
117
119
 
118
120
  ## Output and scripting
119
121
 
120
- 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'`.
122
+ Human-readable tables print to stdout; progress and notes go to stderr, so stdout stays pipeable. Add `--json` for machine-readable output, for example `raster assets search "sunset" --json | jq '.hits[].id'`.
121
123
 
122
124
  ## Exit codes
123
125
 
@@ -126,7 +128,7 @@ Human-readable tables print to stdout; progress and notes go to stderr, so stdou
126
128
  | 0 | Success |
127
129
  | 1 | Unexpected error |
128
130
  | 2 | Usage error (bad flags or arguments) |
129
- | 3 | Authentication (missing or rejected key) |
131
+ | 3 | Authentication or permission (no usable credential, or a 401 or 403 response) |
130
132
  | 4 | Not found |
131
133
  | 5 | Validation or conflict |
132
134
  | 6 | File too large |
@@ -139,20 +141,6 @@ Human-readable tables print to stdout; progress and notes go to stderr, so stdou
139
141
  | `RASTER_API_KEY` | API key (overrides a stored OAuth token; sits below `--api-key`, above a config-file key) |
140
142
  | `RASTER_ORG` | Default organization id for an OAuth login when `--org` is omitted |
141
143
  | `RASTER_CONFIG_HOME` | Config directory override (default `~/.config/raster`) |
142
- | `RASTER_AUTH_ISSUER` | OAuth authorization-server issuer (default `https://raster.app`; a `raster.app` host or localhost only) |
143
- | `RASTER_OAUTH_CLIENT_ID` | Pin a client id to skip dynamic client registration |
144
-
145
- ## Development
146
-
147
- ```sh
148
- bun install
149
- bun test
150
- bun run check:types
151
- bun run gen:types # regenerate src/api/openapi.d.ts from the live OpenAPI document
152
- bun run build # bundle dist/index.js
153
- ```
154
-
155
- 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.
156
144
 
157
145
  ## License
158
146