@raster-app/cli 0.1.0 → 0.2.0

package/README.md

@@ -8,10 +8,10 @@ Command-line client for the [Raster](https://raster.app) API. Browse, search, up
 npm install -g @raster-app/cli
 ```
 
-Run ad hoc without installing:
+Run a single command without installing — the binary is `raster`:
 
 ```sh
-npx @raster-app/cli whoami
+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.
@@ -24,38 +24,102 @@ The CLI uses your organization's API key (create one in Raster under Settings
 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.
+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.
 
-Key resolution order: `--api-key` flag, then `RASTER_API_KEY`, then the config file. `raster auth status` shows which source is active.
+The key resolves from the `--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`.
+
+## 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 the key when omitted) |
+| `--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
+### `auth`
+
+| Command | Description |
+| --- | --- |
+| `raster auth login` | Validate an API key and store it. Pass `--api-key <key>`, or run interactively to be prompted. |
+| `raster auth logout` | Remove the stored API key. |
+| `raster auth status` | Show which key is in use, its source, and the organization it reaches. |
+
+### `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 organization, plan, and libraries the API key can access.
+
+### `libraries`
+
+| Command | Description | Flags |
+| --- | --- | --- |
+| `raster libraries ls` | List libraries in the organization. | `--page <n>`, `--page-size <n>` |
+| `raster libraries create` | Create a library. | `--name <name>` (required), `--slug <slug>` |
+| `raster libraries rename` | Rename the library (`--library`, or the key's only one). | `--name <name>` (required) |
+
+### `assets`
+
+Asset ids are always positional. `--library` selects the library when the key has more than one.
+
+| Command | Description | Flags |
+| --- | --- | --- |
+| `raster assets ls` | List assets in the library. | `--page <n>`, `--page-size <n>`, `--tag <tag...>` (repeatable, up to 5) |
+| `raster assets get <assetId>` | Show one asset's metadata. | — |
+| `raster assets search <query>` | Search assets across the organization (`--library` scopes to one). | `--page <n>`, `--page-size <n>` |
+| `raster assets download <assetId>` | Download the asset's file to disk. | `-o, --output <path>`, `--force` |
+| `raster assets upload <files...>` | Upload local files (batched at 20 per request). | — |
+| `raster assets rm <assetIds...>` | Move assets to trash (recoverable). | `--yes` (skip the confirm prompt) |
+| `raster assets describe <assetId>` | Set an asset's description. | `--text <description>` (required) |
+| `raster assets transfer <assetIds...>` | Move assets to another library. | `--to <libraryId>` (required) |
+
+### `tags`
+
+| Command | Description | Flags |
+| --- | --- | --- |
+| `raster tags ls` | List tags in the library. | `--limit <n>` |
+| `raster tags add <assetIds...>` | Add tags to assets. | `--tag <tag...>` (required, repeatable) |
+| `raster tags rm <assetIds...>` | Remove tags from assets. | `--tag <tag...>` (required, repeatable) |
+
+### `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 a library with no account (held 30 days until claimed). Prints the claim URL; `--save` stores the minted key. Anonymous — sends no API key.
+
+## Examples
+
+```sh
+raster libraries ls
+raster assets ls --library brand --tag sunset
+raster assets upload --library brand ./photos/*.png
+raster assets search "golden hour" --json | jq '.hits[].id'
+raster tags add asset_123 asset_456 --tag launch --library brand
+raster assets transfer asset_123 --to archive --library brand
+```
 
-## 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. `--json` prints only the raw API payload to stdout. `--verbose` logs each request to stderr with the key masked.
 
 ## Exit codes
 
@@ -88,7 +152,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
 

package/dist/index.js

@@ -16337,7 +16337,7 @@ config(en_default());
 // package.json
 var package_default = {
   name: "@raster-app/cli",
-  version: "0.1.0",
+  version: "0.2.0",
   description: "Command-line client for the Raster API",
   license: "Apache-2.0",
   type: "module",
@@ -17032,7 +17032,9 @@ var CONFIG_FILE_NAME = "config.json";
 var CONFIG_FILE_MODE = 384;
 var CONFIG_DIR_MODE = 448;
 var configSchema = exports_external.object({
-  apiKey: exports_external.string().min(1).optional()
+  apiKey: exports_external.string().min(1).optional(),
+  organizationId: exports_external.string().min(1).optional(),
+  libraries: exports_external.array(exports_external.string()).optional()
 });
 function configDir(env) {
   if (env.RASTER_CONFIG_HOME)
@@ -17204,6 +17206,22 @@ async function createCommandContext(globals, overrides = {}) {
   const baseUrl = validateBaseUrl(env.RASTER_API_BASE_URL ?? DEFAULT_BASE_URL);
   const baseFetch = overrides.fetch ?? globalThis.fetch;
   const instrumentedFetch = instrumentFetch(baseFetch, output, apiKey ? maskApiKey(apiKey.key) : null);
+  const clientFactory = (clientOverrides) => createApiClient({
+    baseUrl,
+    apiKey: clientOverrides ? clientOverrides.apiKey : apiKey?.key ?? null,
+    fetch: instrumentedFetch
+  });
+  let viewerPromise = null;
+  const loadViewer = () => {
+    if (!viewerPromise) {
+      if (!apiKey) {
+        throw new AuthSetupError("No API key found. Run `raster auth login` or set RASTER_API_KEY.");
+      }
+      viewerPromise = unwrapResult(() => clientFactory({ apiKey: apiKey.key }).GET("/me", { params: { header: VERSION_HEADER } }));
+    }
+    return viewerPromise;
+  };
+  const cacheMatchesKey = config2.apiKey !== undefined && apiKey?.key === config2.apiKey;
   return {
     ...output,
     env,
@@ -17211,13 +17229,35 @@ async function createCommandContext(globals, overrides = {}) {
     isInteractive: overrides.isInteractive ?? process.stdin.isTTY === true,
     apiKey,
     fetch: instrumentedFetch,
-    clientFactory: (clientOverrides) => createApiClient({
-      baseUrl,
-      apiKey: clientOverrides ? clientOverrides.apiKey : apiKey?.key ?? null,
-      fetch: instrumentedFetch
-    }),
+    clientFactory,
     confirm: overrides.confirm ?? promptConfirm,
-    promptSecret: overrides.promptSecret ?? promptSecret
+    promptSecret: overrides.promptSecret ?? promptSecret,
+    explicitLibrary: globals.library,
+    resolveOrg: async () => {
+      if (globals.org)
+        return globals.org;
+      if (cacheMatchesKey && config2.organizationId)
+        return config2.organizationId;
+      const viewer = await loadViewer();
+      if (!viewer.organizationId) {
+        throw new CliError("Could not determine the organization from the API key.", EXIT_CODES.generic);
+      }
+      return viewer.organizationId;
+    },
+    resolveLibrary: async () => {
+      if (globals.library)
+        return globals.library;
+      const cachedLibraries = cacheMatchesKey ? config2.libraries : undefined;
+      const source = cachedLibraries ?? (await loadViewer()).libraries ?? [];
+      const libraries = source.filter((value) => typeof value === "string");
+      const onlyLibrary = libraries[0];
+      if (libraries.length === 1 && onlyLibrary)
+        return onlyLibrary;
+      if (libraries.length === 0) {
+        throw new AuthSetupError("The API key has no library access.");
+      }
+      throw new UsageError(`The API key can access ${libraries.length} libraries (${libraries.join(", ")}). Pass --library <id>.`);
+    }
   };
 }
 function instrumentFetch(baseFetch, output, maskedKey) {
@@ -17284,11 +17324,7 @@ var SEARCH_HIT_COLUMNS = [
   { header: "NAME", value: (hit) => hit.name ?? "" },
   { header: "LIBRARY", value: (hit) => hit.libraryId ?? "" }
 ];
-var inLibraryOptionsSchema = exports_external.object({
-  org: exports_external.string().min(1),
-  library: exports_external.string().min(1)
-});
-var listOptionsSchema = inLibraryOptionsSchema.extend({
+var listOptionsSchema = exports_external.object({
   page: exports_external.coerce.number().int().min(1).optional(),
   pageSize: exports_external.coerce.number().int().min(1).optional(),
   tag: exports_external.array(exports_external.string().min(1)).default([])
@@ -17298,10 +17334,12 @@ async function listAssetsCommand(context, options) {
     throw new ValidationError(`At most ${MAX_TAGS_PER_QUERY} --tag filters are supported per query.`);
   }
   requireApiKey(context);
+  const organizationId = await context.resolveOrg();
+  const libraryId = await context.resolveLibrary();
   const client = context.clientFactory();
   const assets = await unwrapResult(() => client.GET("/organizations/{organizationId}/libraries/{libraryId}/assets", {
     params: {
-      path: { organizationId: options.org, libraryId: options.library },
+      path: { organizationId, libraryId },
       header: VERSION_HEADER,
       query: {
         page: options.page,
@@ -17316,10 +17354,9 @@ async function listAssetsCommand(context, options) {
   }
   renderTable(context, assets, ASSET_COLUMNS);
 }
-var getOptionsSchema = inLibraryOptionsSchema;
-async function getAssetCommand(context, assetId, options) {
+async function getAssetCommand(context, assetId) {
   requireApiKey(context);
-  const asset = await fetchAsset(context, options.org, options.library, assetId);
+  const asset = await fetchAsset(context, assetId);
   if (context.json) {
     printJson(context, asset);
     return;
@@ -17335,28 +17372,29 @@ async function getAssetCommand(context, assetId, options) {
     { label: "url", value: asset.url ?? "" }
   ]);
 }
-async function fetchAsset(context, organizationId, libraryId, assetId) {
+async function fetchAsset(context, assetId) {
+  const organizationId = await context.resolveOrg();
+  const libraryId = await context.resolveLibrary();
   const client = context.clientFactory();
   return unwrapResult(() => client.GET("/organizations/{organizationId}/libraries/{libraryId}/assets/{assetId}", {
     params: { path: { organizationId, libraryId, assetId }, header: VERSION_HEADER }
   }));
 }
 var searchOptionsSchema = exports_external.object({
-  org: exports_external.string().min(1),
-  library: exports_external.array(exports_external.string().min(1)).default([]),
   page: exports_external.coerce.number().int().min(1).optional(),
   pageSize: exports_external.coerce.number().int().min(1).optional()
 });
 async function searchAssetsCommand(context, query, options) {
   requireApiKey(context);
+  const organizationId = await context.resolveOrg();
   const client = context.clientFactory();
   const result = await unwrapResult(() => client.GET("/organizations/{organizationId}/search/assets", {
     params: {
-      path: { organizationId: options.org },
+      path: { organizationId },
       header: VERSION_HEADER,
       query: {
         q: query,
-        libraries: options.library.length > 0 ? options.library.join(",") : undefined,
+        libraries: context.explicitLibrary,
         page: options.page,
         pageSize: options.pageSize
       }
@@ -17369,13 +17407,13 @@ async function searchAssetsCommand(context, query, options) {
   note(context, `${result.found} result(s), page ${result.page}.`);
   renderTable(context, result.hits, SEARCH_HIT_COLUMNS);
 }
-var downloadOptionsSchema = inLibraryOptionsSchema.extend({
+var downloadOptionsSchema = exports_external.object({
   output: exports_external.string().min(1).optional(),
   force: exports_external.boolean().default(false)
 });
 async function downloadAssetCommand(context, assetId, options) {
   requireApiKey(context);
-  const asset = await fetchAsset(context, options.org, options.library, assetId);
+  const asset = await fetchAsset(context, assetId);
   const fileUrl = asset.url;
   if (!fileUrl)
     throw new CliError("Asset has no file URL to download.", EXIT_CODES.generic);
@@ -17399,11 +17437,12 @@ async function downloadAssetCommand(context, assetId, options) {
 var uploadedAssetsSchema = exports_external.object({
   assets: exports_external.array(exports_external.looseObject({ id: exports_external.string().optional(), name: exports_external.string().nullish() }))
 });
-var uploadOptionsSchema = inLibraryOptionsSchema;
-async function uploadAssetsCommand(context, files, options) {
+async function uploadAssetsCommand(context, files) {
   if (files.length === 0)
     throw new UsageError("Provide at least one file to upload.");
   const { key } = requireApiKey(context);
+  const organizationId = await context.resolveOrg();
+  const libraryId = await context.resolveLibrary();
   const batches = chunk(files, MAX_UPLOAD_FILES);
   const uploadedNames = [];
   const payloads = [];
@@ -17421,7 +17460,7 @@ async function uploadAssetsCommand(context, files, options) {
     if (batches.length > 1) {
       note(context, `Uploading batch ${batchIndex + 1}/${batches.length} (${batch.length} files)…`);
     }
-    const response = await context.fetch(`${context.baseUrl}/organizations/${options.org}/libraries/${options.library}/assets`, { method: "POST", headers: buildRequestHeaders(key), body: formData });
+    const response = await context.fetch(`${context.baseUrl}/organizations/${organizationId}/libraries/${libraryId}/assets`, { method: "POST", headers: buildRequestHeaders(key), body: formData });
     const payload = await parseEnvelope(response);
     payloads.push(payload);
     const parsed = uploadedAssetsSchema.safeParse(payload);
@@ -17439,7 +17478,7 @@ async function uploadAssetsCommand(context, files, options) {
 `);
   }
 }
-var removeOptionsSchema = inLibraryOptionsSchema.extend({
+var removeOptionsSchema = exports_external.object({
   yes: exports_external.boolean().default(false)
 });
 async function removeAssetsCommand(context, assetIds, options) {
@@ -17449,6 +17488,8 @@ async function removeAssetsCommand(context, assetIds, options) {
     throw new ValidationError(`At most ${MAX_DELETE_IDS} asset ids are supported per call.`);
   }
   requireApiKey(context);
+  const organizationId = await context.resolveOrg();
+  const libraryId = await context.resolveLibrary();
   if (!options.yes && context.isInteractive) {
     const confirmed = await context.confirm(`Move ${assetIds.length} asset(s) to trash?`);
     if (!confirmed) {
@@ -17458,10 +17499,7 @@ async function removeAssetsCommand(context, assetIds, options) {
   }
   const client = context.clientFactory();
   const result = await unwrapResult(() => client.DELETE("/organizations/{organizationId}/libraries/{libraryId}/assets", {
-    params: {
-      path: { organizationId: options.org, libraryId: options.library },
-      header: VERSION_HEADER
-    },
+    params: { path: { organizationId, libraryId }, header: VERSION_HEADER },
     body: { ids: assetIds }
   }));
   if (context.json) {
@@ -17470,15 +17508,17 @@ async function removeAssetsCommand(context, assetIds, options) {
   }
   note(context, `Moved ${assetIds.length} asset(s) to trash. They are recoverable from the library trash.`);
 }
-var describeOptionsSchema = inLibraryOptionsSchema.extend({
+var describeOptionsSchema = exports_external.object({
   text: exports_external.string().min(1)
 });
 async function describeAssetCommand(context, assetId, options) {
   requireApiKey(context);
+  const organizationId = await context.resolveOrg();
+  const libraryId = await context.resolveLibrary();
   const client = context.clientFactory();
   const asset = await unwrapResult(() => client.PATCH("/organizations/{organizationId}/libraries/{libraryId}/assets/{assetId}/description", {
     params: {
-      path: { organizationId: options.org, libraryId: options.library, assetId },
+      path: { organizationId, libraryId, assetId },
       header: VERSION_HEADER
     },
     body: { description: options.text }
@@ -17489,36 +17529,36 @@ async function describeAssetCommand(context, assetId, options) {
   }
   note(context, "Description updated.");
 }
-var transferOptionsSchema = inLibraryOptionsSchema.extend({
-  to: exports_external.string().min(1),
-  asset: exports_external.array(exports_external.string().min(1)).min(1)
+var transferOptionsSchema = exports_external.object({
+  to: exports_external.string().min(1)
 });
-async function transferAssetsCommand(context, options) {
+async function transferAssetsCommand(context, assetIds, options) {
+  if (assetIds.length === 0)
+    throw new UsageError("Provide at least one asset id.");
   requireApiKey(context);
+  const organizationId = await context.resolveOrg();
+  const libraryId = await context.resolveLibrary();
   const client = context.clientFactory();
   const result = await unwrapResult(() => client.POST("/organizations/{organizationId}/libraries/{libraryId}/assets/transfer", {
-    params: {
-      path: { organizationId: options.org, libraryId: options.library },
-      header: VERSION_HEADER
-    },
-    body: { targetLibraryId: options.to, assetIds: options.asset }
+    params: { path: { organizationId, libraryId }, header: VERSION_HEADER },
+    body: { targetLibraryId: options.to, assetIds }
   }));
   if (context.json) {
     printJson(context, result);
     return;
   }
-  note(context, `Transferred ${options.asset.length} asset(s) to library ${options.to}.`);
+  note(context, `Transferred ${assetIds.length} asset(s) to library ${options.to}.`);
 }
 function registerAssetCommands(program2, runAction) {
   const assets = program2.command("assets").description("Work with assets in a library");
-  assets.command("ls").description("List assets in a library").requiredOption("--org <organizationId>", "Organization id").requiredOption("--library <libraryId>", "Library id").option("--page <number>", "Page number (1-based)").option("--page-size <number>", "Results per page").option("--tag <tag...>", "Filter by tag (repeatable, up to 5)").action((options, command) => runAction(command, (context) => listAssetsCommand(context, parseOptions(listOptionsSchema, options))));
-  assets.command("get").description("Show a single asset").argument("<assetId>", "Asset id").requiredOption("--org <organizationId>", "Organization id").requiredOption("--library <libraryId>", "Library id").action((assetId, options, command) => runAction(command, (context) => getAssetCommand(context, assetId, parseOptions(getOptionsSchema, options))));
-  assets.command("search").description("Search assets across the organization").argument("<query>", "Search query").requiredOption("--org <organizationId>", "Organization id").option("--library <libraryId...>", "Restrict to specific libraries (repeatable)").option("--page <number>", "Page number (1-based)").option("--page-size <number>", "Results per page").action((query, options, command) => runAction(command, (context) => searchAssetsCommand(context, query, parseOptions(searchOptionsSchema, options))));
-  assets.command("download").description("Download an asset's file").argument("<assetId>", "Asset id").requiredOption("--org <organizationId>", "Organization id").requiredOption("--library <libraryId>", "Library id").option("-o, --output <path>", "Target file path").option("--force", "Overwrite the target file if it exists").action((assetId, options, command) => runAction(command, (context) => downloadAssetCommand(context, assetId, parseOptions(downloadOptionsSchema, options))));
-  assets.command("upload").description("Upload local files as assets").argument("<files...>", "Local file paths").requiredOption("--org <organizationId>", "Organization id").requiredOption("--library <libraryId>", "Library id").action((files, options, command) => runAction(command, (context) => uploadAssetsCommand(context, files, parseOptions(uploadOptionsSchema, options))));
-  assets.command("rm").description("Move assets to trash (recoverable)").argument("<assetIds...>", "Asset ids").requiredOption("--org <organizationId>", "Organization id").requiredOption("--library <libraryId>", "Library id").option("--yes", "Skip the confirmation prompt").action((assetIds, options, command) => runAction(command, (context) => removeAssetsCommand(context, assetIds, parseOptions(removeOptionsSchema, options))));
-  assets.command("describe").description("Set an asset's description").argument("<assetId>", "Asset id").requiredOption("--org <organizationId>", "Organization id").requiredOption("--library <libraryId>", "Library id").requiredOption("--text <description>", "Description text").action((assetId, options, command) => runAction(command, (context) => describeAssetCommand(context, assetId, parseOptions(describeOptionsSchema, options))));
-  assets.command("transfer").description("Move assets to another library").requiredOption("--org <organizationId>", "Organization id").requiredOption("--library <libraryId>", "Source library id").requiredOption("--to <libraryId>", "Target library id").requiredOption("--asset <assetId...>", "Asset ids (repeatable)").action((options, command) => runAction(command, (context) => transferAssetsCommand(context, parseOptions(transferOptionsSchema, options))));
+  assets.command("ls").description("List assets in the library").option("--page <number>", "Page number (1-based)").option("--page-size <number>", "Results per page").option("--tag <tag...>", "Filter by tag (repeatable, up to 5)").action((options, command) => runAction(command, (context) => listAssetsCommand(context, parseOptions(listOptionsSchema, options))));
+  assets.command("get").description("Show a single asset").argument("<assetId>", "Asset id").action((assetId, _options, command) => runAction(command, (context) => getAssetCommand(context, assetId)));
+  assets.command("search").description("Search assets across the organization (pass --library to scope to one)").argument("<query>", "Search query").option("--page <number>", "Page number (1-based)").option("--page-size <number>", "Results per page").action((query, options, command) => runAction(command, (context) => searchAssetsCommand(context, query, parseOptions(searchOptionsSchema, options))));
+  assets.command("download").description("Download an asset's file").argument("<assetId>", "Asset id").option("-o, --output <path>", "Target file path").option("--force", "Overwrite the target file if it exists").action((assetId, options, command) => runAction(command, (context) => downloadAssetCommand(context, assetId, parseOptions(downloadOptionsSchema, options))));
+  assets.command("upload").description("Upload local files as assets").argument("<files...>", "Local file paths").action((files, _options, command) => runAction(command, (context) => uploadAssetsCommand(context, files)));
+  assets.command("rm").description("Move assets to trash (recoverable)").argument("<assetIds...>", "Asset ids").option("--yes", "Skip the confirmation prompt").action((assetIds, options, command) => runAction(command, (context) => removeAssetsCommand(context, assetIds, parseOptions(removeOptionsSchema, options))));
+  assets.command("describe").description("Set an asset's description").argument("<assetId>", "Asset id").requiredOption("--text <description>", "Description text").action((assetId, options, command) => runAction(command, (context) => describeAssetCommand(context, assetId, parseOptions(describeOptionsSchema, options))));
+  assets.command("transfer").description("Move assets to another library").argument("<assetIds...>", "Asset ids to move").requiredOption("--to <libraryId>", "Target library id").action((assetIds, options, command) => runAction(command, (context) => transferAssetsCommand(context, assetIds, parseOptions(transferOptionsSchema, options))));
 }
 
 // src/commands/auth.ts
@@ -17526,23 +17566,26 @@ async function fetchViewer(context, apiKey) {
   const client = context.clientFactory({ apiKey });
   return unwrapResult(() => client.GET("/me", { params: { header: VERSION_HEADER } }));
 }
-var loginOptionsSchema = exports_external.object({
-  apiKey: exports_external.string().min(1).optional()
-});
-async function loginCommand(context, options) {
-  const promptedKey = options.apiKey ?? (context.isInteractive ? await context.promptSecret("Paste your Raster API key") : null);
-  if (!promptedKey) {
+async function loginCommand(context) {
+  const flagKey = context.apiKey?.source === "flag" ? context.apiKey.key : null;
+  const key = flagKey ?? (context.isInteractive ? await context.promptSecret("Paste your Raster API key") : null);
+  if (!key) {
     throw new UsageError("Provide a key with --api-key, or run `raster auth login` in an interactive terminal.");
   }
-  const viewer = await fetchViewer(context, promptedKey);
+  const viewer = await fetchViewer(context, key);
   const config2 = await readConfig(context.env);
-  await writeConfig({ ...config2, apiKey: promptedKey }, context.env);
+  await writeConfig({
+    ...config2,
+    apiKey: key,
+    organizationId: viewer?.organizationId,
+    libraries: (viewer?.libraries ?? []).filter((library) => typeof library === "string")
+  }, context.env);
   if (context.json) {
     printJson(context, viewer);
     return;
   }
   const organizationLabel = viewer?.organizationName ?? viewer?.organizationId ?? "your organization";
-  note(context, `Logged in to ${organizationLabel} as ${maskApiKey(promptedKey)}. Key stored in ${configPath(context.env)}.`);
+  note(context, `Logged in to ${organizationLabel} as ${maskApiKey(key)}. Key stored in ${configPath(context.env)}.`);
 }
 async function logoutCommand(context) {
   const config2 = await readConfig(context.env);
@@ -17599,7 +17642,7 @@ async function whoamiCommand(context) {
 }
 function registerAuthCommands(program2, runAction) {
   const auth = program2.command("auth").description("Manage CLI authentication");
-  auth.command("login").description("Validate an API key against the API and store it").option("--api-key <key>", "API key to store (prompts when omitted)").action((options, command) => runAction(command, (context) => loginCommand(context, parseOptions(loginOptionsSchema, options))));
+  auth.command("login").description("Validate an API key against the API and store it (pass --api-key, or run interactively to be prompted)").action((_options, command) => runAction(command, (context) => loginCommand(context)));
   auth.command("logout").description("Remove the stored API key").action((_options, command) => runAction(command, (context) => logoutCommand(context)));
   auth.command("status").description("Show which API key is in use and where it came from").action((_options, command) => runAction(command, (context) => statusCommand(context)));
   program2.command("whoami").description("Show the organization and libraries the API key can access").action((_options, command) => runAction(command, (context) => whoamiCommand(context)));
@@ -17614,16 +17657,16 @@ var LIBRARY_COLUMNS = [
   { header: "TAGS", value: (library) => String((library.tags ?? []).length) }
 ];
 var listOptionsSchema2 = exports_external.object({
-  org: exports_external.string().min(1),
   page: exports_external.coerce.number().int().min(1).optional(),
   pageSize: exports_external.coerce.number().int().min(1).optional()
 });
 async function listLibrariesCommand(context, options) {
   requireApiKey(context);
+  const organizationId = await context.resolveOrg();
   const client = context.clientFactory();
   const libraries = await unwrapResult(() => client.GET("/organizations/{organizationId}/libraries", {
     params: {
-      path: { organizationId: options.org },
+      path: { organizationId },
       header: VERSION_HEADER,
       query: { page: options.page, pageSize: options.pageSize }
     }
@@ -17635,15 +17678,15 @@ async function listLibrariesCommand(context, options) {
   renderTable(context, libraries, LIBRARY_COLUMNS);
 }
 var createOptionsSchema = exports_external.object({
-  org: exports_external.string().min(1),
   name: exports_external.string().min(1),
   slug: exports_external.string().min(1).optional()
 });
 async function createLibraryCommand(context, options) {
   requireApiKey(context);
+  const organizationId = await context.resolveOrg();
   const client = context.clientFactory();
   const library = await unwrapResult(() => client.POST("/organizations/{organizationId}/libraries", {
-    params: { path: { organizationId: options.org }, header: VERSION_HEADER },
+    params: { path: { organizationId }, header: VERSION_HEADER },
     body: { name: options.name, slug: options.slug }
   }));
   if (context.json) {
@@ -17657,16 +17700,16 @@ async function createLibraryCommand(context, options) {
   note(context, "Library created.");
 }
 var renameOptionsSchema = exports_external.object({
-  org: exports_external.string().min(1),
-  library: exports_external.string().min(1),
   name: exports_external.string().min(1)
 });
 async function renameLibraryCommand(context, options) {
   requireApiKey(context);
+  const organizationId = await context.resolveOrg();
+  const libraryId = await context.resolveLibrary();
   const client = context.clientFactory();
   const library = await unwrapResult(() => client.PATCH("/organizations/{organizationId}/libraries/{libraryId}", {
     params: {
-      path: { organizationId: options.org, libraryId: options.library },
+      path: { organizationId, libraryId },
       header: VERSION_HEADER
     },
     body: { name: options.name }
@@ -17679,9 +17722,9 @@ async function renameLibraryCommand(context, options) {
 }
 function registerLibraryCommands(program2, runAction) {
   const libraries = program2.command("libraries").description("Work with libraries");
-  libraries.command("ls").description("List libraries in an organization").requiredOption("--org <organizationId>", "Organization id").option("--page <number>", "Page number (1-based)").option("--page-size <number>", "Results per page").action((options, command) => runAction(command, (context) => listLibrariesCommand(context, parseOptions(listOptionsSchema2, options))));
-  libraries.command("create").description("Create a library").requiredOption("--org <organizationId>", "Organization id").requiredOption("--name <name>", "Library name").option("--slug <slug>", "URL slug for the library").action((options, command) => runAction(command, (context) => createLibraryCommand(context, parseOptions(createOptionsSchema, options))));
-  libraries.command("rename").description("Rename a library").requiredOption("--org <organizationId>", "Organization id").requiredOption("--library <libraryId>", "Library id").requiredOption("--name <name>", "New library name").action((options, command) => runAction(command, (context) => renameLibraryCommand(context, parseOptions(renameOptionsSchema, options))));
+  libraries.command("ls").description("List libraries in the organization").option("--page <number>", "Page number (1-based)").option("--page-size <number>", "Results per page").action((options, command) => runAction(command, (context) => listLibrariesCommand(context, parseOptions(listOptionsSchema2, options))));
+  libraries.command("create").description("Create a library").requiredOption("--name <name>", "Library name").option("--slug <slug>", "URL slug for the library").action((options, command) => runAction(command, (context) => createLibraryCommand(context, parseOptions(createOptionsSchema, options))));
+  libraries.command("rename").description("Rename the library (the one the key scopes to, or pass --library)").requiredOption("--name <name>", "New library name").action((options, command) => runAction(command, (context) => renameLibraryCommand(context, parseOptions(renameOptionsSchema, options))));
 }
 
 // src/commands/orgs.ts
@@ -17733,16 +17776,16 @@ var TAG_COLUMNS = [
   { header: "TYPE", value: (tag) => tag.type ?? "" }
 ];
 var listOptionsSchema3 = exports_external.object({
-  org: exports_external.string().min(1),
-  library: exports_external.string().min(1),
   limit: exports_external.coerce.number().int().min(1).optional()
 });
 async function listTagsCommand(context, options) {
   requireApiKey(context);
+  const organizationId = await context.resolveOrg();
+  const libraryId = await context.resolveLibrary();
   const client = context.clientFactory();
   const tags = await unwrapResult(() => client.GET("/organizations/{organizationId}/libraries/{libraryId}/tags", {
     params: {
-      path: { organizationId: options.org, libraryId: options.library },
+      path: { organizationId, libraryId },
       header: VERSION_HEADER,
       query: { limit: options.limit }
     }
@@ -17754,53 +17797,54 @@ async function listTagsCommand(context, options) {
   renderTable(context, tags, TAG_COLUMNS);
 }
 var mutateOptionsSchema = exports_external.object({
-  org: exports_external.string().min(1),
-  library: exports_external.string().min(1),
-  asset: exports_external.array(exports_external.string().min(1)).min(1),
   tag: exports_external.array(exports_external.string().min(1)).min(1)
 });
-async function tagAssetsCommand(context, options) {
+async function tagAssetsCommand(context, assetIds, options) {
+  if (assetIds.length === 0)
+    throw new UsageError("Provide at least one asset id.");
   requireApiKey(context);
+  const organizationId = await context.resolveOrg();
+  const libraryId = await context.resolveLibrary();
   const client = context.clientFactory();
   const result = await unwrapResult(() => client.POST("/organizations/{organizationId}/libraries/{libraryId}/assets/tag", {
-    params: {
-      path: { organizationId: options.org, libraryId: options.library },
-      header: VERSION_HEADER
-    },
-    body: { assetIds: options.asset, tags: options.tag }
+    params: { path: { organizationId, libraryId }, header: VERSION_HEADER },
+    body: { assetIds, tags: options.tag }
   }));
   if (context.json) {
     printJson(context, result);
     return;
   }
-  note(context, `Tagged ${options.asset.length} asset(s) with ${options.tag.join(", ")}.`);
+  note(context, `Tagged ${assetIds.length} asset(s) with ${options.tag.join(", ")}.`);
 }
-async function untagAssetsCommand(context, options) {
+async function untagAssetsCommand(context, assetIds, options) {
+  if (assetIds.length === 0)
+    throw new UsageError("Provide at least one asset id.");
   requireApiKey(context);
+  const organizationId = await context.resolveOrg();
+  const libraryId = await context.resolveLibrary();
   const client = context.clientFactory();
   const result = await unwrapResult(() => client.POST("/organizations/{organizationId}/libraries/{libraryId}/assets/untag", {
-    params: {
-      path: { organizationId: options.org, libraryId: options.library },
-      header: VERSION_HEADER
-    },
-    body: { assetIds: options.asset, tags: options.tag }
+    params: { path: { organizationId, libraryId }, header: VERSION_HEADER },
+    body: { assetIds, tags: options.tag }
   }));
   if (context.json) {
     printJson(context, result);
     return;
   }
-  note(context, `Removed ${options.tag.join(", ")} from ${options.asset.length} asset(s).`);
+  note(context, `Removed ${options.tag.join(", ")} from ${assetIds.length} asset(s).`);
 }
 function registerTagCommands(program2, runAction) {
   const tags = program2.command("tags").description("Work with tags in a library");
-  tags.command("ls").description("List tags in a library").requiredOption("--org <organizationId>", "Organization id").requiredOption("--library <libraryId>", "Library id").option("--limit <number>", "Maximum number of tags to return").action((options, command) => runAction(command, (context) => listTagsCommand(context, parseOptions(listOptionsSchema3, options))));
-  tags.command("add").description("Add tags to assets").requiredOption("--org <organizationId>", "Organization id").requiredOption("--library <libraryId>", "Library id").requiredOption("--asset <assetId...>", "Asset ids (repeatable)").requiredOption("--tag <tag...>", "Tags to add (repeatable)").action((options, command) => runAction(command, (context) => tagAssetsCommand(context, parseOptions(mutateOptionsSchema, options))));
-  tags.command("rm").description("Remove tags from assets").requiredOption("--org <organizationId>", "Organization id").requiredOption("--library <libraryId>", "Library id").requiredOption("--asset <assetId...>", "Asset ids (repeatable)").requiredOption("--tag <tag...>", "Tags to remove (repeatable)").action((options, command) => runAction(command, (context) => untagAssetsCommand(context, parseOptions(mutateOptionsSchema, options))));
+  tags.command("ls").description("List tags in the library").option("--limit <number>", "Maximum number of tags to return").action((options, command) => runAction(command, (context) => listTagsCommand(context, parseOptions(listOptionsSchema3, options))));
+  tags.command("add").description("Add tags to assets").argument("<assetIds...>", "Asset ids to tag").requiredOption("--tag <tag...>", "Tags to add (repeatable)").action((assetIds, options, command) => runAction(command, (context) => tagAssetsCommand(context, assetIds, parseOptions(mutateOptionsSchema, options))));
+  tags.command("rm").description("Remove tags from assets").argument("<assetIds...>", "Asset ids to untag").requiredOption("--tag <tag...>", "Tags to remove (repeatable)").action((assetIds, options, command) => runAction(command, (context) => untagAssetsCommand(context, assetIds, parseOptions(mutateOptionsSchema, options))));
 }
 
 // src/index.ts
 var globalOptionsSchema = exports_external.object({
   apiKey: exports_external.string().optional(),
+  org: exports_external.string().optional(),
+  library: exports_external.string().optional(),
   json: exports_external.boolean().optional(),
   verbose: exports_external.boolean().optional()
 });
@@ -17830,7 +17874,7 @@ function exitCodeForCommanderError(error51) {
   return EXIT_CODES.generic;
 }
 var program2 = new Command;
-program2.name("raster").description("Command-line client for the Raster API").version(`${package_default.version} (Api-Version ${API_VERSION})`, "-V, --version", "Print the CLI version and the pinned Api-Version").option("--api-key <key>", "API key (overrides RASTER_API_KEY and the config file)").option("--json", "Print machine-readable JSON to stdout").option("--verbose", "Log requests to stderr (keys masked)").exitOverride();
+program2.name("raster").description("Command-line client for the Raster API").version(`${package_default.version} (Api-Version ${API_VERSION})`, "-V, --version", "Print the CLI version and the pinned Api-Version").option("--api-key <key>", "API key (overrides RASTER_API_KEY and the config file)").option("--org <organizationId>", "Organization id (derived from the API key when omitted)").option("--library <libraryId>", "Library id (derived from the API key when it has one library)").option("--json", "Print machine-readable JSON to stdout").option("--verbose", "Log requests to stderr (keys masked)").exitOverride();
 registerAuthCommands(program2, runAction);
 registerLibraryCommands(program2, runAction);
 registerAssetCommands(program2, runAction);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raster-app/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Command-line client for the Raster API",
   "license": "Apache-2.0",
   "type": "module",