Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: "Call the Admin API from the CLI"
sidebarTitle: "Admin API"
description: "Use spree api for generic get/post/patch/delete calls, schema introspection, and zero-config credentials — built for scripts and AI agents."
---
The `spree api` command group turns the CLI into a first-class Admin API client: generic HTTP verbs against any endpoint, schema introspection without leaving the terminal, and credentials that resolve automatically — from a local dev project to a production store profile. It works against any Spree 5.5+ instance and is designed to be driven by both humans and AI coding agents.
```bash
spree api get /products -q status_eq=active --sort -created_at --limit 10
spree api get /orders/ord_x8k2J9aQ --expand items,payments
spree api post /products -d '{"name":"Classic Tee","prices":[{"currency":"USD","amount":"29.99"}]}'
spree api patch /orders/ord_x8k2J9aQ/cancel
spree api endpoints --resource orders
spree api schema "POST /orders/{id}/refunds"
spree api status
```
## Credentials
Credentials resolve through four layers — first match wins:
| Layer | How |
|---|---|
| Flags | `--base-url` / `--api-key` (and `--profile`, which selects a saved profile explicitly) |
| Environment | `SPREE_API_KEY` (+ `SPREE_BASE_URL`) — the path for CI and agents. `SPREE_BASE_URL` is optional: a bare key defaults to `http://localhost:3000`, so local dev needs only the key. Set it for a remote store. |
| Project | Inside a Spree project with the dev stack running, the CLI mints a **read-only** key on first use and stores it in `.spree/credentials.json` (gitignored) |
| Profile | `~/.config/spree/config.json`, written by `spree auth login` |
Host and key resolve **together** per source — a saved or minted key is never silently re-pointed at a host from a different layer. Only `--base-url` (or `SPREE_BASE_URL` paired with `SPREE_API_KEY`) re-points a key deliberately. So against local dev:
```bash
SPREE_API_KEY=sk_xxx spree api get /products # → http://localhost:3000
```
Zero configuration is needed for local development — the first `spree api get` inside your project just works:
```bash
cd my-store
spree api get /products
# No credentials found — minting a read-only API key via the dev stack...
# Saved to .spree/credentials.json (scopes: read_all)
```
Auto-minted keys carry `read_all` only. Writes always require an explicitly created key:
```bash
spree api-key create --type secret --scopes read_orders,write_products
```
For remote stores, create a secret key in the admin under **Settings → API Keys** and save it as a profile — the key is read from a prompt, never from a flag:
```bash
spree auth login --profile prod --base-url https://store.example.com
spree api get /orders --profile prod -q "status_eq=placed"
spree auth status
spree auth logout --profile prod
```
### Use with a sandbox
A [free sandbox](https://console.spree.sh) works like any remote store. Create a secret key in the sandbox admin under **Settings → API Keys**, then save it as a profile:
```bash
spree auth login --profile sandbox --base-url https://your-store.spree.sh
spree api get /products --profile sandbox
```
No local project or Docker needed — the CLI (`npm install -g @spree/cli`) plus a sandbox is a complete environment for exploring the Admin API.
## Reading data
`-q` takes [Ransack](/api-reference/admin-api/querying) predicates as repeatable `key=value` pairs; sorting, pagination, and shaping flags pass through under the Admin API conventions:
```bash
spree api get /products -q name_cont=shirt -q status_eq=active
spree api get /orders --sort -created_at --page 2 --limit 50
spree api get /products/prod_86Rf07xd --expand variants,variants.prices
spree api get /customers --fields id,email --format table
```
`--fields` trims the response to the attributes you name (comma-separated). The resource `id` is **always returned** even if you don't list it, so you only need to name the extra fields. `--expand` is the companion axis — `--fields` selects top-level attributes, `--expand` pulls in related resources:
```bash
spree api get /products --fields name,price # → id + name + price
spree api get /products --fields name --expand variants
```
### Output format
Output is JSON on stdout, and it adapts to where it goes:
- **In a terminal** — indented and syntax-colored, for reading.
- **Piped or redirected** — compact, single-line, uncolored, so it stays fast and feeds cleanly into `jq` (color codes would corrupt it).
```bash
spree api get /products --limit 5 | jq '.data[].name'
```
`--format table` renders collections as a table for humans (nested objects collapse to `{…}`, arrays to `[N]`).
## Writing data
Request bodies are flat JSON (no root wrapping), inline, from a file, or from stdin:
```bash
spree api post /products -d '{"name":"Classic Tee","prices":[{"currency":"USD","amount":"29.99"}]}'
spree api post /orders/ord_x8k2J9aQ/refunds -d @refund.json
cat prices.json | spree api post /prices/bulk_upsert -d -
spree api delete /products/prod_86Rf07xd
```
Mutations automatically carry an `Idempotency-Key`, so retries are safe.
### Creating products
A product is a catalog grouping; everything purchasable — SKU, price, stock, weight — lives on its variants. For a **simple product** with no options, ship a top-level `prices` array and Spree creates the single backing variant for you:
```bash
spree api post /products -d '{"name":"Classic Tee","prices":[{"currency":"USD","amount":"29.99"}]}'
```
For a product with options, send the `variants` array, each with its own `options` and `prices` (and optionally `stock_items`):
```bash
spree api post /products -d '{
"name": "Classic Tee",
"variants": [
{ "sku": "TEE-S", "options": [{"name":"size","value":"Small"}], "prices": [{"currency":"USD","amount":"29.99"}] },
{ "sku": "TEE-M", "options": [{"name":"size","value":"Medium"}], "prices": [{"currency":"USD","amount":"29.99"}] }
]
}'
```
Run `spree api schema "POST /products"` for the full request body.
## Discovering endpoints and schemas
The CLI bundles a snapshot of the Admin API OpenAPI spec, so discovery works offline:
```bash
spree api endpoints --resource orders # methods, paths, required scopes
spree api endpoints --search "gift card"
spree api schema "POST /orders" # parameters + request/response schema
spree api status # resolved credentials + server reachability
```
`spree api endpoints` shows the `read_*` / `write_*` scope each endpoint requires (see [Authentication](/api-reference/admin-api/authentication)) — useful for deciding what to grant a new key.
### Shell completion
Tab-completion suggests resource paths, Ransack predicate stems (`name_cont=`, `status_eq=`, …), and scope names — all offline from the bundled spec. Add the generated script to your shell:
```bash
# zsh — add to ~/.zshrc
eval "$(spree completion zsh)"
# bash — add to ~/.bashrc
eval "$(spree completion bash)"
# fish — add to ~/.config/fish/config.fish
spree completion fish | source
```
Then `spree api get /pro⇥` completes to `/products`, and `spree api get /products -q name_⇥` offers the Ransack predicates.
## Errors and exit codes
API errors print the error envelope to stderr and exit `1`; usage and configuration problems exit `2`. A scope denial includes the exact remediation:
```text
access_denied: API key lacks scope: write_products
{
"details": { "required_scope": "write_products" }
}
Hint: mint a key carrying this scope — spree api-key create --type secret --scopes write_products
```
## Using it with AI agents
Agents with shell access (Claude Code, Cursor, and similar) can drive a Spree back office through `spree api` with no extra configuration: inside a project the credentials self-provision read-only, and for remote stores two environment variables (`SPREE_BASE_URL`, `SPREE_API_KEY`) are the whole contract. The `endpoints`/`schema` commands give agents request shapes on demand instead of loading the entire API surface up front, and error messages name the missing scope so agents can self-correct.