Page updated Mar 28, 2024

Explore key workflows for Amplify CLI

Initialize new project

To initialize a new Amplify project, run the following command from the root directory of your frontend app.

1amplify init

The init command goes through the following steps:

  • Analyzes the project and confirms the frontend settings
  • Carries out the initialization logic of the selected frontend
  • If there are multiple provider plugins, prompts to select the plugins that will provide accesses to cloud resources
  • Carries out, in sequence, the initialization logic of the selected plugin(s)
  • Insert amplify folder structure into the project's root directory, with the initial project configuration
  • Generate the project metadata files, with the outputs of the above-selected plugin(s)
  • Creates a cloud project in the AWS Amplify Console to view and manage resources for all backend environments.

Clone sample Amplify project

To clone a sample amplify fullstack project, execute the following command inside an empty directory:

amplify init --app <github-url>

where <github-url> is a valid sample Amplify project repository. Click here for more details.

Common CLI commands

amplify init

The init command can determine defaults for the project based on the contents of the directory. To accept the defaults offered, answer yes to:

Initialize the project with the above configuration?

During the init process, the root stack is created with three resources:

  • IAM role for unauthenticated users
  • IAM role for authenticated users
  • S3 bucket, the deployment bucket, to support this provider's workflow

The provider logs the information of the root stack and the resources into the project metadata file (amplify/backend/amplify-meta.json).

amplify <category> add

Once init is complete, run the command amplify <category> add to add resources of a category to the cloud. This will place a CloudFormation template for the resources of this category in the category's subdirectory amplify/backend/<category> and insert its reference into the above-mentioned root stack as the nested child stack. When working in teams, it is good practice to run an amplify pull before modifying the backend categories.

amplify push

Once you have made your category updates, run the command amplify push to update the cloud resources. The CLI will first upload the latest versions of the category nested stack templates to the S3 deployment bucket, and then call the AWS CloudFormation API to create / update resources in the cloud. Based upon the resources added/updated, the aws-exports.js file (for JS projects) and the awsconfiguration.json file (for native projects) gets created/updated. The root stack's template can be found in amplify/backend/awscloudformation.

amplify pull

The amplify pull command operates similar to a git pull, fetching upstream backend environment definition changes from the cloud* and update the local environment to match that definition. The command is particularly helpful in team scenarios when multiple team members are editing the same backend, pulling a backend into a new project, or when connecting to multiple frontend projects that share the same Amplify backend environment.

* The CLI will use the S3 deployment bucket to retrieve your project information including the CloudFormation templates from the last successful amplify push.

To generate client configuration files (aws-exports.js, amplifyconfiguration.json, or amplifyconfiguration.dart) for an existing project that is listed in the Amplify Hosting console, or to checkout a backend environment that has not been pulled locally:

  1. Log in to the AWS console
  2. Choose AWS Amplify
  3. Click your app
  4. Go to Backend environments
  5. Find the backend environment you wish to pull
  6. Click Edit backend
  7. Run the command that is listed (amplify pull --appId YOUR_APP_ID --envName YOUR_ENV_NAME)

amplify console

The amplify console command launches the browser directing you to your cloud project in the AWS Amplify Console. The Amplify Console provides a central location for development teams to view and manage their backend environments, status of the backend deployment, deep-links to the backend resources by Amplify category, and instructions on how to pull, clone, update, or delete environments.

amplify configure project

The amplify configure project command is an advanced command and not commonly used for initial getting started projects. The command should be used to modify the project configuration present in the .config/ directory and re-configuring AWS credentials (based on profile on your local machine) set up during the amplify init step. The .config/ directory is generated in the amplify/ directory, if not already present, and the local-aws-info.json, local-env-info.json and project-info.json files are configured to reflect the selections made as a part of the amplify configure project command.

amplify configure project is also used to enable Serverless Container options in your project with Amazon Elastic Container Service. When enabled, you will be able to build APIs with both AWS Lambda and AWS Fargate using a Dockerfile or a Docker Compose file. See Serverless Containers for more information.

amplify logout --appId <Amplify Project Id>

When Amplify CLI is authenticated with Amplify Studio, JSON Web Tokens (JWTs) are stored on the developer's machine. This command will remove the JWTs associated with a particular Amplify project. The CLI will also prompt if you want to logout from all sessions. 'Yes' will remove the JWTs and ensure they are invalidated globally. 'No' will still remove the locally-stored JWTs but the tokens will remain valid until they expire.

Upgrade Amplify CLI

The Amplify CLI team continuously pushes new features, enhancements and security improvements and it is recommended to update the Amplify CLI version which you or your team is using to the latest version. You can keep track of the latest releases of the Amplify CLI on npm -

1npm install -g @aws-amplify/cli
1amplify upgrade
1amplify upgrade

Verify Amplify CLI upgrade

Verify the successful installation of the latest CLI version by entering the following command in the CLI:

1amplify -v

Confirm the installed version of the Amplify CLI. You can find the latest version of the CLI here -

(Optional) Update projects using latest Amplify CLI

Navigate to your Amplify project folder using the following command cd <Project-Filepath>. To verify if it is a valid Amplify project folder, enter the following command in the CLI:

1amplify status

If it is a valid Amplify project folder, Amplify will display a list of the resources in the project folder that you have deployed to the AWS cloud.

Update your backend resources with updated security configurations or improvements by entering the following command in the CLI:

1amplify push --force

Hit Enter or type Y when prompted for confirmations. Look for the following result to validate the configuration updates have been applied.

1✔ All resources are updated in the cloud

If you have multiple AWS Amplify project folders, repeat steps above for each project folder.

If you are receiving errors on push regarding unknown GraphQL directives and have not yet migrated your GraphQL resource to use GraphQL Transformer v2, please review the migration documentation page for an in-depth guide to migrating the resource.

Uninstall Amplify CLI

Use the following commands to completely remove Amplify CLI from your system. Removing the Amplify CLI will NOT delete any of your Amplify projects. To delete a project, run amplify delete within the project directory.

1npm uninstall -g @aws-amplify/cli
1amplify uninstall
1amplify uninstall

List of commands

  • amplify <category> <subcommand>
  • amplify push
  • amplify pull
  • amplify env <subcommand>
  • amplify configure
  • amplify console
  • amplify delete
  • amplify help
  • amplify init
  • amplify publish
  • amplify run
  • amplify status
  • amplify logout

Category commands

  • amplify <category> add
  • amplify <category> update
  • amplify <category> remove
  • amplify <category> push

Secrets scanning

When working with secrets in your Amplify project it is important to safeguard your secrets from being committed to version control. If you use git, we recommend using git-secrets from AWS Labs. Once installed, it will scan your local repository for secrets and prevent you from committing them.