# @ordergroove/smi-serve

`smi-serve` is a CLI tool to scaffold and run a local dev environment for Ordergroove's Subscription Manager templates.

## Installation

Before using `smi-serve`, ensure you have Node.js installed on your system. If not, you can download and install it from [nodejs.org](https://nodejs.org/). The smi-serve tool requires Node 22 or later.

## Getting started

To initialize the current directory for local Subscription Manager development, run `npx @ordergroove/smi-serve init`. This will authenticate you with Ordergroove, retrieve your current Subscription Manager assets, and start a dev server.

After initialization, you can restart the dev server with `npx @ordergroove/smi-serve`.

When you are ready to push your changes, run `npx @ordergroove/smi-serve push-theme` to deploy your changes to Ordergroove. If the theme you're pushing is live, your changes will be published immediately!

## Configuration file

This tool generates a `.ogrc.json` file to store authentication information. This file should not be committed to source control.

## Command reference

You can run each command with `npx @ordergroove/smi-serve [command]`, e.g. `npx @ordergroove/smi-serve init`.

To see all available commands and flags, run `npx @ordergroove/smi-serve --help`. For documentation specific to individual commands, run `npx @ordergroove/smi-serve [command] --help`.

### init

Initializes the current directory with the assets from your live Subscription Manager theme and starts a dev server. This only needs to be run when you need to retrieve the latest assets from Ordergroove; otherwise you can start the dev server directly with `npx @ordergroove/smi-serve serve`. To pull new assets, use the `pull-theme` command.

### serve

Starts a development server. This is the default command, so it can also be run by entering `npx @ordergroove/smi-serve`.

By default it will choose a random available port, but you can customize this with the `--port` flag.

### pull-theme

Presents you with a list of your Subscription Manager themes including your live theme. Selecting a theme will overwrite the files in your present working directory.

### push-theme

Publishes your template changes to your selected Subscription Manager theme. If the theme you're pushing is your live theme, your changes will be published to your live site immediately! You can add the -y flag to automatically agree to the confirmation prompt.

### select-merchant

If you have access to multiple merchants, this lets you select a new merchant to be used by the other commands. This can be useful if you manage multiple merchant accounts.

## FAQs

### How do I run commands against Ordergroove's staging environment?

You can use the flag `--env staging` to make requests against Ordergroove's staging environment. For example, run `npx @ordergroove/smi-serve init --env staging` to initialize with assets from staging.

Keep in mind that if you use this flag, _every command_ you run must also include it.

### How do I integrate with source control?

Once you run the `init` command, you can initialize the folder as a Git repository with `git init` and push to the source control provider of your choice. When you are ready to deploy the changes, run `npx @ordergroove/smi-serve push-theme`.

Make sure to commit the autogenerated `.gitignore`, which prevents you from committing the `.ogrc.json` file to source control. The `ogrc` file contains authentication tokens and should not be committed.

### How do I merge in updates that have been made via the Subscription Manager editor in RC3?

Ordergroove regularly makes updates to its Subscription Manager templates to fix bugs and add new features. To compare the latest changes with your current template files, first initialize the repo with a source control provider like Git and commit your current template files. You can then re-run the `init` command with the `-f` flag to overwrite your files with the latest Subscription Manager template. Use Git's diff tools to compare what has changed and add back any customizations as necessary.

## Limitations

- Windows is not fully supported, though most functionality should work.
- SSO users and My Organization admins are not currently supported.