Ampli is Amplitude's command line app. It works hand-in-hand with the Amplitude Data web app and enables developers to correctly instrument tracking code in their apps.
Install Ampli from Homebrew or npm.
Add the amplitude/ampli
tap and then install ampli
. You only need to add the tap once.
1brew tap amplitude/ampli2brew install ampli
To upgrade, run:
1brew upgrade ampli
1npm install -g @amplitude/ampli
Amplitude recommends installing Node with Homebrew and brew install node
. Ampli requires Node v8.2.0+.
Now that you have Ampli installed, cd
into your project's root folder and initialize it with:
1ampli 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 or Workspace.
1➜ ampli pull 2Ampli project is not initialized. No existing `ampli.json` configuration found. 3? Create a new Ampli project here? Yes 4? Organization: My Organization 5? Workspace: My Workspace 6? Source: My Web Source 7? Platform: Browser 8? Language: TypeScript 9? SDK: @amplitude/analytics-browser@^1.010? Branch: main11✔ Pulling latest version (1.0.0)...12✔ Tracking library generated successfully.13 ↳ Path: ./src/ampli
The ampli pull
command looks at the events and properties you've defined in your Amplitude Data account (also known as a tracking plan). Ampli uses this information to create a matching type-safe analytics library for you to use.
1ampli pull {source-name}
The pull command takes one (optional) argument: the name of a source created in your Amplitude Data account. For example, a source might be ios
, android
, web
, or backend
. Follow the prompt options to configure a newly created source. Events associated with a particular source appear in the autogenerated SDK. Those that aren't don't. This makes sure Amplitude tracks your events consistently across all sources you 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 make changes to your tracking plan. Amplitude Data notifies you when something changes and when you’re ready, you can pull down the changes and incorporate them into your project.
After you have pulled down the latest tracking plan, learn how to instrument your product.
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.
1ampli 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.
You can configure your CI pipeline to automatically run the ampli status
command at check-in.
Pull down the latest tracking plan and generate a tracking library.
1USAGE 2 $ ampli pull [<source>] [-p <path>] [-b <branch>] 3 4OPTIONS 5 -b, --branch=branch the branch to pull 6 -p, --path=path where the tracking library will be created 7 -t, --token=token personal API token to authenticate with 8 -v, --version=version the version to pull 9 --include-api-keys include api keys to the tracking library (default true)10 --omit-api-keys omit api keys from the tracking library (default false)11 12EXAMPLES13 $ ampli pull14 $ ampli pull web15 $ ampli pull web -p ./ampli -b develop16 $ ampli pull web -p ./ampli -b develop -v 2.1.117 $ ampli pull --omit-api-keys18 $ ampli pull --include-api-keys
Run this command in the root folder of your project. For example:
By default, your tracking library is 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 retains your custom location and uses it going forward.
1ampli pull web -p ./src/analytics
Include -b {branch}
to generate a tracking library from a particular branch, rather than main. By default, Ampli uses the last published version. If you'd like to generate a tracking library for another version, include
-v {version}
and specify the tracking plan's version.
Check the status of your instrumentation by linting (verifying) your source code for analytics.
1USAGE 2 $ ampli status 3 4OPTIONS 5 -b, --branch=branch enforces source is on provided the branch 6 -t, --token=token personal API token to authenticate with 7 -u, --update update tracking plan with latest implementation status 8 --instanceName Ampli instance name(s) to check. Default is "ampli". 9 --is-latest check if current version is the latest10 --is-latest-if-not-default-branch check if current version is the latest (do not check if on default branch)11 --is-merged check if current branch/version has been merged into default branch12 --skip-update-on-default-branch prevents updating implementation status on default branch13 --sourceDir source code location(s). Default is current directory.14 15EXAMPLES16 $ ampli status17 $ ampli status -u18 $ ampli status -b main19 $ ampli status -u --skip-update-on-default-branch20 $ ampli status --instanceName myAmpliInstance21 $ ampli status --is-merged22 $ 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 you're tracking, and which aren't instrumented yet.
Include -u
to update your company's tracking plan in Amplitude Data and share the latest analytics implementation status with your team. Your teammates can tell when events were first implemented, the last time they've
been detected in the source code, and where exactly in the code they're tracked.
If you're integrating Ampli into CI, there are typically two pipelines you want to run ampli status
in:
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.ampli status -u --skip-update-on-default-branch
. The command verifies against the current branch and only updates the tracking plan instrumentation status for branches other than main. This keeps status of events in development out of the main tracking plan.If all events are tracked, then ampli status
passes and returns an exit code of 0. Otherwise, it fails and returns the number of events that aren't tracked.
Configure and update source runtime. Follow the prompts to select a specific platform, language, and underlying Amplitude SDK.
1➜ ampli configure2? Select a platform: Browser3? Select a language: TypeScript4? Select a SDK: @amplitude/analytics-browser@^1.0 (recommended)5✔ Successfully configured source.
1USAGE2 $ ampli configure3OPTIONS4 None5EXAMPLES6 $ ampli configure
Initialize your workspace.
1USAGE 2 $ ampli init 3 4OPTIONS 5 -o, --org=org organization 6 -w, --workspace=workspace workspace 7 --user=user user email 8 9EXAMPLES10 $ ampli init [--org ORGANIZATION] [--workspace WORKSPACE]11 $ ampli init [--user username@some.domain]
Display help for Ampli.
1USAGE2 $ ampli help [command]
Display information about the user.
1USAGE2 $ ampli whoami
The whoami
command displays information about the currently logged in
user.
Find all ampli
commands available here
The Ampli CLI works with a single source per project (folder). For single source projects, Amplitude recommends 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.
You have two sources: web
and backend
that are used in the same repo.
1monorepo/2 web/3 ampli.json (for Browser source)4 package.json5 backend/6 ampli.json (for Node source)7 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.
Thanks for your feedback!
June 28th, 2024
Need help? Contact Support
Visit Amplitude.com
Have a look at the Amplitude Blog
Learn more at Amplitude Academy
© 2024 Amplitude, Inc. All rights reserved. Amplitude is a registered trademark of Amplitude, Inc.