CLI
Reference doc for the `sst` 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@ion
If you are not using Node, you can install the CLI globally.
curl -fsSL https://ion.sst.dev/install | bash
To install a specific version.
curl -fsSL https://ion.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.
Terminal window brew install sst/tap/sst# Upgradebrew upgrade sstYou 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 withsudo dpkg -i
andsudo 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.
If the stage is not passed in, then the CLI will:
- Use the username on the local machine.
- If the username is
root
,admin
,prod
,dev
,production
, then it will prompt for a stage name.
- If the username is
- 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 the global help.
sst --help
Commands
init
sst init
Flags
Skip interactive confirmation for detected framework.yes
boolean
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
The command to runcommand?
Flags
Use mode=basic to turn off multiplexermode
string
Run your app in development mode.
sst dev
Optionally, pass in a command to start your frontend as well.
sst dev next dev
To pass in a flag to your command, use —
sst dev -- next dev --turbo
Dev mode does a few things:
- Starts a local server
- Watches your
sst.config.ts
and re-deploys changes - Run your functions Live
- Skip components that should be run locally
Service
- Frontends like,
Nextjs
,Remix
,Astro
,SvelteKit
, etc.
- If you pass in a
command
, it’ll:- Load your linked resources in the environment
- And run the command
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.
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
Flags
Comma seperated list of target URNs.target
Deploy your application. By default, it deploys to your personal stage.
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
Comma seperated list of target URNs.target
Compare to sst devdev
boolean
See what changes will be made
add
sst add <provider>
Args
The provider to add.provider
Adds and installs the given provider. For example,
sst add aws
This command will:
- Installs the package for the AWS provider.
- Add
aws
to the globals in yoursst.config.ts
. - And, add it to your
providers
.
{ providers: { aws: true }}
You can use any provider listed in the Directory.
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.
{ providers: { aws: { version: "6.27.0" } }}
install
sst install
Installs the providers in your sst.config.ts
. You’ll need this command when:
- You add a new provider to the
providers
orhome
in your config. - Or, when you want to install new providers after you
git pull
some changes.
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
secret set
sst secret set <name> [value]
Args
The name of the secret.name
The value of the secret.value
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.
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+KeFhnii7NT7fELilKUSnxS30WAvQCCo2yU1orfgqr41mM70MBAgMBAAE=-----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
The file to load the secrets from.file
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.
KEY_1=VALUE1KEY_2=VALUE2
Optionally, set the secrets in a specific stage.
sst secret load ./prod.env --stage production
secret remove
sst secret remove <name>
Args
The name of the secret.name
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
A command to run.command?
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.
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.
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.
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
Comma seperated list of target URNs.target
string
Removes your application. By default, it removes your personal stage.
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](/docs/console/#resources).
```bash frame="none"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
A version to upgrade to.version?
Upgrade the CLI to the latest version. Or optionally, pass in a version to upgrade to.
sst upgrade 0.10
telemetry
Subcommands
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
Flags
Comma seperated list of target URNs.target
string
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:
- Go through every single resource in your state.
- 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.
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.