Using the Avo CLI
The Avo command line interface (opens in a new tab) 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.
Quickstart
Step 1: Install the Avo CLI
npm install -g 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.
- 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
- 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
-
Review and merge your git branch
-
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 (opens in a new tab)