Apps
Welcome! This reference outlines the available commands of the Swell CLI. To get started, install the Alpha version:
npm install -g @swell/cli@alpha
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 [-s <store>] [--force]
- -s, --store specific store to log in to
- -f, --force show all available stores and switch if already logged in
Log out of all stores available in your current session.
swell logout [--local]
- --logout clear local authentication data
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]
- store-id the store id you want to switch to
Scaffold apps, models, functions, and notifications.
swell create [command]
- 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.
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]
- app-id: id of the app to create
- -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
swell create app
swell create app my_app
swell create app my_app -y
swell create app -p yarn
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]
- collection: collection to create or apply to, i.e. products
- -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
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
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]
- collection: collection to create or apply to, i.e. products
- -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
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
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>]
- function-name function name, used in an http route if applicable
- trigger function trigger type, one of cron, model, route
- -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
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 * * *"
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>]
- model data model to trigger the notification by
- name internal name for the notification
- -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
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
Manage a Swell app.
swell app [command]
- 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
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/
swell app push [file-path] [--app-path <path>]
- file-path relative path to a configuration file or directory to push
- --app-path path to the app directory, defaults to the current directory
swell app push
swell app push -f content
swell app push -f models/products.json
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>]
- -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
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
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]
- -a, sync-all: synchronize all app configurations on file change
- --app-path: path to the app directory, defaults to the current directory
swell app watch
swell app watch -a
swell app watch --sync-all
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>]
- nextversion: semver version or release type: <next.version>|major|premajor|minor|preminor|patch|prepatch|prerelease
- -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
swell app version
swell app version patch
swell app version 1.0.0 -m "First release"
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>]
- versions: list all app versions
- --app-path: path to the app directory, defaults to the current directory
swell app info
swell app info versions
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]
- -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
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
Display the current logged-in user and available stores.
swell whoami