@spree/cli 1.1.0 → 2.0.0-beta

package/README.md

@@ -1,72 +1,195 @@
-# Spree CLI
+# @spree/cli
 
-Spree CLI is a tool that makes it easy to bootstrap a new Spree project.
-It provides an interactive process for configuring Spree backend (running in Dockerized, Hybrid or Native mode) and a selection of available frontends.
+CLI for managing [Spree Commerce](https://spreecommerce.org) projects.
 
-## Dependencies
+Automatically included in projects created with [`create-spree-app`](https://www.npmjs.com/package/create-spree-app). Can also be installed standalone.
 
-Node 14+ is required to run the CLI. Depending on the chosen Spree setup, you will have to install different dependencies first:
+## Installation
 
-### Spree (dockerized)
-- docker >= 20.0
-- docker-compose
+Already included when you scaffold a project with `create-spree-app`. To install separately:
 
-### Spree (no docker)
-- ruby = 3.2.0
-- vips >= 8.6
-- gpg
-- psql
-- redis
+```bash
+npm install @spree/cli
+```
+
+Or run directly with npx:
+
+```bash
+npx @spree/cli <command>
+```
+
+Or install globally:
+
+```bash
+npm install -g @spree/cli
+spree <command>
+```
+
+## Commands
+
+Run these from your Spree project directory.
+
+### `spree dev`
+
+Start Docker services, print connection info, and stream web server logs.
+
+```bash
+spree dev
+```
+
+```
+╭ Spree Commerce ─────────────────────╮
+│                                     │
+│  Admin Dashboard                    │
+│    http://localhost:3000/admin       │
+│    Email:    spree@example.com      │
+│    Password: spree123               │
+│                                     │
+│  Store API                          │
+│    http://localhost:3000/api/v3/store│
+│                                     │
+╰─────────────────────────────────────╯
+```
+
+Press `Ctrl+C` to stop streaming logs (services keep running).
+
+### `spree stop`
+
+Stop all running services.
+
+```bash
+spree stop
+```
+
+### `spree update`
 
-### Spree (hybrid)
-- docker >= 20.0
-- docker-compose
-- ruby = 3.2.0
-- vips >= 8.6
-- redis (only needed for running rspec tests)
+Pull the latest Spree Docker image and recreate containers. Database migrations run automatically on startup via `db:prepare`.
 
-### Vue Storefront
-- node >= 14.15 <= 14.19
-- yarn
+```bash
+spree update
+```
+
+To pin a specific version, edit `SPREE_VERSION_TAG` in your `.env` file:
 
-### Next.js Commerce
-- node >= 13.0
-- yarn
+```
+SPREE_VERSION_TAG=5.4
+```
 
-## Usage
+### `spree logs [service]`
 
-To get started, simply run the following command in your terminal:
+Stream logs from a service. Defaults to `web`.
 
 ```bash
-npx @spree/cli new app
+spree logs          # web server logs
+spree logs worker   # background job logs
 ```
 
-This will launch the interactive process that will guide you through the process of setting up a new Spree-based store.
+### `spree console`
+
+Open an interactive Rails console inside the running container.
 
-In order to start the already generated app, navigate to your project's folder and run the following command:
 ```bash
-npx @spree/cli start app
+spree console
 ```
-Happy hacking!
 
-## Troubleshooting
+### `spree user create`
+
+Create an admin user. Prompts interactively for email and password, or accepts flags for scripting.
 
-### 1. NextJS storefront doesn't start properly
-If the Storefront doesn't start you need to relaunch server manually.
-To do so you should navigate to `/integration` folder inside created project and type `yarn dev` into console.
+```bash
+# Interactive
+spree user create
 
-### 2. NextJS storefront stops during launch
+# Non-interactive
+spree user create --email admin@example.com --password secret123
+```
 
-In case if the server is randomly stopping during launch it is advised to stop it (for example with `ctrl + c`) and repeat steps mentioned above.
+The user is automatically assigned the `admin` role on the default store.
 
+### `spree api-key create`
 
-If you have encountered any other problem with NextJS you can also refer to NextJs docs: https://github.com/vercel/commerce
+Create a Store API (publishable) or Admin API (secret) key. Prompts interactively for name and type, or accepts flags.
 
+```bash
+# Interactive
+spree api-key create
+
+# Non-interactive
+spree api-key create --name "My Storefront" --type publishable
+spree api-key create --name "Admin Integration" --type secret
+```
+
+**Important:** Secret key tokens are displayed only once at creation time and cannot be retrieved later. Save them immediately.
+
+### `spree api-key list`
+
+List all API keys for the default store with their name, type, token/prefix, creation date, and status.
+
+```bash
+spree api-key list
+```
+
+```
+  Name                      Type           Token                          Created            Status
+  ────────────────────────────────────────────────────────────────────────────────────────────────
+  My Storefront             publishable    pk_abc123def456...             2025-01-15 10:30   active
+  Admin Integration         secret         sk_xyz789qwe...               2025-01-15 10:35   active
+```
+
+### `spree api-key revoke`
+
+Revoke an API key by its token (publishable) or token prefix (secret).
+
+```bash
+spree api-key revoke pk_abc123def456...
+```
+
+### `spree seed`
+
+Run database seeds.
+
+```bash
+spree seed
+```
+
+### `spree sample-data`
+
+Load sample products, categories, customers, and images.
+
+```bash
+spree sample-data
+```
+
+## How It Works
+
+The CLI detects your project by looking for `docker-compose.yml` in the current directory. All commands execute via `docker compose` against the running Spree containers.
+
+- **Port** is read from `SPREE_PORT` in your `.env` file (default: `3000`)
+- **User and API key commands** run Ruby scripts via `docker compose exec web bin/rails runner`
+- **Service commands** (`dev`, `stop`, `update`) are thin wrappers around `docker compose`
+
+## Using with npm scripts
+
+Projects created with `create-spree-app` include convenience scripts in `package.json`:
+
+```bash
+npm run dev             # spree dev
+npm run stop            # spree stop
+npm run update          # spree update
+npm run logs            # spree logs
+npm run logs:worker     # spree logs worker
+npm run console         # spree console
+npm run seed            # spree seed
+npm run load-sample-data # spree sample-data
+```
 
-## Overview
+## Learn More
 
-This repository contains CLI to integrate Spree and storefront of your choice
+- [Spree Documentation](https://docs.spreecommerce.org)
+- [Store API Reference](https://docs.spreecommerce.org/api-reference/store)
+- [create-spree-app](https://www.npmjs.com/package/create-spree-app)
+- [Spree GitHub](https://github.com/spree/spree)
 
-This repository is being developed and maintained by [Upside](https://upsidelab.io)
+## License
 
-<a href="https://upsidelab.io"><img src="https://user-images.githubusercontent.com/6420475/141106487-333774a5-04b2-46a4-8367-7cb11e46906e.png" height="100px" /></a>
+MIT