# Using the Avo CLI

The [Avo command line interface](https://github.com/avohq/avo) provides a way to pull custom analytics wrappers from Avo. The CLI is designed to make developers more productive when implementing analytics.

> 💡 Editors and admins can pull generated code on all plans: free, team and enterprise. Additionally, viewers can pull generated code on the team and enterprise plans. Learn more [here](https://www.avo.app/docs/workspace-management/members.md#codegen-access-for-non-editors).

## Quickstart

### Step 1: Install the Avo CLI

```bash npm2yarn
npm install -g avo
```

After installing, verify everything is in working order by running `avo --version`.

```bash
avo --version
1.3.6
```

### Step 2: Link your Avo account

Once you have installed the Avo CLI, run `avo login` to link your Avo account with the CLI.

```bash
avo login
```

After you have successfully linked your account, run `avo whoami` to see the linked account.

```bash
avo whoami
Logged in as my@account.com
```

### Step 3: Pull generated analytics wrappers from Avo

To pull generated analytics wrappers from Avo, run `avo pull`. It will fetch the latest analytics wrappers based on your tracking plan on avo.app.

When you run this command for the first time it will prompt you to select which Avo source you would like to generate code for and where you would like to save it. This configuration will be stored in the `avo.json` file and you can always change it later.

Please commit the `avo.json` file into your version control, in order to keep it in sync across your team.

```bash
avo pull [--branch "my-branch"] [--force] [--forceFeatures ...,...] [SourceName]
```

Options:

```bash
  --branch         Name of Avo branch to pull from,
  --force          Proceed ignoring the unsupported features for given source type (e.g. group analytics)
  --forceFeatures  A list of experimental codegen features to force enable. Pass unsupported name to get the list of available features
```

### Step 4: Monitor the analytics implementation

Once you have implemented analytics with the Avo analytics wrappers, you can check the status of the implementation by running `avo status`.

The `status` command will report on where the analytics functions provided by Avo are being called, and which events have not been implemented yet.

```bash
avo status
```

The output of this command will show you all the Avo function calls in your codebase and will highlight functions that are never called. If one or more functions from Avo Codegen are not called in the code the command will fail.

```sh
> avo status
info Currently on branch 'main'
└─ java android (musicplayerexample/src/main/java/sh/avo/Avo.java)
   ├─ appOpened
   │  └─ used in musicplayerexample/src/main/java/app/avo/musicplayerexample/MusicPlayerExampleApplication.kt: 1 time
   ├─ login
   │  └─ ✖ no usage found
   ├─ logout
   │  └─ ✖ no usage found
   ├─ pause
   │  └─ used in musicplayerexample/src/main/java/app/avo/musicplayerexample/ExampleMusicPlayerActivity.kt: 1 time
   ├─ play
   │  └─ used in musicplayerexample/src/main/java/app/avo/musicplayerexample/ExampleMusicPlayerActivity.kt: 3 times
   ├─ playNextTrack
   │  └─ used in musicplayerexample/src/main/java/app/avo/musicplayerexample/ExampleMusicPlayerActivity.kt: 1 time
   └─ playPreviousTrack
      └─ used in musicplayerexample/src/main/java/app/avo/musicplayerexample/ExampleMusicPlayerActivity.kt: 1 time
info 5 of 7 events seen in code
error 2 missing events
└─ java android (musicplayerexample/src/main/java/sh/avo/Avo.java)
   ├─ login: no usage found
   └─ logout: no usage found
```

If you run `avo status --verbose` it will also print a list of files where the CLI searched for the functions from Avo Codegen.

Here is an example beginning of the verbose output:

```sh
info Currently on branch 'main'
Looking in files with extensions: [ 'java', 'kt' ]
info Looking for events in src/main/java/app/avo/musicplayerexample/ExampleMusicPlayerActivity.kt
info Looking for events in src/main/java/app/avo/musicplayerexample/ExampleMusicPlayerLogic.kt
info Looking for events in src/main/java/app/avo/musicplayerexample/MusicPlayerExampleApplication.kt
info Looking for events in src/main/java/app/avo/musicplayerexample/MusicStorage.kt
info Looking for events in src/main/java/app/avo/musicplayerexample/Player.kt
...
```

### Interface files

Some languages allow you to generate multiple files, for example Objective-C requires it and you can enable it in Kotlin and Swift using on-demand feature flags. For Kotlin use `SplitKtFiles` and for Swift it's `SplitSwiftFiles` [see --forceFeatures pull flag above](https://www.avo.app/docs/implementation/cli.md#step-3-pull-generated-analytics-wrappers-from-avo).

When initializing a source with CLI v3.2.0 and later it will ask you to specify a separate path for the interface file.

You can also specify the interface file path manually, by adding `interfaceFilePath` field to the `source` object in the `avo.json` file

```json
"sources": [
  {
    "id": "...",
    "name": "Android Kotlin",
    "path": "Avo.kt",
    "interfacePath": "interface/AvoInterface.kt",
    "actionId": "...",
    "branchId": "...",
    "updatedAt": "..."
  }
]
```

## Using Avo Branches

When editing your tracking plan on avo.app you can branch out from the main tracking plan to make changes in isolation, just like with git. To pull analytics wrappers from an open Avo branch you first need to switch to that branch with `avo checkout`.

```bash
avo checkout my-branch-name
```

You can also pull from a specific branch by using the `--branch` flag when running `avo pull`

```bash
avo pull [my-source-name] --branch my-branch-name
```

### Using an Avo branch with a git branch

Here is the workflow we recommend when working on Avo branches with git branches.

1. On your git branch, pull updated analytics wrappers from the Avo branch you would like to implement

```bash
avo pull [my-source-name] --branch my-branch-name
```

2. Once ready to merge, make sure your Avo branch is up to date with Avo main by pulling latest main changes into your branch. This can also be done from the branch review screen on avo.app.
   If any changes were pulled in, make sure to run `avo pull` again to update the analytics wrappers

```bash
avo merge main
```

3. Review and merge your git branch

4. Immediately after merging the git branch, merge the Avo branch from the branch review screen on avo.app

## Git Conflicts in Avo Files

To resolve git conflicts in `avo.json` run `avo pull`. It will attempt to resolve the git conflicts in `avo.json` automatically and check whether the incoming branch has been merge and if your current branch is up to date with Avo main before pulling latest analytics wrappers.

```bash
avo pull
```

As an alternative you can also run `avo conflict`, it will resolve any conflicts in `avo.json` without pulling latest analytics wrappers.

```bash
avo conflict
```

## Complete Reference

Below is the complete documentation for all available commands:

```bash
avo --help
avo command

Commands:
  avo init               Initialize an Avo workspace in the current folder
  avo pull [source]      Pull analytics wrappers from Avo workspace
  avo checkout [branch]  Switch branches [aliases: branch]
  avo source <command>   Manage sources for the current project
  avo status [source]    Show the status of the Avo implementation
  avo merge main         Pull Avo main branch into your current branch
  avo conflict           Resolve git conflicts in Avo files [aliases: resolve, conflicts]
  avo edit               Open the Avo workspace in your browser
  avo login              Log into the Avo platform
  avo logout             Log out from the Avo platform
  avo whoami             Shows the currently logged in username

Options:
  --version      Show version number [boolean]
  -v, --verbose  make output more verbose [boolean] [default: false]
  -f, --force    Proceed with merge when incoming branch is open [boolean] [default: false]
  --help         Show help [boolean]
```

To report any issues or suggest changes, go to [https://github.com/avohq/avo](https://github.com/avohq/avo)