Raster CLI

Command-line client for the Raster API. Browse, search, upload, download, tag, transfer, and delete library assets from a terminal or CI pipeline.

Install

npm install -g @raster-app/cli

Run a single command without installing — the binary is raster:

npx -p @raster-app/cli raster whoami

Authenticate

OAuth is the default — an interactive login tied to your user account. For CI and automation, use an organization API key instead.

raster auth login

raster auth login signs you in over OAuth (no API key needed). 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):

raster auth login --api-key pk_…

Or set RASTER_API_KEY. The bearer credential resolves from the --api-key flag, then RASTER_API_KEY, then a stored OAuth token, 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.

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

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

raster whoami

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

raster orgs create --email <email> [--name <name>] [--save]

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 and scripting

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

| Code | Meaning | | ---- | ------------------------------------ | | 0 | Success | | 1 | Unexpected error | | 2 | Usage error (bad flags or arguments) | | 3 | Authentication (missing or rejected key) | | 4 | Not found | | 5 | Validation or conflict | | 6 | File too large | | 7 | Network failure |

Environment variables

| Variable | Purpose | | --- | --- | | RASTER_API_KEY | API key (overrides a stored OAuth token; sits below --api-key, 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

bun install
bun test
bun run check:types
bun run gen:types   # regenerate src/api/openapi.d.ts from the live OpenAPI document
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.

License

Apache-2.0. Bundled third-party packages are attributed in NOTICE.