Welcome! This reference outlines the available commands of the Swell CLI. To get started, install the Alpha version:

Install Swell CLI alpha
npm install -g @swell/cli@alpha

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.

Usage

swell login [-s <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.

Usage

swell logout [--local]

Flags

  • --logout 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.

Usage

swell switch [store-id]

Arguments

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

Create

Scaffold apps, models, functions, and notifications.

Usage

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

The following create commands are optional. You may 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.

Usage

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.

Usage

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.

Usage

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.

Usage

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.

Usage

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

app

Manage a Swell app.

Usage

swell app [command]

Commands

  • 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 version: increment the version of an app

app push

Push configuration files to your Swell app.

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/
  • functions/
  • models/
  • notifications/
  • settings/
  • webhooks/

Usage

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.

Usage

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.

Usage

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 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.

Usage

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: description of the changes in this version
  • --git-tag: create a git tag for this version, defaults to true
  • --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 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.

Usage

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

logs

swell app info swell app info versions

Usage

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.

Usage

swell whoami