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.--stream-function-logs
(boolean) - Whether to stream function execution logs. (default: false)--logs-filter
(string[]) - Regex pattern to filter logs from only matched functions. E.g. to stream logs for a function, specify it's name, and to stream logs from all functions starting with auth specify 'auth' (default: Stream all logs)--logs-out-file
(string) - File to append the streaming logs. The file is created if it does not exist. (default: stdout)
Usage
npx ampx sandbox
Use with an alternate profile
You can use the --profile
flag to run sandbox with an AWS profile other than default
:
npx ampx sandbox --profile my-other-profile
Additionally, you can use AWS CLI environment variables to specify a different profile:
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:
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
:
# for Androidnpx ampx sandbox --outputs-out-dir app/src/main/res
# for Swift/iOSnpx ampx sandbox
# for Flutternpx 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
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
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
:
npx ampx sandbox secret list --profile my-other-profile
Additionally, you can use AWS environment variables to specify a different profile:
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
:
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
:
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:
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:
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:
# with CloudFormation stack namenpx ampx generate <subcommand> --stack <cloudformation-stack-name>
# with Amplify App ID and git branchnpx 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:
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
:
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.
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:
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)
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
npx cdk deploy
Run Amplify codegen command to generate GraphQL codegen:
npx ampx generate graphql-client-code --stack Backend --platform ts --out ./src
Generate codegen in specific language and format
npx ampx generate graphql-client-code --format modelgen --type-target angular
Supported GraphQL client code combinations:
Format | Platform | Codegen command in Amplify CLI | Command in Amplify Gen2 | Default generated file/path |
---|---|---|---|---|
Introspection schema | Amplify Javascript | N/A | npx ampx generate graphql-client-code --format introspection | <path_to_app>/ |
GraphQL codegen | Amplify Javascript | amplify codegen | npx ampx generate graphql-client-code --format graphql-codegen --statement-target javascript --out <path_to_app>/src/graphql/ | <path_to_app>/src/graphql/ |
Modelgen | Amplify Javascript | amplify codegen model | npx ampx generate graphql-client-code --format modelgen --model-target javascript --out <path_to_app>/src/models/ | <path_to_app>/src/models/ |
Modelgen | Amplify Android | amplify codegen model | npx 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 |
Modelgen | Amplify Swift | amplify codegen model | npx ampx generate graphql-client-code --format modelgen --model-target swift --out <path_to_swift_project>/AmplifyModels | <path_to_swift_project>/AmplifyModels |
Modelgen | Amplify Flutter | amplify codegen model | npx 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
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.
npx ampx info
This command will print system information as follows:
System: OS: macOS 14.3.1 CPU: (10) arm64 Apple M1 Pro Memory: 165.89 MB / 32.00 GB Shell: /opt/homebrew/bin/fishBinaries: 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/pnpmNPM 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.5AWS environment variables: AWS_PROFILE = amplify-admin AWS_STS_REGIONAL_ENDPOINTS = regional AWS_NODEJS_CONNECTION_REUSE_ENABLED = 1 AWS_SDK_LOAD_CONFIG = 1No 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
npx ampx pipeline-deploy --branch $BRANCH_NAME --app-id $AWS_APP_ID