Ampli is Amplitude's command line app. Ampli works with the Amplitude Data web app and helps developers correctly instrument tracking code in their apps.

## Install Ampli

Install Ampli from Homebrew or npm.

{% tabs tabs="Homebrew, npm" %}
{% tab name="Homebrew" %}
Add the `amplitude/ampli` tap and then install `ampli`. You only need to add the tap one time.

```shell
brew tap amplitude/ampli
brew install ampli
```

To upgrade, run:

```shell
brew upgrade ampli
```

{% /tab %}
{% tab name="npm" %}

```shell
npm install -g @amplitude/ampli
```

Amplitude recommends installing Node with [Homebrew](https://brew.sh/) and `brew install node`. Ampli requires Node v8.2.0+.
{% /tab %}
{% /tabs %}

## Initialize and connect Ampli and Amplitude Data

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

```shell
ampli pull
```

A browser window opens and automatically logs you in or prompts 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.

```bash
➜ ampli pull
Ampli project is not initialized. No existing `ampli.json` configuration found.
? Create a new Ampli project here? Yes
? Organization: My Organization
? Workspace: My Workspace
? Source: My Web Source
? Platform: Browser
? Language: TypeScript
? SDK: @amplitude/analytics-browser@^1.0
? Branch: main
✔ Pulling latest version (1.0.0)...
✔ Tracking library generated successfully.
  ↳ Path: ./src/ampli
```

## Generate your analytics SDK

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.

```shell
ampli pull {source-name}
```

The pull command takes one optional argument: the name of a source 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. The autogenerated SDK includes events associated with that source. The SDK excludes events not associated with that source. Source-specific SDKs help Amplitude track your events consistently across all sources.

The pull command also tells you what changed since the last time you pulled your team's analytics spec. Use this information to update your analytics instrumentation.

As your project progresses, you and your team make changes to your tracking plan. Amplitude Data notifies you when something changes. When you're ready, pull the changes and incorporate them into your project.

## Instrument your product

After you have pulled down the latest tracking plan, learn how to [instrument your product](/docs/sdks/analytics).

## Verify the instrumentation

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

```shell
ampli status --update
```

The verify command scans your source code for tracking calls and compares the results to 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](/docs/sdks/ampli/validate-in-ci) to automatically run the `ampli status` command at check-in.

## Ampli commands

### Pull

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

```shell
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 and 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, Ampli places your tracking library 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.

```shell
ampli 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. To generate a tracking library for another version, include `-v {version}` and specify the tracking plan's version.

### Initial pull permissions

When you create a source in Amplitude Data without selecting a specific language, such as Browser or iOS, the source starts in a platform-only runtime state. In this state, Ampli doesn't yet know which language-specific client library to generate.

The first time you initialize such a source, the CLI must resolve and save the exact runtime (platform + language). The write operation updates source metadata in Amplitude and requires Manager or Admin permissions. Because the write operation requires elevated permissions, a non-admin `ampli pull` can fail for sources that don't have configuration yet, even though the command uses the name `pull`.

Use one of the following options to resolve the permissions:

#### Option 1: Run the first `ampli pull` with elevated permissions

Have a user with Manager or Admin access run the first `ampli pull` for the source. The first pull configures and persists the runtime. After that, non-admin developers can use `ampli pull` normally.

#### Option 2: Run `ampli configure` one time, then let members use `ampli pull`

Have a user with Manager or Admin access run:

```shell
ampli configure
```

Complete the prompts for platform, language, and SDK. After an Admin or Manager runs `ampli configure` for the source and fully sets the runtime, subsequent `ampli pull` runs are read-only and work as expected for developers with Member role permissions.

### Status

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

```bash
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, locates all calls to the Ampli tracking library, and tells you which events you're tracking and which events 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 developers first implemented events, when Ampli last detected them in the source code, and where the code tracks them.

If you're integrating Ampli into CI, there are typically two pipelines you 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 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 someone creates a pull/merge request for a branch. To verify instrumentation in this generic case, run `ampli status -u --skip-update-on-default-branch`. The command verifies against the current branch. The command only updates the tracking plan instrumentation status for branches other than **main**, which keeps status of events in development out of the main tracking plan.

If your code tracks all events, `ampli status` passes and returns an exit code of 0. Otherwise, `ampli status` fails and returns the number of events that aren't tracked.

### Configure

Configure and update source runtime. Follow the prompts to select a specific platform, language, and underlying Amplitude SDK.

```text
➜ ampli configure
? Select a platform: Browser
? Select a language: TypeScript
? Select a SDK: @amplitude/analytics-browser@^1.0 (recommended)
✔ Successfully configured source.
```

```shell
USAGE
  $ ampli configure
OPTIONS
  None
EXAMPLES
  $ ampli configure
```

### Init

Initialize your workspace.

```shell
USAGE
  $ 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]
```

### Help

Display help for Ampli.

```shell
USAGE
  $ ampli help [command]
```

### Whoami

Display information about the user.

```shell
USAGE
  $ ampli whoami
```

The `whoami` command displays information about the current logged-in user.

### All Ampli commands

Find all available `ampli` commands in the [`@amplitude/ampli` package](https://www.npmjs.com/package/@amplitude/ampli).

## Use Ampli with a monorepo

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.

{% callout type="example" heading="" %}
You have two sources, `web` and `backend`, in the same repo.

```shell
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.

{% /callout %}