CLI

The CLI helps you manage your SST apps.

If you are using SST as a part of your Node project, we recommend installing it locally.

npm install sst

---

If you are not using Node, you can install the CLI globally.

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

Note

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

To install a specific version.

curl -fsSL https://sst.dev/install | VERSION=0.0.403 bash

---

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.

---

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.

You can also use the SST_STAGE environment variable.

SST_STAGE=dev sst [command]

This can also be declared in a .env file or in the CLI session.

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

Prints extra information to the log files in the .sst/ directory.

sst [command] --verbose

To also view this on the screen, use the --print-logs flag.

print-logs

Type boolean

Print the logs to the screen. These are logs that are written to the .sst/ directory.

sst [command] --print-logs

It can also be set using the SST_PRINT_LOGS environment variable.

SST_PRINT_LOGS=1 sst [command]

This is useful when running in a CI environment.

help

Type boolean

Prints help for the given command.

sst [command] --help

Or the global help.

sst --help

Commands

init

sst init

Flags

• yes boolean

  Skip interactive confirmation for detected framework.

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.

To skip the interactive confirmation after detecting the framework.

sst init --yes

dev

sst dev [command]

Args

• command?

  The command to run

Flags

• mode string

  Defaults to using the multiplexer or mosaic mode. Use basic to turn it off.

Run your app in dev mode.

sst dev

By default, this starts a multiplexer with processes that deploy your app, run your functions, and start your frontend.

Each process is run in a separate pane that you can click on in the sidebar. These include processes that:

1. Watch your sst.config.ts and deploy your app
2. Run your functions Live and logs their invocations
3. Start a sst tunnel session if your app has a VPC with bastion enabled
4. Run the dev mode for components that have dev.autostart enabled
   • Components like Service and frontends like Nextjs, Remix, Astro, StaticSite, etc.
   • It starts their dev.command in a separate pane
   • And loads any linked resources in the environment

The multiplexer makes it so that you won’t have to start your frontend or your container applications separately.

Tip

The sst dev CLI also starts your frontend. So you don’t need to start it separately.

While sst dev does a deploy when it starts up, it does not deploy components like Service, or the frontends like Nextjs, Remix, Astro, StaticSite, etc. That’s because these have their own dev modes that the multiplexer starts.

Note

The Service component and the frontends like Nextjs or StaticSite are not deployed by sst dev.

Optionally, you can disable the multiplexer and run sst dev in basic mode.

sst dev --mode=basic

This will only deploy your app and run your functions. If you are coming from SST v2, this is how sst dev used to work.

However in basic mode, you’ll need to start your frontend separately by running sst dev in a separate terminal session by passing in the command. For example:

sst dev next dev

By wrapping your command, it’ll load your linked resources in the environment.

To pass in a flag to the command, use --.

sst dev -- next dev --turbo

deploy

sst deploy

Flags

• target

  Comma separated list of target URNs.

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

All the resources are deployed as concurrently as possible, based on their dependencies. For resources like your container images, sites, and functions; it first builds them and then deploys the generated assets.

Since the build processes for some of these resources take a lot of memory, the concurrency is limited by default.

• The sites default to 1 concurrent build.
• The container images default to 1 concurrent build.
• The Lambda functions default to 4 concurrent builds.

You can change this by setting the SST_BUILD_CONCURRENCY_SITE, SST_BUILD_CONCURRENCY_CONTAINER, and SST_BUILD_CONCURRENCY_FUNCTION environment variables.

SST_BUILD_CONCURRENCY_SITE=2 SST_BUILD_CONCURRENCY_CONTAINER=2 SST_BUILD_CONCURRENCY_FUNCTION=8 sst deploy

You can change this based on how much memory your CI environment has.

Tip

You can turn down the build concurrency if you are running out of memory in CI.

Optionally, deploy your app to a specific stage.

sst deploy --stage production

Optionally, deploy specific resources by passing in a list of their URNs. You can get the URN of a resource from the Console.

sst deploy --target urn:pulumi:prod::www::sst:aws:Astro::Astro,urn:pulumi:prod::www::sst:aws:Bucket::Assets

diff

sst diff

Flags

• target

  Comma separated list of target URNs.

• dev boolean

  Compare to the dev of this stage.

Builds your app to see what changes will be made when you deploy it.

It displays a list of resources that will be created, updated, or deleted. For each of these resources, it’ll also show the properties that are changing.

Tip

Run a sst diff to see what changes will be made when you deploy your app.

This is useful for cases when you pull some changes from a teammate and want to see what will be deployed; before doing the actual deploy.

Optionally, you can diff a specific set of resources by passing in a list of their URNs.

sst diff --target urn:pulumi:prod::www::sst:aws:Astro::Astro,urn:pulumi:prod::www::sst:aws:Bucket::Assets

By default, this compares to the last deploy of the given stage as it would be deployed using sst deploy. But if you are working in dev mode using sst dev, you can use the --dev flag.

sst diff --dev

This is useful because in dev mode, you app is deployed a little differently.

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: "6.27.0"
  }
}

You can use any provider listed in the Directory.

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 change it in your config.

sst.config.ts

{
  providers: {
    aws: {
      version: "6.26.0"
    }
  }
}

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

By default, these packages are fetched from the NPM registry. If you want to use a different registry, you can set the NPM_REGISTRY environment variable.

NPM_REGISTRY=https://my-registry.com sst add aws

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

Flags

• fallback boolean

  Manage the fallback values of secrets.

Subcommands

• set

• remove

• load

• list

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

The --fallback flag can be used to manage the fallback values of a secret. Applies to all the sub-commands in 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

You can also set a fallback value for a secret with --fallback.

sst secret set StripeSecret dev_123456789 --fallback

So if the secret is not set for a specific stage, it’ll use the fallback instead. This only works for stages that are in the same AWS account.

Tip

Set fallback values for your PR stages.

This is useful for preview environments that are automatically deployed. You won’t have to set the secret for the stage after it’s deployed.

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

Remove the fallback value of the secret.

sst secret remove StripeSecret --fallback

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

Set these secrets as fallback values.

sst secret load ./secrets.env --fallback

secret list

sst secret list

Lists all the secrets.

Optionally, list the secrets in a specific stage.

sst secret list --stage production

List only the fallback secrets.

sst secret list --fallback

shell

sst shell [command]

Args

• command?

  A command to run.

Flags

• target

  Target to run against.

Run a command with all the resources linked to the environment. This is useful for running scripts against your infrastructure.

For example, let’s say you have the following resources in your app.

sst.config.ts

new sst.aws.Bucket("MyMainBucket");
new sst.aws.Bucket("MyAdminBucket");

We can now write a script that’ll can access both these resources with the JS SDK.

my-script.js

import { Resource } from "sst";

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

And run the script with sst shell.

sst shell node my-script.js

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

Tip

Run the command with -- to pass arguments to it.

To pass arguments into the script, you’ll need to prefix it using --.

sst shell -- node my-script.js --arg1 --arg2

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 resources in your app.

remove

sst remove

Flags

• target string

  Comma separated list of target URNs.

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.

This does not remove the SST state and bootstrap resources in your account as these might still be in use by other apps. You can remove them manually if you want to reset your account, learn more.

Optionally, remove your app from a specific stage.

sst remove --stage production

Optionally, remove specific resources by passing in a list of their URNs. You can get the URN of a resource from the Console.

sst remove --target urn:pulumi:prod::www::sst:aws:Astro::Astro,urn:pulumi:prod::www::sst:aws:Bucket::Assets

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.

You can also opt-out by setting an environment variable: SST_TELEMETRY_DISABLED=1 or DO_NOT_TRACK=1.

telemetry enable

sst telemetry enable

Enable telemetry.

telemetry disable

sst telemetry disable

Disable telemetry.

refresh

sst refresh

Flags

• target string

  Comma separated list of target URNs.

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. It will:

1. Go through every single resource in your state.
2. Make a call to the cloud provider to check the resource.
   • If the configs are different, it’ll update the state to reflect the change.
   • If the resource doesn’t exist anymore, it’ll remove it from the state.

Note

The sst refresh does not make changes to the resources in the cloud provider.

Optionally, refresh specific resources by passing in a list of their URNs. You can get the URN of a resource from the Console.

sst refresh --target urn:pulumi:prod::www::sst:aws:Astro::Astro,urn:pulumi:prod::www::sst:aws:Bucket::Assets

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

cert

sst cert

Generate a locally-trusted certificate to connect to the Console.

The Console can show you local logs from sst dev by connecting to your CLI. Certain browsers like Safari and Brave require the local connection to be running on HTTPS.

This command uses mkcert internally to generate a locally-trusted certificate for localhost and 127.0.0.1.

You’ll only need to do this once on your machine.

tunnel

Subcommands

• install

Start a tunnel.

sst tunnel

If your app has a VPC with bastion enabled, you can use this to connect to it. This will forward traffic from the following ranges over SSH:

• 10.0.4.0/22
• 10.0.12.0/22
• 10.0.0.0/22
• 10.0.8.0/22

The tunnel allows your local machine to access resources that are in the VPC.

Note

The tunnel is only available for apps that have a VPC with bastion enabled.

If you are running sst dev, this tunnel will be started automatically under the Tunnel tab in the sidebar.

Tip

This is automatically started when you run sst dev.

You can start this manually if you want to connect to a different stage.

sst tunnel --stage production

This needs a network interface on your local machine. You can create this with the sst tunnel install command.

tunnel install

sst tunnel install

Install the tunnel.

To be able to create a tunnel, SST needs to create a network interface on your local machine. This needs sudo access.

sudo sst tunnel install

You only need to run this once on your machine.

diagnostic

sst diagnostic

Generates a diagnostic report based on the last command that was run.

This takes the state of your app, its log files, and generates a zip file in the .sst/ directory. This is for debugging purposes.