Using the Avo CLI

The Avo command line interface provides a way to pull custom analytics wrappers from Avo. The CLI is designed to make developers more productive when implementing analytics.

Quickstart

Step 1: Install the Avo CLI

npm install -g avo

pnpm add -g avo

yarn global add avo

bun add --global avo

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

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.

avo login

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

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.

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

Options:

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

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.

> 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:

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.

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

"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.

avo checkout my-branch-name

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

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

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

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.

avo pull

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

avo conflict

Complete Reference

Below is the complete documentation for all available commands:

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