Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Make Spree CLI more discoverable; drop "gh-style" phrasing

Damian Legawiecbef515dadaba
diff --git a/README.md b/README.md
index 59e90aabb2..8ffbad6f0f 100755
--- a/README.md
+++ b/README.md
@@ -54,6 +54,19 @@ npx skills add spree/agent-skills
Then connect the [docs MCP server](https://spreecommerce.org/docs/developer/agentic/mcp) and let your agent build with you. Learn more in the [Agentic Development docs](https://spreecommerce.org/docs/developer/agentic/overview).
+### Spree CLI
+
+[`@spree/cli`](packages/cli) manages your Spree project from the terminal — boot the stack, run generators and migrations, tail logs — and calls the **Admin API** directly with simple `get`/`post`/`patch`/`delete` commands. It's a fast way to inspect and script your store, and works hands-free for AI agents (zero-config credentials in local dev):
+
+```bash
+spree dev # boot the project (web + worker + db)
+spree generate model Wishlist # Rails generators, in the container
+spree api get /orders -q status_eq=complete --limit 10 # query the Admin API
+spree api post /products -d '{"name":"Classic Tee"}' # create resources
+```
+
+`spree api endpoints` and `spree api schema` explore the full API offline. See the [CLI docs](https://spreecommerce.org/docs/developer/cli/quickstart).
+
If you prefer to install Spree manually, you may follow the [Quickstart Guide](https://spreecommerce.org/docs/developer/getting-started/quickstart).
If you like what you see, consider giving Spree a GitHub star ⭐
@@ -65,6 +78,7 @@ Thank you for supporting Spree open-source ❤️
Everything below ships in this repository under the BSD 3-Clause license.
* **[REST API & TypeScript SDK](https://spreecommerce.org/docs/api-reference/store-api/introduction)** — production-grade REST API, publishable keys, rate limiting, and OpenAPI 3.0 spec. The [TypeScript SDK](https://spreecommerce.org/docs/developer/sdk/quickstart) adds autocomplete and type safety.
+* **[Spree CLI](https://spreecommerce.org/docs/developer/cli/quickstart)** — manage projects from the terminal (boot, generate, migrate, upgrade) and call the Admin API directly with `spree api get/post/...` — zero-config in local dev, built for scripts and AI agents.
* **[Next.js Storefront](https://github.com/spree/storefront)** — open-source storefront built with Next.js 16, React 19, Tailwind CSS 4, and TypeScript. Full shopping experience, multi-region URL routing, Stripe payments (Apple Pay, Google Pay, Klarna, Affirm), customer accounts, and SEO built in. [Try the demo](https://demo.spreecommerce.org/)
* **[Cross-Border Commerce](https://spreecommerce.org/docs/user/settings/markets)** — Markets bundle currency, language, payment methods, and shipping rules per country. Translations Center for bulk product localization. EU Omnibus Directive compliance with automatic 30-day price history.
* **[B2B & Wholesale](https://spreecommerce.org/docs/developer/core-concepts/products#price-lists)** — [Price Lists](https://spreecommerce.org/docs/developer/core-concepts/products#price-lists) for regional, B2B, and wholesale pricing. [Customer Groups](https://spreecommerce.org/docs/user/customers/customer-groups) for segmentation. Companies, company locations, and company contacts for buyer organizations. Catalogs for curated, per-segment product assortments. Gated storefronts via publishable keys.
@@ -73,7 +87,7 @@ Everything below ships in this repository under the BSD 3-Clause license.
* **[Promotions & Gift Cards](https://spreecommerce.org/docs/user/promotions/create-a-promotion)** — advanced promotions engine and [Gift Cards](https://spreecommerce.org/docs/developer/core-concepts/store-credits-gift-cards).
* **Products & Catalog** — [Metafields](https://spreecommerce.org/docs/developer/core-concepts/metafields), [CSV importer/exporter](https://spreecommerce.org/docs/user/manage-products/import-products), digital products, product tags, [bulk operations](https://spreecommerce.org/docs/user/manage-products/bulk-product-operations).
* **[MeiliSearch Integration](https://spreecommerce.org/docs/integrations/search/meilisearch)** — typo-tolerant product search and faceted filtering.
-* **Admin Dashboard** — built with [Tailwind CSS](https://spreecommerce.org/docs/developer/admin/custom-css), [Tables DSL](https://spreecommerce.org/docs/developer/admin/tables), and [role-based permissions](https://spreecommerce.org/docs/developer/customization/permissions).
+* **Admin Dashboard** — built with [Tailwind CSS](https://spreecommerce.org/docs/developer/admin/custom-css) with [role-based permissions](https://spreecommerce.org/docs/developer/customization/permissions).
* **Integrations & Extensibility** — [Event Bus](https://spreecommerce.org/docs/developer/core-concepts/events), [Webhooks 2.0](https://spreecommerce.org/docs/developer/core-concepts/webhooks), native integrations ([GA4](https://spreecommerce.org/docs/integrations/analytics/google-analytics), [GTM](https://spreecommerce.org/docs/integrations/analytics/google-tag-manager), [Klaviyo](https://spreecommerce.org/docs/integrations/marketing/klaviyo)).
* **[Agentic Development](https://spreecommerce.org/docs/developer/agentic/overview)** — [25 agent skills](https://github.com/spree/agent-skills) (`npx skills add spree/agent-skills`) teaching AI coding agents Spree's conventions, a [docs MCP server](https://spreecommerce.org/docs/developer/agentic/mcp), [LLM-ready documentation](https://spreecommerce.org/docs/developer/agentic/llm-docs) (llms.txt, per-page Markdown, offline npm package), and a generated AGENTS.md/CLAUDE.md in every scaffolded project.
diff --git a/docs/api-reference/admin-api/errors.mdx b/docs/api-reference/admin-api/errors.mdx
index 044c65919c..ff2c710a97 100644
--- a/docs/api-reference/admin-api/errors.mdx
+++ b/docs/api-reference/admin-api/errors.mdx
@@ -5,6 +5,10 @@ description: "Reference for the Spree Admin API Stripe-style error response form
The Admin API uses the same Stripe-style error format as the rest of the Spree v3 API. Every error response carries a machine-readable `code` and a human-readable `message`.
+<Tip>
+Debugging a failing request? The [Spree CLI](/developer/cli/admin-api) is the fastest probe: `spree api get /orders/<id>` shows the live state, and on a `403` it prints the exact missing scope plus the command to mint a key that has it.
+</Tip>
+
## Error response format
```json
diff --git a/docs/api-reference/admin-api/introduction.mdx b/docs/api-reference/admin-api/introduction.mdx
index e878ce200f..d0ee568b5f 100644
--- a/docs/api-reference/admin-api/introduction.mdx
+++ b/docs/api-reference/admin-api/introduction.mdx
@@ -56,7 +56,7 @@ const { data: orders } = await client.orders.list({
## From the command line
-Every endpoint can also be called with the [Spree CLI](/developer/cli/admin-api) — a `gh api`-style client built into `@spree/cli`. It's the fastest way to explore the API from a terminal or drive it from scripts and AI agents, with zero-config credentials in local development:
+Every endpoint can also be called with the [Spree CLI](/developer/cli/admin-api) — a generic HTTP client (`get`/`post`/`patch`/`delete`) built into `@spree/cli`. It's the fastest way to explore the API from a terminal or drive it from scripts and AI agents, with zero-config credentials in local development:
```bash
spree api get /orders -q status_eq=complete --limit 25
diff --git a/docs/developer/agentic/overview.mdx b/docs/developer/agentic/overview.mdx
index fce328fcbd..52f8210afc 100644
--- a/docs/developer/agentic/overview.mdx
+++ b/docs/developer/agentic/overview.mdx
@@ -26,7 +26,7 @@ Spree ships first-class tooling for AI-assisted development. Whether you use Cla
llms.txt, per-page Markdown, and the `@spree/docs` npm package for fast local reads.
</Card>
<Card title="Spree CLI" icon="square-terminal" href="/developer/cli/quickstart">
- A predictable command surface (`spree dev`, `spree generate`, `spree migrate`, `spree upgrade`) that agents can drive end-to-end.
+ A predictable command surface (`spree dev`, `spree generate`, `spree migrate`) plus `spree api` — call the Admin API directly to inspect and drive the store, with zero-config credentials in local dev. Agents debug and act end-to-end.
</Card>
</CardGroup>
diff --git a/docs/developer/cli/admin-api.mdx b/docs/developer/cli/admin-api.mdx
index db4c129af1..ee53ba4adc 100644
--- a/docs/developer/cli/admin-api.mdx
+++ b/docs/developer/cli/admin-api.mdx
@@ -1,7 +1,7 @@
---
title: "Call the Admin API from the CLI"
sidebarTitle: "Admin API"
-description: "Use spree api to call the Spree Admin API with gh api-style generic verbs, schema introspection, and zero-config credentials — built for scripts and AI agents."
+description: "Use spree api to call the Spree Admin API with generic get/post/patch/delete commands, 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.
@@ -77,7 +77,7 @@ spree api get /products --fields name --expand variants
### Output format
-Output is JSON on stdout, and it adapts to where it goes (like `gh` and `stripe`):
+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).
diff --git a/docs/developer/cli/quickstart.mdx b/docs/developer/cli/quickstart.mdx
index e4d502bcd6..ca4391458f 100644
--- a/docs/developer/cli/quickstart.mdx
+++ b/docs/developer/cli/quickstart.mdx
@@ -1,10 +1,22 @@
---
title: Spree CLI
sidebarTitle: Overview
-description: Install and use the @spree/cli to scaffold, run, build, migrate, and upgrade Docker-based Spree Commerce projects from the command line.
+description: Install and use the @spree/cli to scaffold, run, build, and migrate Spree projects — and call the Admin API directly from the command line.
---
-The Spree CLI (`@spree/cli`) manages Docker-based Spree projects created with [create-spree-app](/developer/create-spree-app/quickstart).
+The Spree CLI (`@spree/cli`) does two things from your terminal:
+
+1. **Manages your Spree project** — boot the Docker stack, run generators and migrations, tail logs, open a console, upgrade versions.
+2. **Calls the Admin API** — generic `get`/`post`/`patch`/`delete` commands to read, write, and explore your store's data, with zero-config credentials in local dev. See [Admin API from the CLI](/developer/cli/admin-api).
+
+```bash
+spree dev # boot the project
+spree api get /orders -q status_eq=complete --limit 10 # query the Admin API
+spree api post /products -d '{"name":"Classic Tee"}' # create a resource
+spree api endpoints --search refund # discover endpoints, offline
+```
+
+The `spree api` commands work against any Spree 5.5+ instance and are built for both humans and AI agents — see the dedicated [Admin API from the CLI](/developer/cli/admin-api) guide. The rest of this page covers project management.
## Installation
@@ -176,7 +188,7 @@ spree api-key revoke <id> # Revoke a key
### `spree api`
-Call the Admin API with `gh api`-style generic verbs — zero-config inside a project (a read-only key is minted on first use), env vars or profiles for remote stores. See [Admin API from the CLI](/developer/cli/admin-api) for the full guide.
+Call the Admin API with generic `get`/`post`/`patch`/`delete` commands — zero-config inside a project (a read-only key is minted on first use), env vars or profiles for remote stores. See [Admin API from the CLI](/developer/cli/admin-api) for the full guide.
```bash
spree api get /products -q status_eq=active --limit 10
diff --git a/packages/cli/.changeset/admin-api-commands.md b/packages/cli/.changeset/admin-api-commands.md
index 0aececbdeb..940fc2fd26 100644
--- a/packages/cli/.changeset/admin-api-commands.md
+++ b/packages/cli/.changeset/admin-api-commands.md
@@ -2,7 +2,7 @@
"@spree/cli": minor
---
-New `spree api` and `spree auth` command groups — a gh api-style Admin API client built into the CLI:
+New `spree api` and `spree auth` command groups — a generic Admin API client (`get`/`post`/`patch`/`delete`) built into the CLI:
- `spree api get|post|patch|delete <path>` — generic verbs with Ransack `-q` filters, `--sort`/`--page`/`--limit`/`--expand`/`--fields`, and JSON bodies from inline/`@file`/stdin
- `spree api endpoints` / `spree api schema` — offline schema introspection over a bundled OpenAPI snapshot, including each endpoint's required scope
diff --git a/packages/cli/README.md b/packages/cli/README.md
index fd0eb84ba8..0339f81c1c 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -137,7 +137,7 @@ spree api-key revoke pk_abc123def456...
### `spree api`
-Call the Admin API directly with `gh api`-style generic verbs. Works against any Spree 5.5+ instance — inside a project it self-provisions a **read-only** key via the dev stack on first use (saved to `.spree/credentials.json`, gitignored). For other servers set `SPREE_API_KEY` (the host defaults to `http://localhost:3000`; add `SPREE_BASE_URL` for a remote store) or save a profile with `spree auth login`.
+Call the Admin API directly with generic `get`/`post`/`patch`/`delete` commands. Works against any Spree 5.5+ instance — inside a project it self-provisions a **read-only** key via the dev stack on first use (saved to `.spree/credentials.json`, gitignored). For other servers set `SPREE_API_KEY` (the host defaults to `http://localhost:3000`; add `SPREE_BASE_URL` for a remote store) or save a profile with `spree auth login`.
```bash
spree api get /products -q status_eq=active --sort -created_at --limit 10
diff --git a/packages/cli/src/api/body.ts b/packages/cli/src/api/body.ts
index ce61d86a6e..bceed1a221 100644
--- a/packages/cli/src/api/body.ts
+++ b/packages/cli/src/api/body.ts
@@ -5,7 +5,7 @@ import pc from 'picocolors'
export const NO_BODY = Symbol('no-body')
/**
- * Reads the request body for write verbs, gh-api style:
+ * Reads the request body for write verbs via the `-d` flag:
* -d '{"name":"Tee"}' inline JSON
* -d @payload.json from a file
* -d - from stdin
diff --git a/packages/cli/src/api/output.ts b/packages/cli/src/api/output.ts
index a95fe07fcf..547d2b7cea 100644
--- a/packages/cli/src/api/output.ts
+++ b/packages/cli/src/api/output.ts
@@ -9,9 +9,9 @@ export type OutputFormat = 'json' | 'table'
* Prints an API result. JSON is the default; `--format table` renders
* collections for humans.
*
- * JSON adapts to the destination, like `gh`/`stripe`: a terminal gets
- * indented, syntax-colored output; a pipe or file gets compact, uncolored
- * JSON so it stays fast and `jq`-clean (color codes would corrupt it).
+ * JSON adapts to the destination: a terminal gets indented, syntax-colored
+ * output; a pipe or file gets compact, uncolored JSON so it stays fast and
+ * `jq`-clean (color codes would corrupt it).
*/
export function printResult(result: unknown, format: OutputFormat = 'json'): void {
if (result === undefined || result === null) return
diff --git a/packages/cli/src/commands/api.ts b/packages/cli/src/commands/api.ts
index 996e5ca094..022c2e89a7 100644
--- a/packages/cli/src/commands/api.ts
+++ b/packages/cli/src/commands/api.ts
@@ -72,7 +72,7 @@ async function clientFor(
export function registerApiCommand(program: Command): void {
const api = program
.command('api')
- .description('Call the Admin API directly (gh api-style generic verbs)')
+ .description('Call the Admin API directly (generic get/post/patch/delete)')
// Discovery pointers — shown on `spree api --help` and after an unknown
// subcommand (the global showHelpAfterError prints help on usage errors).
diff --git a/packages/cli/src/commands/completion.ts b/packages/cli/src/commands/completion.ts
index 2037bb20b1..06002fa68c 100644
--- a/packages/cli/src/commands/completion.ts
+++ b/packages/cli/src/commands/completion.ts
@@ -4,11 +4,11 @@ import type { Command } from 'commander'
import RESOURCE_PATHS from '../generated/resource-paths.json' with { type: 'json' }
/**
- * Shell completion, following the `gh`/`kubectl` architecture: `spree
- * completion <shell>` prints a static script that, on Tab, calls a hidden
- * `spree __complete <words...>` subcommand. The resolver reads the bundled
- * OpenAPI snapshot (offline — no server, no network), so it can suggest live
- * resource paths, verbs, Ransack predicates, and scopes.
+ * Shell completion via the standard static-script-plus-hidden-subcommand
+ * pattern: `spree completion <shell>` prints a static script that, on Tab,
+ * calls a hidden `spree __complete <words...>` subcommand. The resolver reads
+ * the bundled OpenAPI snapshot (offline — no server, no network), so it can
+ * suggest live resource paths, verbs, Ransack predicates, and scopes.
*/
const SHELLS = ['bash', 'zsh', 'fish'] as const