CLI

Browse, search, upload, and organize your Raster libraries from a terminal or CI pipeline with the Raster command-line client.

The Raster CLI is a command-line client for the REST API. It authenticates with the same API keys as the REST, GraphQL, and MCP surfaces and covers the full asset workflow — list, search, upload, download, tag, transfer, and delete — from a terminal or a CI pipeline.

The CLI is in Alpha. Commands and flags may change before the 1.0 release.

Install

npm install -g @raster-app/cli

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

npx -p @raster-app/cli raster whoami

Each GitHub release also ships a standalone macOS (Apple Silicon) binary that runs without Node.

Authenticate

raster auth login

The command validates your API key against the API and stores it in ~/.config/raster/config.json with owner-only permissions. In CI, set the RASTER_API_KEY environment variable instead.

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, 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.

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

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`	Validate an API key and store it (`--api-key`, or an interactive prompt).	`raster auth login`
`raster auth logout`	Remove the stored API key.	`raster auth logout`
`raster auth status`	Show which key is in use, its source, and the organization it reaches.	`raster auth status`

`whoami`

raster whoami

Show the organization, plan, and libraries the API key can access.

`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, 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:

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 the config file)
`RASTER_CONFIG_HOME`	Config directory override (default `~/.config/raster`)

On this page