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
Make Spree CLI more discoverable; drop "gh-style" phrasing
Damian Legawiecbef515dadaba
diff --git a/README.md b/README.mdindex 59e90aabb2..8ffbad6f0f 100755--- a/README.md+++ b/README.md@@ -54,6 +54,19 @@ npx skills add spree/agent-skillsThen 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.mdxindex 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 formThe 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```jsondiff --git a/docs/api-reference/admin-api/introduction.mdx b/docs/api-reference/admin-api/introduction.mdxindex 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:```bashspree api get /orders -q status_eq=complete --limit 25diff --git a/docs/developer/agentic/overview.mdx b/docs/developer/agentic/overview.mdxindex 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 Clallms.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.mdxindex 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.mdxindex e4d502bcd6..ca4391458f 100644--- a/docs/developer/cli/quickstart.mdx+++ b/docs/developer/cli/quickstart.mdx@@ -1,10 +1,22 @@---title: Spree CLIsidebarTitle: 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.```bashspree api get /products -q status_eq=active --limit 10diff --git a/packages/cli/.changeset/admin-api-commands.md b/packages/cli/.changeset/admin-api-commands.mdindex 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 scopediff --git a/packages/cli/README.md b/packages/cli/README.mdindex 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`.```bashspree api get /products -q status_eq=active --sort -created_at --limit 10diff --git a/packages/cli/src/api/body.ts b/packages/cli/src/api/body.tsindex 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 stdindiff --git a/packages/cli/src/api/output.ts b/packages/cli/src/api/output.tsindex 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) returndiff --git a/packages/cli/src/commands/api.ts b/packages/cli/src/commands/api.tsindex 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.tsindex 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