@raster-app/cli 0.2.0 → 0.3.0

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 +45 -46
  2. package/dist/index.js +866 -80
  3. package/package.json +2 -6
package/README.md CHANGED
@@ -14,19 +14,25 @@ Run a single command without installing — the binary is `raster`:
14
14
  npx -p @raster-app/cli raster whoami
15
15
  ```
16
16
 
17
- A standalone macOS (Apple Silicon) binary ships with each [GitHub release](https://github.com/raster-app/raster-cli/releases) — no Node required.
18
-
19
17
  ## Authenticate
20
18
 
21
- The CLI uses your organization's API key (create one in Raster under Settings → API Keys).
19
+ There are two ways to sign in: an interactive OAuth login tied to your user account, or an organization API key for CI.
22
20
 
23
21
  ```sh
24
22
  raster auth login
25
23
  ```
26
24
 
27
- The command validates the key against the API and stores it in `~/.config/raster/config.json` with owner-only permissions. In CI, set `RASTER_API_KEY` instead.
25
+ 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.
26
+
27
+ 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
+
29
+ For CI and scripts, use an organization API key instead (create one in Raster under Settings → API Keys):
30
+
31
+ ```sh
32
+ raster auth login --api-key pk_…
33
+ ```
28
34
 
29
- The key resolves from the `--api-key` flag, then `RASTER_API_KEY`, then the config file. `raster auth status` shows which source is active.
35
+ 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.
30
36
 
31
37
  ## Org and library are derived from the key
32
38
 
@@ -37,6 +43,8 @@ An API key is scoped to one organization and a set of libraries. `raster auth lo
37
43
 
38
44
  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`.
39
45
 
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.
47
+
40
48
  ## Global flags
41
49
 
42
50
  These work on every command, before or after the subcommand.
@@ -44,20 +52,22 @@ These work on every command, before or after the subcommand.
44
52
  | Flag | Purpose |
45
53
  | --- | --- |
46
54
  | `--api-key <key>` | API key (overrides `RASTER_API_KEY` and the config file) |
47
- | `--org <organizationId>` | Organization id (derived from the key when omitted) |
55
+ | `--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`) |
48
56
  | `--library <libraryId>` | Library id (derived from the key when it has one library) |
49
57
  | `--json` | Print the raw API payload to stdout and nothing else |
50
58
  | `--verbose` | Log each request to stderr (method, path, masked key, status, duration) |
51
59
 
52
60
  ## Commands
53
61
 
62
+ Asset ids are always positional. `--library` selects the library when the key can reach more than one. `raster <command> --help` lists every flag.
63
+
54
64
  ### `auth`
55
65
 
56
- | Command | Description |
57
- | --- | --- |
58
- | `raster auth login` | Validate an API key and store it. Pass `--api-key <key>`, or run interactively to be prompted. |
59
- | `raster auth logout` | Remove the stored API key. |
60
- | `raster auth status` | Show which key is in use, its source, and the organization it reaches. |
66
+ | Command | Description | Example |
67
+ | --- | --- | --- |
68
+ | `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` |
69
+ | `raster auth logout` | Revoke the OAuth token (if any) and remove stored credentials. | `raster auth logout` |
70
+ | `raster auth status` | Show which credential is in use, its source, and the organization it reaches. | `raster auth status` |
61
71
 
62
72
  ### `whoami`
63
73
 
@@ -65,38 +75,36 @@ These work on every command, before or after the subcommand.
65
75
  raster whoami
66
76
  ```
67
77
 
68
- Show the organization, plan, and libraries the API key can access.
78
+ 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`.
69
79
 
70
80
  ### `libraries`
71
81
 
72
- | Command | Description | Flags |
82
+ | Command | Description | Example |
73
83
  | --- | --- | --- |
74
- | `raster libraries ls` | List libraries in the organization. | `--page <n>`, `--page-size <n>` |
75
- | `raster libraries create` | Create a library. | `--name <name>` (required), `--slug <slug>` |
76
- | `raster libraries rename` | Rename the library (`--library`, or the key's only one). | `--name <name>` (required) |
84
+ | `raster libraries ls` | List libraries in the organization (`--page`, `--page-size`). | `raster libraries ls` |
85
+ | `raster libraries create --name <name>` | Create a library (`--slug` optional). | `raster libraries create --name "Brand"` |
86
+ | `raster libraries rename --name <name>` | Rename the library. | `raster libraries rename --name "Brand assets"` |
77
87
 
78
88
  ### `assets`
79
89
 
80
- Asset ids are always positional. `--library` selects the library when the key has more than one.
81
-
82
- | Command | Description | Flags |
90
+ | Command | Description | Example |
83
91
  | --- | --- | --- |
84
- | `raster assets ls` | List assets in the library. | `--page <n>`, `--page-size <n>`, `--tag <tag...>` (repeatable, up to 5) |
85
- | `raster assets get <assetId>` | Show one asset's metadata. | — |
86
- | `raster assets search <query>` | Search assets across the organization (`--library` scopes to one). | `--page <n>`, `--page-size <n>` |
87
- | `raster assets download <assetId>` | Download the asset's file to disk. | `-o, --output <path>`, `--force` |
88
- | `raster assets upload <files...>` | Upload local files (batched at 20 per request). | — |
89
- | `raster assets rm <assetIds...>` | Move assets to trash (recoverable). | `--yes` (skip the confirm prompt) |
90
- | `raster assets describe <assetId>` | Set an asset's description. | `--text <description>` (required) |
91
- | `raster assets transfer <assetIds...>` | Move assets to another library. | `--to <libraryId>` (required) |
92
+ | `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. | `raster assets get asset_123` |
94
+ | `raster assets search <query>` | Search across the organization (`--library` scopes to one). | `raster assets search "golden hour"` |
95
+ | `raster assets download <assetId>` | Download the file (`-o` path, `--force` to overwrite). | `raster assets download asset_123 -o photo.png` |
96
+ | `raster assets upload <files...>` | Upload local files (batched at 20 per request). | `raster assets upload ./photos/*.png` |
97
+ | `raster assets rm <assetIds...>` | Move assets to trash (`--yes` skips the prompt). | `raster assets rm asset_123 asset_456` |
98
+ | `raster assets describe <assetId> --text <text>` | Set an asset's description. | `raster assets describe asset_123 --text "Hero shot"` |
99
+ | `raster assets transfer <assetIds...> --to <libraryId>` | Move assets to another library. | `raster assets transfer asset_123 --to archive` |
92
100
 
93
101
  ### `tags`
94
102
 
95
- | Command | Description | Flags |
103
+ | Command | Description | Example |
96
104
  | --- | --- | --- |
97
- | `raster tags ls` | List tags in the library. | `--limit <n>` |
98
- | `raster tags add <assetIds...>` | Add tags to assets. | `--tag <tag...>` (required, repeatable) |
99
- | `raster tags rm <assetIds...>` | Remove tags from assets. | `--tag <tag...>` (required, repeatable) |
105
+ | `raster tags ls` | List tags in the library (`--limit`). | `raster tags ls --library brand` |
106
+ | `raster tags add <assetIds...> --tag <tag...>` | Add tags to assets. | `raster tags add asset_123 --tag launch` |
107
+ | `raster tags rm <assetIds...> --tag <tag...>` | Remove tags from assets. | `raster tags rm asset_123 --tag launch` |
100
108
 
101
109
  ### `orgs`
102
110
 
@@ -104,22 +112,11 @@ Asset ids are always positional. `--library` selects the library when the key ha
104
112
  raster orgs create --email <email> [--name <name>] [--save]
105
113
  ```
106
114
 
107
- Create a library with no account (held 30 days until claimed). Prints the claim URL; `--save` stores the minted key. Anonymous — sends no API key.
108
-
109
- ## Examples
110
-
111
- ```sh
112
- raster libraries ls
113
- raster assets ls --library brand --tag sunset
114
- raster assets upload --library brand ./photos/*.png
115
- raster assets search "golden hour" --json | jq '.hits[].id'
116
- raster tags add asset_123 asset_456 --tag launch --library brand
117
- raster assets transfer asset_123 --to archive --library brand
118
- ```
115
+ 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.
119
116
 
120
117
  ## Output and scripting
121
118
 
122
- Human-readable tables print to stdout; progress and notes go to stderr, so stdout stays pipeable. `--json` prints only the raw API payload to stdout. `--verbose` logs each request to stderr with the key masked.
119
+ 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'`.
123
120
 
124
121
  ## Exit codes
125
122
 
@@ -138,9 +135,11 @@ Human-readable tables print to stdout; progress and notes go to stderr, so stdou
138
135
 
139
136
  | Variable | Purpose |
140
137
  | --- | --- |
141
- | `RASTER_API_KEY` | API key (overrides the config file) |
142
- | `RASTER_API_BASE_URL` | API origin override — https only, except localhost |
138
+ | `RASTER_API_KEY` | API key (sits below a stored OAuth token, above a config-file key) |
139
+ | `RASTER_ORG` | Default organization id for an OAuth login when `--org` is omitted |
143
140
  | `RASTER_CONFIG_HOME` | Config directory override (default `~/.config/raster`) |
141
+ | `RASTER_AUTH_ISSUER` | OAuth authorization-server issuer (default `https://raster.app`; a `raster.app` host or localhost only) |
142
+ | `RASTER_OAUTH_CLIENT_ID` | Pin a client id to skip dynamic client registration |
144
143
 
145
144
  ## Development
146
145