Amplify has re-imagined the way frontend developers build fullstack applications. Develop and deploy without the hassle.

Page updated Jul 17, 2024

CLI commands

This page serves as a reference for commands found in the @aws-amplify/backend-cli package.

All commands can be prefixed with AWS CLI environment variables to change the AWS account behavior with Amplify Gen 2 commands.

npx ampx sandbox

Sandbox enables you to develop your backend alongside your frontend's development server. Run npx ampx sandbox to deploy to your personal cloud sandbox, this command will automatically watch for changes in the amplify/ folder, and redeploy each time you save a file.

Options

  • --dir-to-watch (string) - Directory to watch for file changes. All subdirectories and files will be included. Defaults to the amplify directory.
  • --exclude (string[]) - An array of paths or glob patterns to ignore. Paths can be relative or absolute and can either be files or directories.
  • --identifier (string) - An optional name to distinguish between different sandbox environments. Default is the name of the system user executing the process
  • --outputs-out-dir (string) - A path to a directory where the client config file is written. If not provided, defaults to the working directory of the current process.
  • --outputs-format (string) - Format in which the client config file is written (choices: json, dart).
  • --outputs-version (string) - Version of the configuration. Version 0 represents classic amplify-cli config file amplify-configuration and 1 represents newer config file amplify_outputs (choices: 0, 1).
  • --profile (string) - An AWS profile name.

Usage

Terminal
npx ampx sandbox

Use with an alternate profile

You can use the --profile flag to run sandbox with an AWS profile other than default:

Terminal
npx ampx sandbox --profile my-other-profile

Additionally, you can use AWS CLI environment variables to specify a different profile:

Terminal
AWS_PROFILE=my-other-profile ampx sandbox

Use with an alternate Region

Use AWS environment variables to deploy to a Region other than your AWS profile's configured Region:

Terminal
AWS_REGION=us-west-2 ampx sandbox

Use with mobile applications

For mobile applications, you will need to set the output directory and format of the generated configuration file, specifically amplify_outputs.json:

Terminal
# for Android
npx ampx sandbox --outputs-out-dir app/src/main/res
Terminal
# for Swift/iOS
npx ampx sandbox
Terminal
# for Flutter
npx ampx sandbox --outputs-format dart --outputs-out-dir lib

npx ampx sandbox delete

Delete your personal cloud sandbox. This should only be used if you have an active cloud sandbox that you opted to not delete when exiting npx ampx sandbox.

Options

  • --name (string) - An optional name to distinguish between different sandbox environments. Default is the name in your package.json.
  • --profile (string) - An AWS profile name.
  • -y, --yes (boolean) - Do not ask for confirmation before deleting the sandbox environment.

Usage

Terminal
npx ampx sandbox delete

npx ampx sandbox secret

Manage backend secrets used with your personal cloud sandbox.

Options

  • --profile (string) - An AWS profile name.

Usage

Terminal
npx ampx sandbox secret

Using with an alternate AWS profile

You can use the --profile flag to run sandbox with an AWS profile other than default:

Terminal
npx ampx sandbox secret list --profile my-other-profile

Additionally, you can use AWS environment variables to specify a different profile:

Terminal
AWS_PROFILE=my-other-profile ampx sandbox secret list

Creating a secret

Create secrets for use with your personal cloud sandbox by using sandbox secret set:

Terminal
npx ampx sandbox secret set LOGINWITHAMAZON_CLIENT_ID

This is how you configure secrets to be retrieved and used within your backend using secret().

Removing a secret

If you want to remove a secret you previously set, use sandbox secret remove:

Terminal
npx ampx sandbox secret remove LOGINWITHAMAZON_CLIENT_ID

Listing secrets

List all available secrets for your personal sandbox in the default AWS profile and Region:

Terminal
npx ampx sandbox secret list

Get a secret and view its details

You can view an existing secret and its details, such as the current version and when it was last updated:

Terminal
npx ampx sandbox secret get LOGINWITHAMAZON_CLIENT_ID
name: LOGINWITHAMAZON_CLIENT_ID
version: 1
value: ****
lastUpdated: Fri Nov 17 2023 12:00:00 GMT-0800 (Pacific Standard Time)

npx ampx generate

Generate is not intended to be used standalone; however, it does offer a few subcommands to generate information or code that is supplemental to your frontend development.

Each of the following generate subcommands require either a CloudFormation stack name or an existing Amplify App ID and corresponding git branch:

Terminal
# with CloudFormation stack name
npx ampx generate <subcommand> --stack <cloudformation-stack-name>
Terminal
# with Amplify App ID and git branch
npx ampx generate <subcommand> --app-id <app-id> --branch <git-branch-name>

npx ampx generate outputs

Generate the backend outputs file (e.g. amplify_outputs.json) for your frontend application to consume. This is intended to be used to manually generate a configuration file for an environment other than your personal cloud sandbox. For example, you might use it if you would like to verify something your coworker is seeing in their cloud sandbox, or to demonstrate frontend changes locally using a pre-existing "staging" branch.

Options

In addition to the required options noted in ampx generate:

  • --profile (string) - An AWS profile name.
  • --format (string) - The format into which the configuration should be exported (choices: json, dart).
  • --out-dir (string) - A path to the directory where config is written. If not provided, it defaults to the working directory of the current process.
  • --outputs-version (string) - Version of the configuration. Version 0 represents classic amplify-cli config file amplify-configuration and 1 represents newer config file amplify_outputs (choices: 0, 1).

Usage

As mentioned above, you can specify a team member's cloud sandbox CloudFormation stack:

Terminal
npx ampx generate outputs --stack amplify-nextamplifygen2-josef-sandbox-ca85e1081b

Use with mobile applications

Similar to sandbox, you can specify an alternate outputs file format by using --format:

Terminal
npx ampx generate outputs --stack amplify-nextamplifygen2-josef-sandbox-ca85e1081b

npx ampx generate graphql-client-code

Generate GraphQL statements and types for your frontend application to consume.

Options

The available parameters for npx ampx generate graphql-client-code are:

Required parameters:

  • Stack identifier
    • --stack(string) - A stack name that contains an Amplify backend.
  • Project identifier
    • --app-id(string) - The Amplify App ID of the project.
    • --branch(string) - A git branch of the Amplify project.

Optional parameters:

  • --out(string) - Specifies the path to the directory where the config is written. If not provided, defaults to the current process working directory.
  • --format(string) (choices: modelgen, graphql-codegen, introspection) - Specifies the format of the GraphQL client code to be generated.
  • --model-target (string) (choices: java, swift, javascript, typescript, dart) - Specifies the modelgen export target. Only applies when the --format parameter is set to modelgen.
  • --statement-target(string) (choices: javascript, graphql, flow, typescript, angular) - Specifies the graphql-codegen statement export target. Only applies when the --format parameter is set to graphql-codegen.
  • --type-target(string) (choices: json, swift, typescript, flow, scala, flow-modern, angular) - Specifies the optional graphql-codegen type export target. Only applies when the --format parameter is set to graphql-codegen.
  • --all(boolean)- Shows hidden options.
  • --profile(string) - Specifies an AWS profile name.
  • --debug (boolean) - Print debug logs to the console.
  • --help(boolean) - Displays help information about the command.

Usage

Generate GraphQL client code using the Amplify App ID and branch.

Terminal
npx ampx generate graphql-client-code --app-id <your-amplify-app-id> --branch staging

Generate GraphQL client code for a branch that is connected to Amplify

Sometimes you want to test your latest local changes with the backend of another deployed branch. If you want to generate the GraphQL client code file(s) for the latest deployment of another branch, you can run the following command:

Terminal
npx ampx generate graphql-client-code --branch staging

Generate codegen for CDK app using a joint "AmplifyBackendStack" construct

Assume you have deployed your Amplify project with the CDK construct. You will need to remember your app's project name (designated as the second parameter in your CDK construct) and stack name (designated as part of your npx cdk deploy context)

lib/stack.ts
import { Construct } from 'constructs';
import { App, Backend } from 'aws-cdk-lib/aws-amplify';
export class MyAmplifyStack extends cdk.Stack {
constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
new Backend(this, "Backend", { /* ... */ });
}
}

Deployment command for CDK project

Terminal
npx cdk deploy

Run Amplify codegen command to generate GraphQL codegen:

Terminal
npx ampx generate graphql-client-code --stack Backend --platform ts --out ./src

Generate codegen in specific language and format

Terminal
npx ampx generate graphql-client-code --format modelgen --type-target angular

Supported GraphQL client code combinations:

FormatPlatformCodegen command in Amplify CLICommand in Amplify Gen2Default generated file/path
Introspection schemaAmplify JavascriptN/Anpx ampx generate graphql-client-code --format introspection<path_to_app>/
GraphQL codegenAmplify Javascriptamplify codegennpx ampx generate graphql-client-code --format graphql-codegen --statement-target javascript --out <path_to_app>/src/graphql/<path_to_app>/src/graphql/
ModelgenAmplify Javascriptamplify codegen modelnpx ampx generate graphql-client-code --format modelgen --model-target javascript --out <path_to_app>/src/models/<path_to_app>/src/models/
ModelgenAmplify Androidamplify codegen modelnpx ampx generate graphql-client-code --format modelgen --model-target java --out <path_to_app/src/main/java/><path_to_app>/src/main/java/com/amplifyframework/datastore/generated/model
ModelgenAmplify Swiftamplify codegen modelnpx ampx generate graphql-client-code --format modelgen --model-target swift --out <path_to_swift_project>/AmplifyModels<path_to_swift_project>/AmplifyModels
ModelgenAmplify Flutteramplify codegen modelnpx ampx generate graphql-client-code --format modelgen --model-target dart --out <path_to_flutter_project>/AmplifyModels<path_to_flutter_project>/AmplifyModels

npx ampx generate forms

Generate React form components derived from your backend data models for your frontend application to consume.

Options

  • --stack(string) - A stack name that contains an Amplify backend.
  • --branch (string) - Name of the git branch being deployed.
  • --app-id (string) - The app id of the target Amplify app.
  • --out-dir (string) - A path to directory where generated forms are written. Defaults to the ./ui-components directory.
  • --models (array) - Model name to generate.
  • --profile (string) - An AWS profile name.

Usage

Terminal
npx ampx generate forms --branch $BRANCH_NAME --app-id $AWS_APP_ID --out-dir ./src

npx ampx info

Generates information on system, binaries, npm packages, and environment variables for troubleshooting Amplify issues.

Terminal
npx ampx info

This command will print system information as follows:

Terminal
System:
OS: macOS 14.3.1
CPU: (10) arm64 Apple M1 Pro
Memory: 165.89 MB / 32.00 GB
Shell: /opt/homebrew/bin/fish
Binaries:
Node: 20.12.2 - ~/Library/Caches/fnm_multishells/1063_1714573452292/bin/node
Yarn: 1.22.19 - ~/Library/Caches/fnm_multishells/1063_1714573452292/bin/yarn
npm: 10.5.0 - ~/Library/Caches/fnm_multishells/1063_1714573452292/bin/npm
pnpm: 9.0.5 - ~/Library/Caches/fnm_multishells/1063_1714573452292/bin/pnpm
NPM Packages:
@aws-amplify/backend: 1.0.0
@aws-amplify/backend-cli: 1.0.1
aws-amplify: 6.2.0
aws-cdk: 2.139.1
aws-cdk-lib: 2.139.1
typescript: 5.4.5
AWS environment variables:
AWS_PROFILE = amplify-admin
AWS_STS_REGIONAL_ENDPOINTS = regional
AWS_NODEJS_CONNECTION_REUSE_ENABLED = 1
AWS_SDK_LOAD_CONFIG = 1
No CDK environment variables

npx ampx pipeline-deploy

Deploys the Amplify project in a CI/CD pipeline for a specified Amplify app and branch.

Options

  • --branch (string) - Name of the git branch being deployed.
  • --app-id (string) - The app id of the target Amplify app.
  • --outputs-out-dir (string) - A path to a directory where the client config file is written. If not provided, defaults to the working directory of the current process.
  • --outputs-version (string) - Version of the configuration. Version 0 represents classic amplify-cli config file amplify-configuration and 1 represents newer config file amplify_outputs (choices: 0, 1).

Usage

Terminal
npx ampx pipeline-deploy --branch $BRANCH_NAME --app-id $AWS_APP_ID