Skip to content

Ampli CLI

Ampli is Amplitude's command line app. It works hand-in-hand with the Amplitude Data web app and enables developers to quickly and correctly instrument tracking code in their apps.

Set Up Ampli

Step 1: Install Ampli

You can install Ampli from Homebrew or NPM.

Add the amplitude/ampli tap and then install ampli. You only need to add the tap once.

brew tap amplitude/ampli
brew install ampli

To upgrade, run:

brew upgrade ampli
npm install -g @amplitude/ampli

Install Node & NPM

We recommend installing Node via Homebrew by running brew install node. Ampli requires v8.2.0+.

Step 2: Initialize and connect Ampli and Amplitude Data

Now that you have Ampli installed, cd into your project's root folder and initialize it with:

ampli pull

A browser window opens and automatically logs you in or prompt you for your credentials. Ampli stores your project-specific settings in ampli.json and your user-specific settings (such as your credentials) in ~/ampli.json. Depending on your Amplitude organization settings, the CLI might prompt you to choose your Organization and/or Workspace.

Step 3: Generate your analytics SDK

Now that you're done setting Ampli up, you’re ready to generate your analytics SDK. The ampli pull command looks at the events and properties you've defined in your Amplitude Data account (this is also commonly referred to as a tracking plan) and auto-generates a matching type-safe analytics library for you to use.

ampli pull {source-name}

The pull command takes one argument: the name of a source created in your Amplitude Data account. For example, a source might be ios, android, web, or backend. Events associated with a particular source will appear in the auto-generated SDK. Those that aren't will not. This makes sure your events are tracked consistently on all the sources you'd like to track them on.

The pull command also tells you what, if anything, has changed since the last time you pulled your team's analytics spec. You can use this as a guide for getting your analytics instrumentation up-to-date.

As your project progresses, you and your team will inevitably make changes to your tracking plan. Amplitude Data notifies you when those changes are made and when you’re ready, you can pull down the changes and incorporate them into your project.

Step 4: Instrument your product

After you have pulled down the latest tracking plan, learn how to instrument your product.

Step 5: Verify the instrumentation

To make sure you’re tracking all the right events, and that you’re tracking those events correctly, Ampli can lint your source code and warn you about any errors. For example, Ampli can tell if you’ve forgotten to track any required events, or if you’re not passing along all required properties.

ampli status --update

The verify command scans your source code for tracking calls and compare the results to what's expected per your team's tracking plan. Include --update to update your company's tracking plan online and share the latest analytics implementation status with your team. If the command reports all green, you're all good!

You can configure your CI pipeline to automatically run the ampli status command at check-in so you never miss another analytics bug again.

View real time events sent from your source application. See the Debug Analytics resource guide.

Ampli CLI Commands

ampli pull

Pull down the latest tracking plan and generate a tracking library.

USAGE
  $ ampli pull [<source>] [-p <path>] [-b <branch>]

OPTIONS
  -b, --branch=branch    the branch to pull
  -p, --path=path        where the tracking library will be created
  -t, --token=token      personal API token to authenticate with
  -v, --version=version  the version to pull
  --include-api-keys     include api keys to the tracking library (default true)
  --omit-api-keys        omit api keys from the tracking library (default false)

EXAMPLES
  $ ampli pull
  $ ampli pull web
  $ ampli pull web -p ./ampli -b develop
  $ ampli pull web -p ./ampli -b develop -v 2.1.1
  $ ampli pull --omit-api-keys
  $ ampli pull --include-api-keys

Run this command in the root folder of your project. For example:

  • Browser & Node.js: the folder with your package.json
  • iOS: the folder with your Info.plist
  • Android: the folder with your {project-name}.iml

By default, your tracking library will be placed in:

Platform Default location
Browser ./src/ampli
Node.js ./src/ampli
iOS ./ampli
Android ./app/src/main/java/com/amplitude/ampli
JRE ./src/main/java/com/amplitude/ampli

To override the default location, pass the -p argument. Ampli will remember your custom location and use it going forward.

ampli pull web -p ./src/analytics

Include -b {branch} to generate a tracking library from a particular branch, rather than main. By default, the last published version will be used. If you'd like to generate a tracking library for another version, include -v {version} and specify the tracking plan's version.

ampli status

Check the status of your instrumentation by linting (verifying) your source code for analytics.

USAGE
  $ ampli status

OPTIONS
  -b, --branch=branch                enforces source is on provided the branch
  -t, --token=token                  personal API token to authenticate with
  -u, --update                       update tracking plan with latest implementation status
  --instanceName                     Ampli instance name(s) to check. Default is "ampli".
  --is-latest                        check if current version is the latest
  --is-latest-if-not-default-branch  check if current version is the latest (do not check if on default branch)
  --is-merged                        check if current branch/version has been merged into default branch
  --skip-update-on-default-branch    prevents updating implementation status on default branch
  --sourceDir                        source code location(s). Default is current directory.

EXAMPLES
  $ ampli status
  $ ampli status -u
  $ ampli status -b main
  $ ampli status -u --skip-update-on-default-branch
  $ ampli status --instanceName myAmpliInstance
  $ ampli status --is-merged
  $ ampli status --sourceDir ./src ./util

Run this command in the root folder of your project. The command scans your source files, locate all calls to the Ampli tracking library, and let you know which events are being tracked, and which have yet to be instrumented.

Include -u to update your company's tracking plan in Amplitude Data and share the latest analytics implementation status with your team. Your teammates will be able to tell when events were first implemented, the last time they've been detected in the source code, and where exactly in the source code they are tracked.

If you're integrating Ampli into CI, there are typically two pipelines you'll want to run ampli status in:

  1. Your production branch pipeline that runs when pull/merge requests get merged into your main/default branch (typically main). To make sure the code being checked there is correct and from Amplitude Data's main branch, run ampli status -u -b main. If the Amplitude Data branch instrumented in your source code isn't main, the command fails; otherwise, it updates the main branch's tracking plan.
  2. Your pull/merge request pipeline that runs when a pull/merge request is created for a branch. To verify instrumentation in this generic case, run ampli status -u --skip-update-on-default-branch. The command will verify against the current branch but will only update the tracking plan instrumentation status for branches other than main. This safely keeps status of events in development out of the main tracking plan.

ampli status passes and returns an exit code of 0 if all events are tracked as expected, or fails and returns the number of events that aren't.

ampli init

Initialize your workspace.

SAGE
  $ ampli init

OPTIONS
  -o, --org=org              organization
  -w, --workspace=workspace  workspace
  --user=user                user email

EXAMPLES
  $ ampli init [--org ORGANIZATION] [--workspace WORKSPACE]
  $ ampli init [--user username@some.domain]

ampli help

Display help for Ampli.

USAGE
  $ ampli help [command]

ampli whoami

Display information about the user.

USAGE
  $ ampli whoami

The whoami command displays information about the currently logged in user.

All ampli Commands

Find all ampli commands available here

Use Ampli with a monorepo

The Ampli CLI is designed to work with a single source per project (folder). For single source projects, we recommend running ampli pull from the root directory of the repo.

In monorepos with multiple sources, you must run ampli pull and ampli status from each source's folder.

Example

You have two sources: web and backend that are used in the same repo.

monorepo/
  web/
    ampli.json (for Browser source)
    package.json
  backend/
    ampli.json (for Node source)
    package.json

You run ampli pull in web/ for Browser and again in backend/ for Node.

To verify instrumentation status run cd ~/monorepo/web && ampli status for Browser, and cd ~/monorepo/backend && ampli status for Node.


Last update: 2022-07-25