Skip to main content

SST CLI

The SST CLI allows you to build, deploy, test, and manage SST apps.

Installation​

Install the sst npm package in your project root.

npm install sst --save-exact

If you are using our starters, the sst package should already be installed.

Usage​

Once installed, you can run the commands using.

npx sst <command>

This will run the commands using the locally installed version of SST.

AWS profile​

Specify the AWS account you want to deploy to by using the --profile option. If not specified, uses the default AWS profile. Read more about AWS profiles here. For example:

npx sst deploy --profile=production

Where production is a profile defined locally in your ~/.aws/credentials.

Or, use the AWS_PROFILE CLI environment variable

AWS_PROFILE=production npx sst deploy

Commands​

Let's look at the commands in the SST CLI.

sst dev​

Starts up a local development environment for your Lambda functions, powered by Live Lambda Dev. It allows you to make changes and test your functions without having to deploy them.

npx sst dev [options]

In addition to the global options, the following options are supported.

Options​

  • --outputs-file

    Default: none

    Pass in this option if you want to write the AWS CloudFormation stack outputs to a JSON file. Works the same way as the --outputs-file option in AWS CDK.

  • --rollback

    Default: true

    By default SST enables rollback on failure. This is so that any mistakes do not leave your infrastructure in an inconsistent state. To override this behavior pass in --rollback=false.

  • --increase-timeout

    Default: Default Lambda function timeout

    Pass in the --increase-timeout option if you want to increase the timeout value for all the Lambda functions in your app to 15 minutes (the maximum value). This gives you more time to inspect your breakpoints before the functions timeout.

    This option is meant to be used when debugging with VS Code or other debuggers that can set breakpoints.

    A couple of things to note when --increase-timeout option is enabled:

    • APIs have a timeout of 30 seconds. So if the Lambda function does not return after 30 seconds, the API request will timeout. However, you can continue to debug your Lambda functions. The request might fail but the breakpoint context is still preserved for 15 minutes.
    • Queues need to have a visibility timeout that is longer than the timeout of the subscribing Lambda function. If the visibility timeout is configured to less than 15 minutes, it'll be increased to 15 minutes as well.

sst diff​

Compares the current version of the stacks in your app with the ones that've been deployed to AWS. This can be helpful in doing a quick check before deploying your changes to prod.

npx sst diff [stacks..] [options]

You can also optionally compare a list of stacks.

npx sst diff stack-a stack-b

sst bind​

Bind your app's resources to the given command. This allows the sst/node client to work as if it was running inside a Lambda function.

npx sst bind <command> [options]

So for example, you can start your frontend with all the binding values.

npx sst bind next dev

You can also bind all the resources in your app and use it to run your tests.

npx sst bind vitest run

You can read more about how this works for running tests.

sst build​

Build your app and synthesize your stacks. Generates a .build/ directory with the compiled files and a .build/cdk.out/ directory with the synthesized CloudFormation stacks.

npx sst build [options]

In addition to the global options, the following options are supported.

Options​

  • --to

    Default: .sst/dist

    Pass in a path for the build output. This lets you split up the deploy process and deploy without having to build the app again.

sst deploy​

Deploy your app to AWS. Or optionally deploy a specific stack by passing in a filter.

npx sst deploy [filter] [options]

In addition to the global options, the following options are supported.

Options​

  • --outputs-file

    Default: none

    Pass in this option if you want to write the AWS CloudFormation stack outputs to a JSON file. Works the same way as the --outputs-file option in AWS CDK.

  • --from

    Default: none

    Pass in a path for the build output. This lets you split up the deploy process and deploy without having to build the app again.

sst remove​

Remove your app and all their resources from AWS. Or optionally deploy a specific stack by passing in a filter.

npx sst remove [filter] [options]
Removal Policy

By default, AWS does not remove resources like S3 buckets or DynamoDB tables. To let SST remove these, you'd need to set the default removal policy.

sst update​

Updates the SST and CDK packages in your package.json to the latest version. Or optionally to the given version.

npx sst update [version] [options]

sst console​

npx sst console [options]

Launches the SST Console to manage stages that are not running locally. It uses your local credentials (or the ones you specify) to make calls to AWS.

For more context; if you run sst dev and fire up the Console, you'll see the logs for the local invocations of your functions. Whereas with the sst console command, you'll see their CloudWatch logs instead. This allows you to use the Console against your production or staging environments.

info

This command does not instrument your code. It simply uses your local credentials to make calls to AWS.

Options​

  • --stage

    Default: Your local stage

    The stage you want connect to. If this is not specified, it will default to your local stage.

    Connecting to a different stage.

    npx sst console --stage=staging

    Using a different aws profile if your stage is in another AWS account.

    npx sst console --stage=production --profile=acme-production

sst secrets​

Manage secrets in your app.

npx sst secrets <command> [options]

For example, you can set a secret.

npx sst secrets set MY_SECRET abc

Get the secret.

npx sst secrets get MY_SECRET

And remove the secret.

npx sst secrets remove MY_SECRET

Options​

  • --fallback

    Default: false

    Set this option if you want to get, set, or remove the fallback version of a secret. For example, to get the fallback of a secret.

    npx sst secrets get --fallback STRIPE_KEY

    Note that, the fallback value can only be inherited by stages deployed in the same AWS account and region. Read more about fallback values.

sst secrets takes the following commands.

sst secrets get​

Decrypts and prints the value of the secret with the given name.

npx sst secrets get <name> [options]

sst secrets set​

Sets the value of a secret with the given name.

npx sst secrets set <name> <value> [options]

sst secrets list​

Decrypts and prints out all the secrets with the given format; table or env. Where env is the dotenv format. Defaults to table.

npx sst secrets list [format] [options]

sst secrets remove​

Removes the secret with the given name.

npx sst secrets remove <name> [options]

sst telemetry​

SST collects completely anonymous telemetry data about general usage.

npx sst telemetry <status> [options]

You can opt-out of this if you'd not like to share any information.

npx sst telemetry disable

You can also re-enable telemetry if you'd like to re-join the program.

npx sst telemetry enable

Global options​

  • --stage

    Default: Your personal stage

    The stage you want to deploy to. If this is not specified, it will default to the stage configured during the initial run of the CLI. This is cached in the .sst/ directory.

    This option applies to the dev, build, deploy, remove, and secrets commands.

  • --profile

    Default: The default profile in your AWS credentials file.

    The AWS profile you want to use for deployment. Defaults to the default profile in your AWS credentials file.

  • --region

    Default: Stage set in the SST config.

    The region you want to deploy to. Defaults to the one specified in your sst.json. Or uses us-east-1.

    This option applies to the dev, build, deploy, remove, and secrets commands.

  • --verbose

    Default: false

    Prints verbose logs.

  • --role

    ARN of the IAM Role to use when invoking AWS. This role must be assumable by the AWS account being used.

    This option applies to the start, deploy, and remove commands.