CLI

The Raster CLI is a command-line client for the REST API. It signs in over OAuth by default and covers the full asset workflow — list, search, upload, download, tag, transfer, and delete — from a terminal or a CI pipeline.

Install

npm install -g @raster-app/cli

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

npx -p @raster-app/cli raster whoami

Authenticate

raster auth login

raster auth login signs you in over OAuth, tied to your user account. When a browser is available, it opens a browser authorization-code flow and captures the result on a local loopback redirect. Over SSH or on a headless machine it falls back to the device authorization grant: it prints a short user code and the URL https://raster.app/device, which you approve in a browser on any device. Pass --browser or --device to force either flow.

The CLI prints the authorization URL ("Visit <url>") before opening the browser, so you can open it yourself in a browser on the same machine.

OAuth tokens 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 refresh, re-run raster auth login.

API keys for CI and automation

For CI and scripts, sign in with an organization API key:

raster auth login --api-key pk_...

Or set RASTER_API_KEY in the environment. The active credential resolves from the --api-key flag, then RASTER_API_KEY, then a stored OAuth token, then a config-file apiKey. An ambient RASTER_API_KEY therefore takes precedence over a stored OAuth session — handy for scripts and CI. raster auth status shows which credential is in use; for an API key it also names the organization it reaches. raster auth logout revokes the OAuth token (if any) and clears stored credentials.

Org and library

An API key is scoped to one organization and a set of libraries, so the CLI takes the org and library from the key:

• --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 works without auth login. If a key's library access changes, re-run raster auth login to refresh, or pass --library.

A broad user-scope OAuth login reaches every organization you belong to. Because no single org is implied, commands that act on one organization need you to choose it: pass --org <id>, set RASTER_ORG, or set a defaultOrg in the config file. Without a selection the command stops with a clear error. Run raster whoami to list the organizations you can reach. An org-scoped OAuth login and an API key resolve their single organization automatically.

Global flags

These work on every command, before or after the subcommand.

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

whoami

raster whoami

Show the organizations, plan, and libraries the current credential can access. A broad user-scope OAuth login lists every organization you can reach, so you can pick one with --org. An org-scoped OAuth login and an API key show their single organization.

libraries

assets

tags

orgs

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

Create an organization and library with no account, the anonymous flow documented at POST /libraries. Prints the claim URL; --save stores the minted 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 are stable across releases:

Environment variables