Swell CLI is a command-line interface that helps you create and work with apps, themes, and storefronts. This reference outlines the available commands.

Setup

To get started, install the CLI using a Node.js package manager.

Requirements

Install Swell CLI
npm install -g @swell/cli

Authentication

Start with commands to login and switch between Swell stores. App-related commands will automatically target the current store/environment based on your authentication.

login

Login to your Swell user account. If you are not already logged in, this command will open your browser to the Swell Admin login page, otherwise, it will show you the stores you still have available for logging in to.

swell login [--store <store>] [--force]

Flags

  • -s, --store: specific store to log in to
  • -f, --force: show all available stores and switch if already logged in

logout

Log out of all stores available in your current session.

swell logout [--local]

Flags

  • --local: clear local authentication data

switch

Switch your current default store.

If you have access to multiple stores, this command will define the store that all other commands will apply to by default.

swell switch [store-id]

Arguments

  • store-id: the store id you want to switch to

app

Manage a Swell app.

swell app [command]

Commands

  • swell app init: initialize an app in the current directory with a default config file and folder structure
  • swell app push: push configuration files to a development store
  • swell app install: install an app in another store environment
  • swell app watch: watch for local changes and push configuration files to a development store
  • swell app dev: run an app in dev mode from your local machine
  • swell app frontend dev: run a frontend app in dev mode from your local machine
  • swell app frontend deploy: push and deploy frontend files to your Swell app
  • swell app version: increment the version of an app
  • swell app release: release a new version of your an app for publishing to the App Store
  • swell app info: show information about your Swell app

app init

Initialize an app in the current directory with the default config file and folder structure.

swell app init [--yes]

Flags

  • -y, --yes: skip prompts and accept defaults

app push

Push all app configurations, a specific file, or a specific configuration type to an app in your store's test environment. If the app does not exist yet, it will be created and its global ID saved to a .swellrc file.

  • If no file is specified, all configuration files will be pushed to the store. This includes the app icon (assets/icon.png) and swell.json.
  • If a file is specified, only that file will be pushed to the store.
  • If a directory is specified, only files in that directory will be pushed.

App configuration directories

  • assets/
  • content/
  • frontend/
  • functions/
  • models/
  • notifications/
  • settings/
  • webhooks/
swell app push [file-path] [--app-path <path>]

Arguments

  • file-path relative path to a configuration file or directory to push

Flags

  • --app-path: path to the app directory, defaults to the current directory

Examples

swell app push

swell app push -f content

swell app push -f models/products.json

app install

Install an existing app in another store environment.

  • Without a version specified, install the latest version of the app.
  • Without a store specified, install the app in the Live environment of the current store.
swell app install [--app-path <path>] [-s <store>] [-e <env>] [-v <version>]

Flags

  • -v, --version: version of the app to install, defaults to latest
  • -s, --store: target store id to install the app
  • -e, --env: target environment to install the app, defaults to live
  • --app-path: path to the app directory, defaults to the current directory

Examples

swell install

swell install -v 3.2.7

swell install -v 1.0.0 -s my-store-id

swell install -v 1.0.0 -s another-store --env test

app watch

Watch for changes and push app configurations. Watches configuration files including functions, and automatically pushes to the remote store.

  • Optionally synchronize all configs before watching.
swell app watch [--app-path <path>] [-a]

Flags

  • -a, sync-all: synchronize all app configurations on file change
  • --app-path: path to the app directory, defaults to the current directory

Examples

swell app watch

swell app watch -a

swell app watch --sync-all

app dev

Run an app in dev mode from your local machine.

swell app dev

This command is an alias for swell app frontend dev. See below for more details.

app frontend dev

Run a frontend app in dev mode from your local machine. This will launch a web browser displaying app frontend changes and reload dynamically when files are saved.

swell app frontend dev
  [--port <port>]
  [--no-push]
  [--storefront-select]
  [--storefront-id <storefront-id>]

Flags

  • --port: override the default port
  • --no-push: skip pushing app files initially
  • --storefront-select: prompt to select a storefront to preview with
  • --storefront-id: identify a storefront to preview with

Examples

swell app frontend dev

swell app frontend dev --port 3000

swell app frontend dev --no-push

swell app frontend dev --storefront-id <id>

app frontend deploy

Push and deploy frontend files to your Swell app.

This creates a new build using the relevant command depending on your frontend framework. Once the build succeeds, this command will invoke Cloudflare Wrangler to upload build assets using your own Cloudflare account. Once complete, Swell will update the app's deployment URL and push the updated frontend files.

swell app frontend deploy
  [--force]
  [--storefront-select]
  [--storefront-id <storefront-id>]

Flags

  • --force: force push and build all frontend files
  • --storefront-select: prompt to select a storefront to preview deployment with
  • --storefront-id: identify a storefront to preview deployment with

Examples

swell app frontend deploy

swell app frontend deploy --force

swell app frontend deploy --storefront-id <id>

app version

Increment the version of your Swell app.

  • When executed without specifying nextversion, the command will display the current version of your app.
  • If a nextversion is provided, the command will validate and compute the version according to Semver rules.

The version change will be committed to the Git repository, if existing, using the provided message or a default similar to the tag, e.g. "v1.0.1". By default, it creates a Git tag for the specified version. You can disable this behavior by using the --git-tag=false option.

swell app version [nextversion] [--app-path <path>] [--git-tag] [-m <message>]

Arguments

  • nextversion: semver version or release type: <next.version>|major|premajor|minor|preminor|patch|prepatch|prerelease

Flags

  • -m, --message: description of the changes in this version
  • --no-git-tag: do not create a git tag for this version
  • --app-path: path to the app directory, defaults to the current directory

Examples

swell app version

swell app version patch

swell app version 1.0.0 -m "First release"

app release

Release a new version of your an app for publishing to the App Store. A version may already be created, using swell app version, or the command will prompt you to create a new version record.

swell app release [version]
  [-y]
  [-m <message>]
  [--release-notes <file-path>]
  [--amend]
  [--not-supported]
  [--no-git-tag]

Arguments

  • version: optional semver version to release, will use the current latest version if omitted

Flags

  • -y, --yes: skip prompts and accept defaults
  • -m, --message: brief description of the changes in this version
  • --release-notes: relative path to a file containing release notes
  • --amend: amend the description or release notes of an existing release
  • --not-supported: indicates the version is not officially supported by the developer
  • --no-git-tag: do not create a git tag for this version

Examples

swell app release

swell app release 2.0.0

swell app release 2.0.0 --amend --release-notes ./releases/v2.0.0.md

swell app release 2.0.0 -y

app info

Show information about your Swell app.

The command shows the latest information about your app including the name, description, version, public ID, test store, and more. If the versions argument is passed, it will output all versions of the app instead.

swell app info [versions] [--app-path <path>]

Arguments

  • versions: list all app versions

Flags

  • --app-path: path to the app directory, defaults to the current directory

Examples

swell app info

swell app info versions

theme

Manage a Swell storefront theme.

swell theme [command]

Commands

  • swell theme init: initialize a storefront theme in the current directory with the default config file and folder structure
  • swell theme pull: download a theme from a Swell storefront
  • swell theme push: upload local theme changes to a Swell storefront
  • swell theme dev: start a proxy to preview local theme changes

If you're developing a storefront app and want to preview theme changes along with your local app instance, see the swell app frontend dev command.

theme init

Initialize a storefront theme in the current directory with the default config file and folder structure.

swell theme init [--yes]

Flags

  • -y, --yes: skip prompts and accept defaults

theme pull

Download a theme from a Swell storefront.

If used inside the directory of a local Swell theme, this command will prompt to override existing files and remove deleted files. Otherwise, it will create a new directory containing all remote files.

swell theme pull [app-id] [target-path]
  [-e <environment>]
  [--force]
  [--storefront-select]
  [--storefront-id <storefront-id>]
  [--sync-app]

Arguments

  • app-id: theme app id to pull
  • target-path: path to download theme files into

Flags

  • -e, --env: target environment to pull from, defaults to live
  • --force: force pull all theme files, overwriting existing files
  • --storefront-select: prompt to select a storefront to pull theme files from
  • --storefront-id: identify a storefront to pull theme files from
  • --sync-app: pull app files in addition to theme files

Examples

swell theme pull

swell theme pull sunrise

swell theme pull sunrise sunrise-theme

swell theme pull --storefront-select

swell theme pull --force

theme push

Upload local theme changes to a Swell storefront.

swell theme push [file-path]
  [-e <environment>]
  [--force]
  [--storefront-select]
  [--storefront-id <storefront-id>]
  [--sync-app]

Arguments

  • file-path: target file or directory to push, defaults to the current directly

Flags

  • -e, --env: target environment to push to, defaults to live
  • --force: force push all theme files, overwriting remote files
  • --storefront-select: prompt to select a storefront to push theme files to
  • --storefront-id: identify a storefront to push theme files to
  • --sync-app: push app files in addition to theme files

Examples

swell theme push

swell theme push theme/sections

swell theme push sunrise sunrise-theme

swell theme push --storefront-select

swell theme push --force

theme dev

Start a proxy to preview local theme changes. This will launch a web browser displaying your theme changes and reload dynamically when files are saved.

An npm bundle script can be defined in order to automatically run a bundle process using the `--bundle` flag.

Use the --local flag to connect to a local storefront app, initiated by the swell app frontend dev command in order to develop a theme along with a a custom storefront app in the same environment.

swell theme dev
  [-e <environment>]
  [--bundle]
  [--local]
  [--force]
  [--no-push]
  [--storefront-select]
  [--storefront-id <storefront-id>]

Flags

  • -e, --env: target environment to push to, defaults to live
  • --bundle: automatically bundle assets, if configured
  • --local: connect to a running local storefront app dev server
  • --force: force push all theme files, overwriting remote files
  • --no-push: skip pushing theme files initially
  • --storefront-select: prompt to select a storefront to push theme files to
  • --storefront-id: identify a storefront to push theme files to
  • --sync-app: push app files in addition to theme files

create

Scaffold apps, models, functions, and notifications.

swell create [command]

Commands

  • swell create app: initialize an app with config file and folder structure
  • swell create model: initialize a data model config file with properties in the models folder
  • swell create content: initialize a content UI model config file with properties in the content folder
  • swell create function: initialize a functions script in JavaScript or TypeScript
  • swell create notification: initialize notification files and configuration with properties in the notifications folder

While create commands are useful, you can manually create configuration files instead.

create app

Initialize an app with swell.json file and folder structure.

If npm or yarn are available, initiate a package with @swell/app-types and tsconfig.json. By default, apps have full access to store data. Edit swell.json to narrow down permissions before publishing an app.

swell app create [app-id] [--pkg=<pkg>] [--yes]

Arguments

  • app-id: id of the app to create

Flags

  • -p, --pkg: package manager used to install default dependencies, one of npm, yarn, none, defaults to npm
  • -y, --yes: skip prompts and accept defaults, overwriting existing files, should only be used with [app-id] argument

Examples

swell create app

swell create app my_app

swell create app my_app -y

swell create app -p yarn

create model

Initialize a data model config file with properties in the models folder.

CLI will prompt for values when flags are not present.

swell create model [collection]
  [-l <label>]
  [-d <description>]
  [-f <fields>]
  [-e <events>]
  [--overwrite]
  [--app-path <app-path>]

Arguments

  • collection: collection to create or apply to, i.e. products

Flags

  • -l, --label: data model label, i.e. Products
  • -d, --description: data model description
  • -e, --events: list of data model events delimited by commas, defaults to created,updated,deleted
  • -f, --fields: list of data model fields delimited by commas, in the format of field_name:type
  • --overwrite: overwrite existing data model configuration, if existing
  • --app-path: path to the app directory, defaults to the current directory

Examples

swell create model

swell create model visitors -e created,updated,deleted

swell create model visitors \
  --fields first_name:string,last_name:string,photo:file,visit_count:int,visits:link

swell create model visitors \
  -f first_name:string,last_ame:string,photo:file,visit_count:int,visits:link \
  -d "Visitors" \
  -e created,updated,deleted,converted
  --overwrite

create content

Initialize a content UI model config file with properties in the content folder.

CLI will prompt for values when flags are not present.

swell create content [collection]
  [-l <label>]
  [-d <description>]
  [-f <fields>]
  [-v <views>]
  [--overwrite]
  [--app-path <app-path>]

Arguments

  • collection: collection to create or apply to, i.e. products

Flags

  • -l, --label: content model label, i.e. Products
  • -d, --description: content model description
  • -f, --fields: list of content fields delimited by commas, in the format of field_name:type
  • -v, --views: list of content views delimited by commas, i.e. list,edit,new
  • --overwrite: overwrite existing model configuration, if existing
  • --app-path: path to the app directory, defaults to the current directory

Examples

swell create content

swell create content visitors -v list,edit,new

swell create content visitors \
  -f name:short_text,description:long_text,verified:boolean,visitor_count:integer,photo:image,orders:collection

create function

Initialize a functions script in JavaScript or TypeScript.

CLI will prompt for values when flags are not present.

swell create function [function-name] [trigger]
  [-d <description>]
  [-e <model-events>]
  [-r public|private]
  [-s <cron-schedule>]
  [--overwrite]
  [--app-path <app-path>]

Arguments

  • function-name: function name, used in an http route if applicable
  • trigger function: trigger type, one of cron, model, route

Flags

  • -d, --description: function description
  • -e, --events: list of data model events used with model trigger, delimited by commas
  • -r, --route: access type used with route trigger, one of public, private, defaults to public
  • -s, --schedule: crontab value used with cron trigger
  • --overwrite: overwrite existing model configuration, if existing
  • --app-path: path to the app directory, defaults to the current directory

Examples

swell create function

swell create function orders-subscriptions-created.ts model --events order.created,subscription.created

swell create function get-frontend-data.ts route --route public

swell create function process-metrics.ts cron --schedule "0 0 * * *"

create notification

Initialize notification files and configuration with properties in the notifications folder.

CLI will prompt for values when flags are not present.

swell create notification [model] [name]
  [-d <description>]
  [-s <subject>]
  [-e <event-name>]
  [--admin]
  [--once]
  [--overwrite]
  [--app-path <value>]

Arguments

  • model: data model to trigger the notification by
  • name: internal name for the notification

Flags

  • -d, --description: notification description
  • -s, --subject: notification email subject
  • -e, --event: data model event to trigger the notification event, i.e. created
  • -a, --admin: indicate when the notification is sent to store admins only
  • -o, --once: indicate the notification should be sent only once when conditions are met, instead of repeating
  • --overwrite: overwrite existing model configuration, if existing
  • --app-path: path to the app directory, defaults to current directory

Examples

swell create notification

swell create notification subscriptions confirmed --event subscription.created --once \
  -d "Send a confirmation email when subscription is created" \
  -s "Your subscription has been confirmed"

swell create notification orders paid --event paid --admin

logs

swell app info swell app info versions

swell logs
  [--follow]
  [--search <search>]
  [--columns <date,request,data,status,time,app,env,ip,req>]
  [--number <number>]
  [--output <table|line>]
  [--before <before-date>]
  [--after <after-date>]
  [--app <app-id>]
  [--env <env>]
  [--type <api|function|webhook>]
  [--status <status>]
  [--pretty]

Flags

  • -f, --follow: stream logs in real time
  • -s, --search: search logs by keyword
  • -c, --columns: comma separated list of columns to display
    • date date the log entry was created
    • request log message describing the request
    • data request payload, if applicable
    • status http status code, if applicable
    • time request execution time in milliseconds, if applicable
    • app id of the app which initiated a request, if applicable
    • env environment of the store the log belongs to
    • ip ip address of the client which initiated the request, if applicable
    • req global request id, shared by function sub-requests
  • -n, --number: number of log lines to return, defaults to 100
  • -o, --output: style to display logs, one of table, line, defaults to line
  • --before: show logs created on before this date/time (utc)
  • --after: show logs created on or after this date/time (utc)
  • --app: filter logs by app id
  • --env: filter logs by environment, defaults to test
  • --type: filter logs by type, one of api, function, webhook
  • --status: filter logs by http status
  • --pretty: pretty print json data

Examples

swell logs

swell logs -f -p -n 10 -c date,req,data

swell logs -s accounts

swell logs -f --app honest_reviews

swell logs --after 2023-08-25T16:01:02.697Z -c date,request

swell logs --after 2023-08-27

whoami

Display the current logged-in user and available stores.

swell whoami

Contributing

Swell CLI is open source on Github. Contributions welcome!

Getting help

Visit our Github Discussions forum to connect with the Swell developer community and get help.