docs

Storefront CLI

How do you point a fresh Storefront Application V3 at your SCAYLE shop without editing .env and storefront.config.ts by hand? @scayle/storefront-cli reads your shop with its countries, currencies, and locales from the Admin API and writes them into your project. Its setup command scaffolds .env, replaces the countries in storefront.config.ts, and creates one translation file per country language. setup cms connects a CMS provider, and deploy starts a deployment to Storefront Hosting. The command is called sfcli. Run setup once for a new project or when you switch to another shop. Run setup cms when you choose a CMS provider. Run deploy from a terminal or a CI pipeline when you want a build on Storefront Hosting. A project that already has its countries configured by hand needs care before you run setup again, see Constraints and limits.

Run the CLI

You need Node.js 22 or later for the CLI itself, and a project that the CLI recognizes as a Storefront Application V3. The CLI looks for a directory that holds a package.json and a storefront.config.ts, starting in the directory you run it from and moving up through its parents. It reads the framework from the package.json in that directory, which needs "scayle": { "framework": "storefront-v3" }. The Storefront Application V3 ships both. Without the scayle.framework marker, the CLI does not recognize the project.

  1. Open a terminal in the root of your project.
  2. Run a command through pnpx, which runs the CLI without installing it:

You can also install the package and run the sfcli binary. Installed in the project, pnpm exec sfcli setup runs it. Installed globally with pnpm add --global @scayle/storefront-cli, sfcli setup runs it from any directory inside a project. Every example on this page uses pnpx.

To list the flags of a command, add --help, for example pnpx @scayle/storefront-cli setup --help. The -h flag does not print help. It is the short form of --no-header, which hides the startup banner.

Set up your shop

You need two values before you start. If you do not have them yet, run the command anyway, because it prompts for the tenant space and the token.

  • The tenant space: the part before .panel.scayle.cloud in your SCAYLE Panel URL.
  • An Admin API token with read permission on the Shops resource. Its restrictions on shops, companies, and IP ranges must not exclude your shop. Create one in the SCAYLE Panel under Settings ➜ General ➜ API Keys, at https://<tenant-space>.panel.scayle.cloud/settings/api-keys.

Steps:

  1. Run pnpx @scayle/storefront-cli setup from your project root. To skip those two prompts, pass the values as flags: --tenant-space=<tenant-space> --admin-api-token=<token>.
  2. Enter the tenant space and the Admin API token when prompted. The token prompt is masked and prints the Panel link.
  3. Answer Should all unsaved config be saved to file? with yes to keep the token in .scayle/config.json, as described in Saved values. The prompt appears only when the token is not saved yet or differs from the saved one, and --no-config-file and --non-interactive turn it off.
  4. Pick your shop from the list. Add --parent-shop-key=<shop-key> to skip this step.
  5. If .env or storefront.config.ts already exists, answer the conflict prompt. Yes overwrites the file. No, the default, writes a copy next to it, see Existing files.
  6. Answer the prompts that setup asks at the end. Press Enter on a credential prompt to skip it.

The CLI asks for these values at the end, and it skips a value that is already set in the .env it writes. Required explains what each variable sets.

  • STOREFRONT_SESSION_SECRET: The yes or no prompt Generate a random STOREFRONT_SESSION_SECRET for local development? creates a random value when you accept. Enter accepts, because yes is the default.
  • STOREFRONT_API_KEY: The Storefront API key. The prompt links to the Panel page that lists it.
  • STOREFRONT_OAUTH_CLIENT_ID and STOREFRONT_OAUTH_CLIENT_SECRET: The Customer Authentication API keys of your shop, with a link to the Panel page.

When the run worked, the terminal prints these headings in order, then Setup completed successfully! and the steps the CLI leaves to you. A run with --only-env skips the second and third heading:

The CLI prints the steps it leaves to you in two groups. The first group is required:

  • Create a local TLS certificate, because the dev server runs on HTTPS only. See Set up HTTPS.
  • Replace the checkout credentials. setup writes the placeholder text Add checkout user here (and the same for token and secret) into STOREFRONT_COUNTRIES_<KEY>_CHECKOUT_USER, _TOKEN, and _SECRET, so the application can start. <KEY> is the country code, see What setup writes. Ask your SCAYLE Account Manager for the real values before you use checkout.

The second group is optional: configure a CMS provider, start a Redis instance for sessions, and translate the files that setup copied.

Connect a CMS provider

The command supports four providers: amplience, contentful, contentstack, and storyblok. Each has its own flags, listed in setup cms flags.

Run it from your project root. For Contentful, for example:

In an interactive run, the command prompts for every missing required value and for --import-content-model (-i), which is true or false. To skip the prompts, pass the values:

The command checks that every required value is present before it changes a file. Then it writes CMS_PROVIDER and the provider variables into .env in the project root. A flag you leave out, or answer with a blank, does not overwrite an existing value. When --import-content-model is true, it then imports the content model from .scayle/cms/contentModel/<provider> in your project into your CMS. A failure during the import, such as a missing content model file, leaves the .env changes in place.

Run the import against a new, empty CMS space. A second run changes what already exists in your space as follows:

  • Storyblok and Contentstack skip items that exist and create the missing ones.
  • Contentful and Amplience overwrite the existing definitions.

The Amplience import runs dc-cli through pnpm exec, so @amplience/dc-cli must be installed in your project and pnpm must be on your PATH. dc-cli stores the personal access token in cleartext in ~/.amplience/dc-cli-config.json.

Deploy to Storefront Hosting

You need a CLI token from the SCAYLE Panel, an environment, and the environment variables set up in Storefront Hosting, see CLI Tokens and Deployment Actions.

Without --git-ref, the command deploys the commit that git rev-parse HEAD returns in the project it detects from your current directory. Storefront Hosting builds the ref from the Git repository you connected to the shop, so push the commit before you deploy. The command creates the deployment and checks its state every 15 seconds. At each check it prints the new build log lines. It fetches no logs after the final check, so the last lines of the build log can be missing. When the deployment succeeds and the environment has an internal domain, it prints Preview your Storefront on followed by the URL of the oldest one. For any other final status, it prints that status and exits with code 1.

What setup writes

setup writes three kinds of files, and --only-env limits it to .env. The .env file holds the values that differ per shop, and storefront.config.ts reads them through process.env. The CLI never writes the tenant space, the shop key, or the shop country IDs into storefront.config.ts.

FileWhat setup writes
.envStarts from .env.example, not from your current .env. Sets STOREFRONT_TENANT_SPACE and STOREFRONT_SHOP_KEY, and writes OTEL_SERVICE_NAME as storefront. Adds STOREFRONT_COUNTRIES_<KEY>_SHOP_COUNTRY_ID and the three _CHECKOUT_ variables for each active country and one empty STOREFRONT_COUNTRIES_<KEY>_SUBSCRIPTION_ENABLED variable per active country, and removes the example blocks for DE, US, and AT. Comments out HTTPS_KEY and HTTPS_CERT when they are empty. Fills the credentials that you answer in the prompts.
storefront.config.tsReplaces the countries array with one entry per active country. A country that is already in the file keeps its publicFields. Leaves every other key as it is.
src/i18n/locales/<locale>.jsonCreates one file per active country, named after the default language of the country, for example de_DE.json.

<KEY> is the country code, for example DE. When your shop has more than one shop country for a country code, the language joins it, for example BE_FR and BE_NL. A shop country is active when it is active and not deleted in the Admin API. Inactive and deleted countries get no entries.

Each entry in countries looks like this for a country with the code DE:

  • name is the English name of the country.
  • locale is the default language of the shop country, written with a hyphen. The Storefront API identifies a shop country by this locale, so the CLI keeps it as the Admin API returns it.
  • path is the lowercase country code. When more than one shop country shares a country code, the language comes first, for example fr-be and nl-be.
  • isDefault is true for the first active country that the Admin API returns, and false for the others.

For each locale file, the CLI picks the source in this order. It copies a file in the same language when one exists in src/i18n/locales/, for example fr_FR.json for fr_BE. When the language has several files and no <language>_<LANGUAGE>.json, it takes the first one in alphabetical order. Without a same-language file, it copies en_GB.json. When en_GB.json is missing, setup prints a warning and creates no locale files. It prints a warning for every file it creates, so you can review the wording. The Storefront Application V3 loads every JSON file in that folder, so you register nothing. setup creates a file only for the default language of each country, not for the other languages the shop country supports.

Existing files

FileWithout --should-overrideWith --should-override
.envAsks. No writes the result to .env.new, or .env.new-1 and up when that exists.Rebuilds .env from .env.example and discards every value of your current .env, including credentials you entered before. The prompts ask for them again.
storefront.config.tsAsks. No copies the file to storefront.config.new.ts, or storefront.config.new-1.ts and up, and edits the copy.Edits storefront.config.ts in place.
Locale filesSkips a file that exists and prints a warning.Skips a file that exists and prints a warning.

setup requires storefront.config.ts, so that file always exists. The conflict prompt for it appears in every interactive run that uses neither --should-override nor --only-env. With --non-interactive, the prompt is skipped and the answer is no. A run without an existing .env writes .env directly and asks nothing.

Flags and configuration

setup flags

FlagRequiredDescription
--tenant-space, -tYesYour tenant space.
--admin-api-token, -aYesThe Admin API token. Needs read permission on the Shops resource. The CLI reads a saved value when you pass none, see Saved values.
--parent-shop-key, -pNoThe key of the shop to set up. Skips the shop prompt. The command aborts when that shop is inactive or deleted.
--should-override, -oNoOverwrites .env and storefront.config.ts without asking, see Existing files.
--only-env, -eNoWrites only .env. Skips storefront.config.ts and the translation files.

setup cms flags

Every provider accepts --import-content-model (-i, required, true or false). The prompt for a flag marked "when importing" appears only when that flag is true.

ProviderFlagsVariables written to .env
contentful--space-id, -s (required). --access-token (required, the Delivery API token). --preview-token (required). --management-token (when importing).CONTENTFUL_CMS_SPACE, CONTENTFUL_CMS_ACCESS_TOKEN, CONTENTFUL_CMS_PREVIEW_ACCESS_TOKEN, CONTENTFUL_CMS_MANAGEMENT_TOKEN
storyblok--space-id, -s (required). --access-token (required, a Preview or Public token). --personal-access-token, -p (when importing). --region, -r (eu, cn, us, ca, or ap, derived from the Space ID when you omit it, but a Space ID below 1,000,000 always resolves to eu, so pass cn for a China space).STORYBLOK_CMS_SPACE, STORYBLOK_CMS_ACCESS_TOKEN, STORYBLOK_CMS_PERSONAL_TOKEN, STORYBLOK_CMS_REGION
contentstack--api-key, -k (required). --delivery-token, -d (required). --preview-token, -p (required). --region, -r (required, one of na, eu, au, azure-na, azure-eu, gcp-na, gcp-eu). --environment, -e (required). --branch, -b (default main). --management-token, -m (when importing).CONTENTSTACK_CMS_STACK_API_KEY, CONTENTSTACK_CMS_DELIVERY_TOKEN, CONTENTSTACK_CMS_PREVIEW_ACCESS_TOKEN, CONTENTSTACK_CMS_ENVIRONMENT, CONTENTSTACK_CMS_REGION, CONTENTSTACK_CMS_BRANCH, CONTENTSTACK_CMS_MANAGEMENT_TOKEN
amplience--hub-name, -n (required, the hub name and not the hub ID). --hub-id (when importing). --personal-access-token, -p (when importing).AMPLIENCE_CMS_HUB_NAME, AMPLIENCE_CMS_HUB_ID, AMPLIENCE_CMS_PERSONAL_ACCESS_TOKEN

deploy flags

FlagRequiredEnvironment variableDescription
--tenant-space, -tYesSCAYLE_CLI_TENANT_SPACEYour tenant space.
--shop-key, -sYesSCAYLE_CLI_SHOP_KEYThe key of the shop you deploy.
--env-key, -eYesSCAYLE_CLI_ENV_KEYThe key of the environment you deploy to.
--deploy-tokenYesSCAYLE_CLI_DEPLOY_TOKENThe CLI token that authenticates against Storefront Hosting.
--git-ref, -gNoSCAYLE_CLI_GIT_REFThe Git ref to deploy. Defaults to the HEAD commit of the detected project and aborts with Required Git Reference not found. when none is found. The old name --git-rev still works and is deprecated.

Flags of every command

FlagEnvironment variableDescription
--no-header, -hNoneHides the startup banner.
--no-config-fileSCAYLE_CLI_NO_CONFIG_FILESkips the prompt that saves values to .scayle/config.json. The CLI still reads a config file that exists.
--non-interactiveSCAYLE_CLI_NON_INTERACTIVENever prompts. A required value that is missing aborts the command with an error. A prompt with a default takes it: the session secret is generated, a file conflict writes a copy, and the credential prompts are skipped with a warning. Also skips the config file prompt.
--log-levelNoneDefaults to info. Only debug and trace change anything, and they print verbose debug output.
--jsonNoneThe CLI framework adds it to every command. With setup, the output stays the same, so it has no use today.

Saved values

The CLI can keep your Admin API token and deploy token in a config file so you do not enter them again. It uses one file, never both:

  • .scayle/config.json in the directory you run the CLI from, when that file exists.
  • Otherwise ~/.scayle/config.json, when that file exists.

When neither file exists, the prompt Should all unsaved config be saved to file? creates .scayle/config.json in the current directory. The CLI never creates the file in your home directory. Create it yourself to share a token across projects.

The tokens sit under your tenant space:

A value you pass as a flag wins over a saved value. The key names are exact: a key such as adminApiToken is not read. The token is stored as plain text, and the Storefront Application V3 lists .scayle/config.json in its .gitignore. In CI, pass --no-config-file or --non-interactive to skip the save prompt.

Constraints and limits

Permanent

  • setup fetches one shop per run. To use more than one shop, run it again with another --parent-shop-key, and check the files first, because each run rewrites countries and builds .env from .env.example again.
  • setup writes only the default language of each shop country. Add the other languages by hand.

Known limitations

  • setup replaces the whole countries array in the file it edits, which is storefront.config.ts when you overwrite and the .new copy otherwise. Edits you made to a country, other than its publicFields, and countries you added are gone from that file after a run. The CLI matches a country to your publicFields by country code and locale, or by country code alone when the shop and your file each have one entry for it. Commit the file first and compare the result.
  • A country that is new to storefront.config.ts gets consentManagementRequired: false. Set it to true for every country that needs a consent banner.

Troubleshooting

does not contain a supported Storefront Application

Issue: The command prints The current directory '<path>' does not contain a supported Storefront Application. Aborting!

Possible causes:

  • You run the command outside the project.
  • The package.json of your project has no "scayle": { "framework": "storefront-v3" } entry, so the CLI does not recognize the project.
  • The project has no storefront.config.ts.

Solution:

  1. Change into the project root, or a folder below it, as described in Run the CLI.
  2. Add "scayle": { "framework": "storefront-v3" } to package.json.
  3. Restore storefront.config.ts.

Prevention: Keep the scayle entry in package.json when you edit it.

The Admin API rejects the token

Issue: The command stops with The Admin API token was rejected or The Admin API token has no access.

Possible causes:

  • The token is invalid, expired, or deleted. This is the first message.
  • The token lacks read permission on the Shops resource, or its restrictions on shops, companies, or IP ranges exclude your shop. This is the second message.
  • A saved value in .scayle/config.json is outdated, because the CLI uses it when you pass no flag.

Solution:

  1. Create or check the token in the SCAYLE Panel under Settings ➜ General ➜ API Keys.
  2. Pass the new token with --admin-api-token, or edit the saved value.

Prevention: Remove the saved value from .scayle/config.json when you delete the token.

No .env.example found

Issue: The step Creating the .env file fails with an error that contains No .env.example found. Run this command from your Storefront Application root.

Possible causes: The project has no .env.example in its root. The CLI looks in the project root it detected, not in the folder you ran it from.

Solution: Restore .env.example in the project root and run setup again.

Prevention: Keep .env.example in version control, because setup builds .env from it.

The shop does not appear in the list

Issue: The shop prompt does not list the shop you expect, or the command prints No shop entities found for tenant space <tenant-space>.

Possible causes:

  • The shop is inactive or deleted.
  • The shop has no country. The list shows only shops with at least one country.

Solution: Activate the shop and add a country in the SCAYLE Panel, then run setup again. When you know the shop key, pass --parent-shop-key.

A run with --non-interactive aborts

Issue: The command prints The --admin-api-token flag is required for this run but has no value and the CLI is running non-interactively. or the same for --tenant-space or --parent-shop-key.

Possible causes: --non-interactive never prompts, and setup needs the tenant space, the token, and the shop key. Only the token can come from a saved value.

Solution: Pass the missing flags, or save the token to .scayle/config.json first.

Prevention: In CI, pass every required flag.