Azure Static Web Apps CLI reference

The reference of Azure Static Web Apps CLI commands.

Commands

Global Parameters

swa login

Log in to Azure.

Authenticate with Azure to get a deployment token for Azure Static Web Apps, using the swa deploy command.

Syntax

swa login
          [--subscription-id]
          [--resource-group]
          [--tenant-id]
          [--client-id]
          [--client-secret]
          [--app-name]
          [--clear-credentials]
          [--use-keychain]
          [--no-use-keychain]

Examples

Example 1: Interactive log in to Azure

swa login

Parameters

--subscription-id, -S

Azure subscription ID used by this project. The default is process.env.AZURE_SUBSCRIPTION_ID.

--resource-group, -R

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--tenant-id, -T

Azure tenant ID. The default is process.env.AZURE_TENANT_ID.

--client-id, -C

Azure client ID.

--client-secret, -CS

Azure client secret.

--app-name, -n

Azure Static Web Apps app name.

--clear-credentials -cc

Clear persisted credentials before login. The default is false.

--use-keychain, -u

Use the operating system native keychain for persistent credentials. The default is true.

--no-use-keychain, -nu

Disable use of the operating system native keychain.

Global Parameters

swa init

Configures a new Azure Static Web Apps project.

Configures a new Azure Static Web Apps project with the Static Web Apps CLI. Interactive mode prompts you for a configuration name, detects your project settings and the frameworks used. Once complete, a new static web app is created and a swa-cli.config.json file is generated in the current directory.

You can run swa init multiple times to create different configurations for your project. You may want to do this if you're working on a monorepo and want to configure different projects.

The generated configuration file is used in every command you run with the Static Web Apps CLI. If you have multiple named configurations, you can use the positional argument or --config-name option to specify which configuration you want to use.

The following is an example configuration generated by the init command:

{
  "$schema": "https://aka.ms/azure/static-web-apps-cli/schema",
  "configurations": {
    "myApp": {
      "appLocation": ".",
      "apiLocation": "api",
      "outputLocation": "dist",
      "appBuildCommand": "npm run build",
      "apiBuildCommand": "npm run build --if-present",
      "run": "npm run dev",
      "appDevserverUrl": "http://localhost:8080"
    }
  }
}

Syntax

swa init
          [--yes]

Examples

Example 1: Create a new configuration interactively.

swa init

Example 2: Create a new configuration using default values for all options.

swa init --yes

Example 3: Initialize the project using the configuration named "myApp" from the swa-cli.config.json file.

swa init --config-name myApp

Parameters

--yes, -y

Answers "yes" to all prompts, which disables interactive mode. Default is false.

Global Parameters

swa build

Builds the application. If you have a Node.js application, it installs dependencies first.

Common use cases include: Installing dependencies for the front-end app and API and running the build commands for both, only building the front-end or API project if the other doesn't have a build step.

Syntax

swa build
          [--app-location]
          [--api-location]
          [--output-location]
          [--app-build-command]
          [--api-build-command]
          [--auto]

Examples

Example 1: Build the app, and optionally install dependencies.

swa build

Example 2: Detect how to build your app and run build commands after installing dependencies.

swa build --auto

Example 3: Install dependencies for the front-end application.

swa build --app-location ./client

Example 4: Use the configuration named myApp in swa-cli.config.json to build your front-end application.

swa build myApp

Parameters

--app-location, -a

The folder containing the source code of the front-end application. Default is ..

--api-location, -i

The folder containing the source code of the API application.

--output-location, -O

The folder containing the built source of the front-end application. This path is relative to --app-location. Default is ..

--app-build-command, -A

Builds the front-end application.

--api-build-command, -I

Builds the API application.

--auto

Automatically detects how to build your front-end and API applications. Default is false.

Global Parameters

swa start

Start the Azure Static Web Apps emulator from a directory or bind to a running dev server.

Serve from a folder

By default, the CLI starts and serves any static content from the current working directory ./:

swa start

If the artifact folder of your static app is under a different folder (for example, ./my-dist), then run the CLI and provide that folder:

swa start ./my-dist

Serve from a dev server

When developing your front-end app locally, it's often useful to use the dev server that comes with your front end framework's CLI. Using the framework CLI allows you to use built-in features like "livereload" and HMR (hot module replacement).

To use SWA CLI with your local dev server, follow these two steps:

1. Start your local dev server as usual. For example, if you are using Angular: ng serve (or npm start).

2. In a separate terminal, run swa start with the URI provided by the dev server, in the following format:

swa start http://<APP_DEV_SERVER_HOST>:<APP_DEV_SERVER_PORT>

Here is a list of the default ports and commands used by some popular dev servers:

Instead of starting a dev server separately, you can provide the startup command to the CLI.

# npm start script (React)
swa start http://localhost:3000 --run "npm start"

# dotnet watch (Blazor)
swa start http://localhost:5000 --run "dotnet watch run"

# Jekyll
swa start http://localhost:4000 --run "jekyll serve"

# custom script
swa start http://localhost:4200 --run "./startup.sh"

Then access the application with the emulated services from http://localhost:4280

Serve both the front-end app and API

If your project includes API functions, the CLI checks if the Azure Functions Core Tools are installed and available. If not, the CLI downloads and install the right version of the Azure Functions Core Tools.

Start the API server automatically

Run the CLI and provide the folder that contains the API backend (a valid Azure Functions App project):

# static content plus an API
swa start ./my-dist --api-location ./api

# front-end dev server plus an API
swa start http://localhost:3000 --api-location ./api

Start API server manually

When developing your backend locally, sometimes it's useful to run Azure Functions Core Tools separately to serve your API. This allows you to use built-in features like debugging and rich editor support.

To use the CLI with your local API backend dev server, follow these two steps:

1. Start your API using Azure Functions Core Tools: func host start or start debugging in VS Code.

2. In a separate terminal, run the SWA CLI with the --api-location flag and the URI of the local API server, in the following format:

swa start ./my-dist --api-location http://localhost:7071

Database connections

To start your application with a database connection, use the --data-api-location parameter and point to the folder containing the staticwebapp.database.config.json file.

swa start ./src --data-api-location swa-db-connections

Syntax

swa start

Examples

Example 1: Start the application with defaults.

swa start

Example 2: Start the application with a front end dev server.

swa start http://<APP_DEV_SERVER_HOST>:<APP_DEV_SERVER_PORT>

Example 3: Start the application with a front end and back end dev server.

swa start http://<APP_DEV_SERVER_HOST>:<APP_DEV_SERVER_PORT> --api-location http://localhost:7071

Parameters

--app-location, -a <PATH>

The folder containing the source code of the front end application. Default is ..

--api-location, -i <PATH>

The folder containing the source code of the API application.

--output-location, -O <PATH>

The folder containing the built source of the front end application. The path is relative to --app-location. Default is ..

--data-api-location

The folder containing the staticwebapp.database.config.json file.

--app-devserver-url, -D <URL>

Connect to the app dev server at this URL instead of using output location.

--api-devserver-url, -is <URL>

Connect to the API server at this URL instead of using output location.

--api-port, -j <API_PORT>

The API server port passed to func start. Default is 7071.

--host, -q <HOST>

The host address used for the CLI dev server. Default is localhost.

--port, -p <PORT>

The port value to use for the CLI dev server. Default 4280.

--ssl, -s

Serve the front end application and API over HTTPS. Default is false.

--ssl-cert, -e <SSL_CERT_LOCATION>

The SSL certificate (.crt) used when enabling HTTPS.

--ssl-key, -k <SSL_KEY_LOCATION>

The SSL key (.key) used when enabling HTTPS.

--run, -r <STARTUP_SCRIPT>

Location of a custom shell command or script file to run at startup.

--devserver-timeout, -t <TIME>

The amount of time to wait (in seconds) when connecting to a front end application's dev server or an API server. Default is 60.

--swa-config-location, -w <SWA_CONFIG_FILE_LOCATION>

The directory location of the staticwebapp.config.json file.

--open, -o

Open the browser to the dev server. Default is false.

--func-args, -f <FUNCTION_ARGUMENTS>

Pass additional arguments to the func start command.

Global Parameters

swa deploy

Deploy the current project to Azure Static Web Apps.

Common use cases include:

1. Deploy a front end app without an API

2. Deploy a front end app with an API

3. Deploy a Blazor app

Deployment token

The SWA CLI supports deploying using a deployment token. This is often useful when deploying from a CI/CD environment. You can get a deployment token either from:

• The Azure portal: Home → Static Web App → Your Instance → Overview → Manage deployment token

• If you are using the Azure CLI, you can get the deployment token of your project using the following command:

az staticwebapp secrets list --name <APPLICATION_NAME> --query "properties.apiKey"

• If you are using the Azure Static Web Apps CLI, you can use the following command:

swa deploy --print-token

You can then use that value with the --deployment-token <TOKEN> or you can create an environment variable called SWA_CLI_DEPLOYMENT_TOKEN and set it to the deployment token.

Deploy a front end app without an API

You can deploy a front end application without an API to Azure Static Web Apps by running the following steps:

1. If your front-end application requires a build step, run swa build or refer to your application build instructions.

Option 1: From build folder you would like to deploy, run the deploy command:

cd build/
swa deploy

Option 2: You can also deploy a specific folder:

1. If your front end application requires a build step, run swa build or refer to your application build instructions.

2. Deploy your app:

swa deploy ./my-dist

Deploy a front-end app with an API

To deploy both the front end app and an API to Azure Static Web Apps, use the following steps:

1. If your front end application requires a build step, run swa build or refer to your application build instructions.

2. Make sure the API language runtime version in the staticwebapp.config.json file is set correctly, for example:

{
  "platform": {
    "apiRuntime": "node:16"
  }
}

3. Deploy your app:

swa deploy ./my-dist --api-location ./api

Deploy a Blazor app

To deploy a Blazor app with an optional API to Azure Static Web Apps, use the following steps:

1. Build your Blazor app in Release mode:

dotnet publish -c Release -o bin/publish

2. From the root of your project, run the deploy command:

swa deploy ./bin/publish/wwwroot --api-location ./Api

Deploy using the swa-cli.config.json

If you are using a swa-cli.config.json configuration file in your project and have a single configuration entry, use a configuration like this:

{
  "configurations": {
    "my-app": {
      "appLocation": "./",
      "apiLocation": "api",
      "outputLocation": "frontend",
      "start": {
        "outputLocation": "frontend"
      },
      "deploy": {
        "outputLocation": "frontend"
      }
    }
  }
}

Then you can deploy your application by running the following steps:

1. If your front-end application requires a build step, run swa build or refer to your application build instructions.

2. Deploy your app:

swa deploy

If you have multiple configuration entries, you can provide the entry ID to specify which one to use:

swa deploy my-otherapp

Syntax

swa deploy
           [--yes]

Examples

Example 1: Deploy using a deployment token.

swa deploy ./dist/ --api-location ./api/ --deployment-token <TOKEN>

Example 2: Deploy using a deployment token from the environment variables

SWA_CLI_DEPLOYMENT_TOKEN=123 swa deploy ./dist/ --api-location ./api/

Example 3: Deploy using swa-cli.config.json file

swa deploy
swa deploy myconfig

Example 4: Print the deployment token

swa deploy --print-token

Example 5: Deploy to a specific environment

swa deploy --env production

Global Parameters

swa db

Generate and edit your Static Web Apps database connections configuration.

Use swa db init to generate a sample swa-db-connections folder, along with a staticwebapp.database.config.json configuration file. If you are using a Cosmos DB for NoSQL database, this also generates a sample staticwebapp.database.schema.gql schema file.

Syntax

swa db init --database-type <DATABASE_TYPE>

Examples

Example 1: Generate a sample database connection configuration folder for an Azure SQL database.

swa db init --database-type mssql

Parameters

--database-type, -t <DATABASE_TYPE>

(Required) The type of the database you want to connect (mssql, postgresql, cosmosdb_nosql, mysql).

--folder-name, -f <FOLDER_NAME>

A folder name to override the convention database connection configuration folder name (ensure that you update your CI/CD workflow files accordingly). The default value is swa-db-connections.

---connection-string, -cs <CONNECTION_STRING>

The connection string of the database you want to connect.

--cosmosdb_nosql-database, -nd <COSMOSDB_NOSQL_DATABASE>

The database of your Cosmos DB account you want to connect (only needed if using cosmosdb_nosql database type).

--cosmosdb_nosql-container, -nc <COSMOSDB_NOSQL_CONTAINER>

The container of your Cosmos DB account you want to connect.

--help, -h

Display help for command.

Global Parameters