CLI Reference

The Serverless Cloud CLI is an auto-updating command-line interface (CLI) that provides a simple, unified interface to Serverless Cloud. The CLI has multiple modes to optimize the experience for different contexts:

• Cloud Shell: The interactive Cloud Shell allows developers to connect to their developer sandbox from their local IDE, auto sync code changes, stream logs, and run common commands and pre-defined scripts to manage their full-stack development workflow.
• Standard Mode: Standard mode allows developers to run commands from your terminal without having to open an interactive session. Login is still required.
• Headless Mode: Headless mode allows developers to run commands from CI/CD systems using an Access Token.

The CLI automatically updates to the latest version to ensure that users have access to the latest features and fixes. This includes auto-updates of the package locally installed in a project.

Current CLI Version:

PLEASE NOTE: The CLI requires Node.js v16 or higher. You can check your current Node.js version by running node -v.

Cloud Shell

The interactive Cloud Shell allows developers to connect to their developer sandbox from their local IDE, auto sync code changes, stream logs, and run common commands to manager their development workflow.

To enter the interactive Cloud Shell, run the cloud command from your terminal. If you do not have the @serverless/cloud NPM package installed globally, you can also run npx @serverless/cloud.

Additional flags can be passed to the cloud command to configure the behavior of the Cloud Shell.

• --seed: Seed data from your data.json file on initialization.
• --reseed: Enable automatic data reseeding when the data.json file is updated.
• --org: Overwrites the organization of the project in your current directory.
• --app: Overwrites the app of the project in your current directory.
• --template: Initiate a new project from a template in the templates repository. E.g. --template=sveltekit-ts.

To exit the interactive Cloud Shell, type exit.

dev

Starts the local development server in a child process, if a script named cloud:dev is defined in package.json.

share [NAME]

Deploys the code AND data from your developer sandbox to a preview stage named NAME. If no NAME is provided, a randomly generated name will be created for you.

A preview stage is an ephermeral stage that you can use to easily share your work with others. Preview stages allow you to create a stable snapshots of your developer sandbox so that you can get feedback while continuing to make changes to your own version.

If a script named cloud:build is defined in package.json, it will be run before deploying.

deploy [STAGE]

Deploys the code from your developer sandbox to the provided STAGE. If no STAGE is provided, it will prompt you to enter a STAGE.

A STAGE is a long-lived stage/environment that hosts your app. Common names for STAGEs are prod, staging, qa, and dev.

If a script named cloud:build is defined in package.json, it will be run before deploying.

delete [STAGE]

Deletes the stage named [STAGE]. Warning: this is a destructive action.

promote [from] [to]

Deploys code from one stage to another stage. If from and to are not provided, it will prompt you to enter the from and to stages.

import [FILENAME] [--overwrite]

Seeds data from the FILENAME in your local directory to your developer sandbox. If no FILENAME is provided, it will default to data.json. By default, the data will be merged with existing data. If you specify the -o or --overwrite flag, all data will be cleared and reseeded.

export [FILENAME] [--overwrite]

Exports data from your developer sandbox to a JSON file named FILENAME in your current working directoy. If no FILENAME is provided, it will default to data.json. If the FILENAME already exists, you can specify the -o or --overwrite flag to overwrite the existing file.

test [PATTERN] [--workers <n>]

Runs defined tests against your connected developer sandbox. Please note that this will use and (depending on your tests) potentially modify data in your developer sandbox. To run these tests on an isolated stage, exit the shell and run cloud test.

If [PATTERN] is specified, only test files that match the pattern will be run. The pattern is a regular expression that is matched against the test file path.

If --workers <n> is specified, up to <n> workers will be used to run tests in parallel. Note that for this to work, your tests must be independent of each other and not rely on any shared data.

install [PACKAGENAME]

Installs the specified npm package into your application, and syncs your developer sandbox once it's done. If you did not provide a package name, it'll simply install all your app's dependencies listed in package.json.

uninstall [PACKAGENAME]

Uninstalls the specified npm package from your application, and syncs your developer sandbox once it's done.

version

Displays the current running version of the CLI.

url

Displays the current URL of your developer sandbox.

open

Opens the dashboard to the current app in your default browser.

docs

Opens the Serverless Cloud documentation in your default browser.

quit / exit or Ctrl/Cmd+C

Terminates the interactive cloud shell and disconnects from your developer sandbox.

clear

Clears the terminal screen.

help

Displays a simple help screen that shows all the available commands and their options.

Standard Mode

Standard mode allows developers to run commands from your terminal without having to open an interactive session. Login is still required.

cloud login

Logs the user in via the browser

cloud logout

Logs the user out of the current session

cloud test

Deploys code from the current directory and run tests in an isolated stage. After tests are complete, the stage is automatically deleted.

cloud share [NAME]

Deploys the code AND data from your developer sandbox to a preview stage named NAME. If no NAME is provided, a randomly generated name will be created for you.

A preview stage is an ephermeral stage that you can use to easily share your work with others. Preview stages allow you to create a stable snapshots of your developer sandbox so that you can get feedback while continuing to make changes to your own version.

cloud deploy [STAGE]

Deploys the code from your local directory to the provided STAGE. If no STAGE is provided, it will prompt you for a STAGE name.

A STAGE is a long-lived stage/environment that hosts your app. Common names for STAGEs are prod, staging, qa, and dev.

cloud delete [STAGE]

Deletes the stage named [STAGE]. Warning: this is a destructive action.

cloud install [PACKAGENAME]

Installs the specified npm package into your application. If you did not provide a package name, it'll simply install all your app's dependencies listed in package.json.

cloud uninstall [PACKAGENAME]

Uninstalls the specified npm package from your application.

cloud clone [@ORG_NAME/APP_NAME/stage_NAME] [-overwrite]

Copies code AND data from stage_NAME of service APP_NAME of org ORG_NAME to your local directory and your developer sandbox. If ORG_NAME is not specified it will clone from the logged in organization. Note that you should have access to the given org name otherwise the operation fails. stage_NAME can specify either a stage (like prod or dev), or a preview stage. If your current directory is not empty, you can use the optional --overwrite (or -o) flag. If no APP_NAME is specified, it will default to the app in your current directory. If not stage_NAME is specified, it will display a list of available stage to choose from.

cloud promote [from] [to]

Deploys code from one stage to another stage. If from and to are not provided, it will prompt you to enter the from and to stages.

cloud run [script] [--stage <name>] [--test-stage] [-- npm-arguments [-- script-arguments]]

Runs the npm script cloud:<script> locally, with access to the selected stage. The script will have access to the selected stage's params, data, and storage.

By default the script runs with access to your developer sandbox. Use --stage <name> to use an existing stage.

Specifying --test-stage will create a temporary test stage, which will be deleted after the script completes.

You may pass additional arguments to npm by adding a double dash followed by the arguments, and another double dash to pass arguments to the script. For example cloud run migrate --stage staging -- --if-present -- script-argument --script-option will result in running npm run cloud:migrate --if-present -- script-argument --script-option using the environment from the staging stage.

cloud import [FILENAME] [--overwrite]

Seeds data from the FILENAME in your local directory to your developer sandbox. If no FILENAME is provided, it will default to data.json. By default, the data will be merged with existing data. If you specify the --overwrite flag, all data will be cleared and reseeded.

cloud export [FILENAME] [--overwrite]

Exports data from your developer sandbox to a JSON file named FILENAME in your current working directoy. If no FILENAME is provided, it will default to data.json. If the FILENAME already exists, you can specify the --overwrite flag to overwrite the existing file.

cloud version

Displays the running version of the CLI.

cloud url

Displays the current URL of your developer sandbox.

cloud open

Opens the dashboard to the current app in your default browser.

cloud docs

Opens the Serverless Cloud documentation in your default browser.

cloud help

Displays a help screen that shows all the available commands and their options.

Headless Mode

Headless mode allows developers to run commands from CI/CD systems using an Access Token. If the CLI detects a SERVERLESS_ACCESS_KEY environment variable and there is no active login, the CLI will run in headless mode.

The following commands are supported in headless mode:

cloud test [PATTERN] [--workers <n>]

Deploys code from the current directory and run tests in an isolated stage. After tests are complete, the stage is automatically terminated.

If [PATTERN] is specified, only test files that match the pattern will be run. The pattern is a regular expression that is matched against the test file path.

If --workers <n> is specified, up to <n> workers will be used to run tests in parallel. Note that for this to work, your tests must be independent of each other and not rely on any shared data.

cloud deploy {STAGE}

Deploys code from the local directory to the specified STAGE. STAGE is required.