CLI

The CLI helps you manage your SST apps.

Install

curl -fsSL https://ion.sst.dev/install | bash

Note

The CLI currently supports macOS, Linux, and WSL. Windows support is coming soon.

With a package manager

You can also use a package manager to install the CLI.

• macOS

  The CLI is available via a Homebrew Tap, and as downloadable binary in the releases.

  brew install sst/tap/sst
  
  # Upgrade
  brew upgrade sst

  You might have to run brew upgrade sst, before the update.

• Linux

  The CLI is available as downloadable binaries in the releases. Download the .deb or .rpm and install with sudo dpkg -i and sudo rpm -i.

  For Arch Linux, it’s available in the aur.

• Windows

  The CLI is available via Scoop, and as a downloadable binary in the releases.

  scoop bucket add sst https://github.com/sst/scoop-bucket.git
  scoop install sst
  
  # Upgrade
  scoop update sst

Usage

Once installed you can run the commands using.

sst [command]

The CLI takes a few global flags. For example, the deploy command takes the --stage flag

sst deploy --stage=production

Environment variables

You can access any environment variables set in the CLI in your sst.config.ts file. For example, running:

ENV_VAR=123 sst deploy

Will let you access ENV_VAR through process.env.ENV_VAR.

---

Global Flags

stage

Type string

Set the stage the CLI is running on.

sst [command] --stage=production

The stage is a string that is used to prefix the resources in your app. This allows you to have multiple environments of your app running in the same account.

Tip

Changing the stage will redeploy your app to a new stage with new resources. The old resources will still be around in the old stage.

If the stage is not passed in, then the CLI will:

1. Use the username on the local machine.
   • If the username is root, admin, prod, dev, production, then it will prompt for a stage name.
2. Store this in the .sst/stage file and reads from it in the future.

This stored stage is called your personal stage.

verbose

Type boolean

Enables verbose logging for the CLI output.

sst [command] --verbose

help

Type boolean

Prints help for the given command.

sst [command] --help

Or for the global help.

sst --help

Commands

init

sst init

Initialize a new project in the current directory. This will create a sst.config.ts and sst install your providers.

If this is run in a Next.js, Remix, Astro, or SvelteKit project, it’ll init SST in drop-in mode.

dev

sst dev [command]

Args

• command?

  The command to run

Flags

• silent boolean

  Do not output function invocation logs

Run your app in development mode. Optionally, pass in a command to start your frontend as well.

sst dev

You can also pass in a command to start your frontend with it.

sst dev next dev

To pass in a flag to your command, wrap it in quotes.

sst dev "next dev --turbo"

Dev mode does a few things:

1. Starts a local server
2. Watches your app config and re-deploys your changes
3. Run your functions Live
4. If you pass in a command, it’ll:
   • Load your linked resources in the environment
   • And run the command

Note

If you run sst dev with a command, it will not print your function logs.

If sst dev starts your frontend, it won’t print logs from your SST app. We do this to prevent your logs from being too noisy. To view your logs, you can run sst dev in a separate terminal.

Tip

You can start as many instances of sst dev in your app as you want.

Starting multiple instances of sst dev in the same project only starts a single server. Meaning that the second instance connects to the existing one.

This is different from SST v2, in that you needed to run sst dev and sst bind for your frontend.

deploy

sst deploy

Deploy your application. By default, it deploys to your personal stage.

Optionally, deploy your app to a specific stage.

sst deploy --stage=production

add

sst add <provider>

Args

• provider

  The provider to add.

Adds and installs the given provider. For example,

sst add aws

This command will:

1. Installs the package for the AWS provider.
2. Add aws to the globals in your sst.config.ts.
3. And, add it to your providers.

sst.config.ts

{
  providers: {
    aws: true
  }
}

You can use any provider listed in the Pulumi Registry. The name of a provider comes from the URL of the provider in the Pulumi Registry.

For example, https://www.pulumi.com/registry/packages/aws/ is the URL of the AWS Clasic provider. So the name of the provider here is aws.

Note

Running sst add aws above is the same as manually adding the provider to your config and running sst install.

By default, the latest version of the provider is installed. If you want to use a specific version, you can set it in your config.

sst.config.ts

{
  providers: {
    aws: {
      version: "6.27.0"
    }
  }
}

Tip

You’ll need to run sst install after you update the providers in your config.

install

sst install

Installs the providers in your sst.config.ts. You’ll need this command when:

1. You add a new provider to the providers or home in your config.
2. Or, when you want to install new providers after you git pull some changes.

Tip

The sst install command is similar to npm install.

Behind the scenes, it installs the packages for your providers and adds the providers to your globals.

If you don’t have a version specified for your providers in your sst.config.ts, it’ll install their latest versions.

secret

Subcommands

• set

• load

• remove

• list

Manage the secrets in your app defined with sst.Secret.

secret set

sst secret set <name> <value>

Args

• name

  The name of the secret.

• value

  The value of the secret.

Set the value of the secret.

The secrets are encrypted and stored in an S3 Bucket in your AWS account. They are also stored in the package of the functions using the secret.

Tip

If you are not running sst dev, you’ll need to sst deploy to apply the secret.

For example, set the sst.Secret called StripeSecret to 123456789.

sst secret set StripeSecret dev_123456789

Optionally, set the secret in a specific stage.

sst secret set StripeSecret prod_123456789 --stage=production

To set something like an RSA key, you can first save it to a file.

cat > tmp.txt <<EOF
-----BEGIN RSA PRIVATE KEY-----
MEgCQQCo9+BpMRYQ/dL3DS2CyJxRF+j6ctbT3/Qp84+KeFhnii7NT7fELilKUSnx
S30WAvQCCo2yU1orfgqr41mM70MBAgMBAAE=
-----END RSA PRIVATE KEY-----
EOF

Then set the secret from the file.

sst secret set Key -- "$(cat tmp.txt)"

And make sure to delete the temp file.

secret load

sst secret load <file>

Args

• file

  The file to load the secrets from.

Load all the secrets from a file and set them.

sst secret load ./secrets.env

The file needs to be in the dotenv or bash format of key-value pairs.

secrets.env

KEY_1=VALUE1
KEY_2=VALUE2

Optionally, set the secrets in a specific stage.

sst secret load ./prod.env --stage=production

secret remove

sst secret remove <name>

Args

• name

  The name of the secret.

Remove a secret.

For example, remove the sst.Secret called StripeSecret.

sst secret remove StripeSecret

Optionally, remove a secret in a specific stage.

sst secret remove StripeSecret --stage=production

secret list

sst secret list

Lists all the secrets.

Optionally, list the secrets in a specific stage.

sst secret list --stage=production

shell

sst shell [command]

Args

• command?

  A command to run.

Run a command with all the resources linked to the environment.

For example, you can run a Node script and use the JS SDK to access all the linked resources in your app.

sst.config.ts

const myMainBucket = new sst.aws.Bucket("MyMainBucket");
const myAdminBucket = new sst.aws.Bucket("MyAdminBucket");

new sst.aws.Nextjs("MyMainWeb", {
  link: [myMainBucket]
});

new sst.aws.Nextjs("MyAdminWeb", {
  link: [myAdminBucket]
});

Now if you run a script.

sst shell node my-script.js

It’ll have access to all the buckets from above.

my-script.js

import { Resource } from "sst";

console.log(Resource.MyMainBucket.name, Resource.MyAdminBucket.name);

If no command is passed in, it opens a shell session with the linked resources.

sst shell

This is useful if you want to run multiple commands, all while accessing the linked resources.

remove

sst remove

Removes your application. By default, it removes your personal stage.

Tip

The resources in your app are removed based on the removal setting in your sst.config.ts.

Optionally, remove your app from a specific stage.

sst remove --stage=production

unlock

sst unlock

When you run sst deploy, it acquires a lock on your state file to prevent concurrent deploys.

However, if something unexpectedly kills the sst deploy process, or if you manage to run sst deploy concurrently, the lock might not be released.

This should not usually happen, but it can prevent you from deploying. You can run sst unlock to release the lock.

version

sst version

Prints the current version of the CLI.

upgrade

sst upgrade [version]

Args

• version?

  A version to upgrade to.

Upgrade the CLI to the latest version. Or optionally, pass in a version to upgrade to.

sst upgrade 0.10

telemetry

Subcommands

• enable

• disable

Manage telemetry settings.

SST collects completely anonymous telemetry data about general usage. We track:

• Version of SST in use
• Command invoked, sst dev, sst deploy, etc.
• General machine information, like the number of CPUs, OS, CI/CD environment, etc.

This is completely optional and can be disabled at any time.

telemetry enable

sst telemetry enable

Enable telemetry.

telemetry disable

sst telemetry disable

Disable telemetry.

refresh

sst refresh

Compares your local state with the state of the resources in the cloud provider. Any changes that are found are adopted into your local state.

This is useful for cases where you want to ensure that your local state is in sync with your cloud provider.