---
title: "CLI commands"
section: "reference"
platforms: ["android", "angular", "flutter", "javascript", "nextjs", "react", "react-native", "swift", "vue"]
gen: 2
last-updated: "2025-04-28T21:41:46.000Z"
url: "https://docs.amplify.aws/react/reference/cli-commands/"
---

This page serves as a reference for commands found in the [`@aws-amplify/backend-cli`](https://www.npmjs.com/package/@aws-amplify/backend-cli) package.

All commands can be prefixed with [AWS CLI environment variables](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html#envvars-list) 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.

### Logs Streaming

- `--stream-function-logs` (_boolean_) - Whether to stream function execution logs. (default: false)
- `--logs-filter` (_array_) - 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)

### Options

- `--debug` (_boolean_) - Print debug logs to the console (default: false)
- `--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
- `--once` (_boolean_) - Execute a single sandbox deployment without watching for future file changes.
- `--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

```bash title="Terminal" showLineNumbers={false}
npx ampx sandbox
```

#### Use with an alternate profile

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

```bash title="Terminal" showLineNumbers={false}
npx ampx sandbox --profile my-other-profile
```

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

```bash title="Terminal" showLineNumbers={false}
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:

```bash title="Terminal" showLineNumbers={false}
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`:

```bash title="Terminal" showLineNumbers={false}
# for Android
npx ampx sandbox --outputs-out-dir app/src/main/res
```

```bash title="Terminal" showLineNumbers={false}
# for Swift/iOS
npx ampx sandbox
```

```bash title="Terminal" showLineNumbers={false}
# 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

```bash title="Terminal" showLineNumbers={false}
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

```bash title="Terminal" showLineNumbers={false}
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`:

```bash title="Terminal" showLineNumbers={false}
npx ampx sandbox secret list --profile my-other-profile
```

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

```bash title="Terminal" showLineNumbers={false}
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`:

```bash title="Terminal" showLineNumbers={false}
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`:

```bash title="Terminal" showLineNumbers={false}
npx ampx sandbox secret remove LOGINWITHAMAZON_CLIENT_ID
```

#### Removing all secrets

If you want to remove all secrets you previously set, use `sandbox secret remove --all`:

```bash title="Terminal" showLineNumbers={false}
npx ampx sandbox secret remove --all
```

#### Listing secrets

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

```bash title="Terminal" showLineNumbers={false}
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:

```console title="Terminal" showLineNumbers={false}
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 sandbox seed

Seeds your sandbox environment with data using the seed script defined in your project.

### Options

- `--debug` (_boolean_) - Print debug logs to the console. [default: false]
- `--identifier` (_string_) - An optional identifier to distinguish between different sandboxes. Default is the name of the system user executing the process.
- `--profile` (_string_) - An AWS profile name.
- `-h, --help` (_boolean_) - Show help information.

### Usage

```bash title="Terminal" showLineNumbers={false}
npx ampx sandbox seed
```

## npx ampx sandbox seed generate-policy

Generates the IAM policy required for seeding operations.

### Options

- `--debug` (_boolean_) - Print debug logs to the console. [default: false]
- `--identifier` (_string_) - An optional identifier to distinguish between different sandboxes. Default is the name of the system user executing the process.
- `--profile` (_string_) - An AWS profile name.
- `-h, --help` (_boolean_) - Show help information.

### Usage

Output the policy to the terminal:

```bash title="Terminal" showLineNumbers={false}
npx ampx sandbox seed generate-policy
```

Save the policy to a file:

```bash title="Terminal" showLineNumbers={false}
npx ampx sandbox seed generate-policy > seed-policy.json
```

## 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:

```bash title="Terminal" showLineNumbers={false}
# with CloudFormation stack name
npx ampx generate <subcommand> --stack <cloudformation-stack-name>
```

```bash title="Terminal" showLineNumbers={false}
# 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`](#npx-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:

```bash title="Terminal" showLineNumbers={false}
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`:

```bash title="Terminal" showLineNumbers={false}
npx ampx generate outputs --stack amplify-nextamplifygen2-josef-sandbox-ca85e1081b --format dart
```

#### Use with pre-existing branch

If you have a pre-existing branch that you want to generate outputs for, you can use the `--branch` with the `--app-id` flag:

```bash title="Terminal" showLineNumbers={false}
npx ampx generate outputs --branch staging --app-id <your-amplify-app-id>
```

## 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.
- `--statement-max-depth`(_integer_) - Specifies the maximum depth of the generated GraphQL statements. 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. 

```bash title="Terminal" showLineNumbers={false}
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:

```bash title="Terminal" showLineNumbers={false}
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)

```ts title="lib/stack.ts" showLineNumbers={false}
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

```bash title="Terminal" showLineNumbers={false}
npx cdk deploy
```

Run Amplify codegen command to generate GraphQL codegen:

```bash title="Terminal" showLineNumbers={false}
npx ampx generate graphql-client-code --stack Backend --platform ts --out ./src
```

#### Generate codegen in specific language and format

```bash title="Terminal" showLineNumbers={false}
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 schema-from-database

Generates typescript data schema from a SQL database.

### 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`(_string_) - A path to directory where generated schema is written [default: `./amplify/data/schema.sql.ts`].
- `--connection-uri-secret`(_string_) - Amplify secret name for the database connection uri.
- `--ssl-cert-secret`(_string_) - Amplify secret name for the database ssl certificate.
- `--profile`(_string_) - An AWS profile name.

### Usage

```bash title="Terminal" showLineNumbers={false}
npx ampx generate schema-from-database --connection-uri-secret SQL_CONNECTION_STRING --out amplify/data/schema.sql.ts
```

## 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

```bash title="Terminal" showLineNumbers={false}
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.

```bash title="Terminal" showLineNumbers={false}
npx ampx info
```

This command will print system information as follows:

```bash title="Terminal" showLineNumbers={false}
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

```bash title="Terminal" showLineNumbers={false}
npx ampx pipeline-deploy --branch $BRANCH_NAME --app-id $AWS_APP_ID
```