Chartmetric CLI

Getting Started

The Chartmetric CLI helps you access, test, and build with the Chartmetric API.

Now, access the power of Chartmetric from any terminal:

Simple and easy to use. Run directly from the command line.
Fast lookups. Quickly retrieve information without needing to launch any applications or services.
Chartmetric CLI is FREE to use (however you will need an active Chartmetric API subscription).

Jump to the Installation section to download the binaries. Refer to the CLI Documentation for a list of available commands.

You will need a valid Chartmetric API refresh token for this tool to work correctly.

Refresh tokens are available to Chartmetric API subscribers (rate limits will vary based on your plan).

Trial API subscriptions are available for new users looking to evaluate if the Chartmetric API is the right fit for your project (limited to 1 req/sec up to a maximum of 1000 requests per day).

Disclaimer

The Chartmetric CLI is in a beta stage and provided without any warranties. As of 18 July, all existing API endpoints to be added have been implemented. Some command line syntax may undergo additional changes before this tool reaches General Availability, but this is expected to be minimal moving forward.

This tool is created by Jay Hung (former chief of engineering for Chartmetric) and not maintained by Chartmetric, so please refrain from pinging the company for support.

Installation

Future plans include installation via popular package managers (such as Homebrew, MacPorts, apt, yum, and others) to make this process easier.

For now, download the appropriate binary package for your operating system:

Then, extract the binary and move the file into a folder in your PATH.

* For MacOS binaries, you will need to first bypass the built-in Gatekeeper security check, as these downloaded binaries are not signed with an Apple Developer certificate. In the future this won’t be necessary when the tool reaches General Availability.

For now, to bypass Gatekeeper:

Download the appropriate MacOS .tar.gz file from the links above
Unzip the file (replace “chartmetric-cli-filename.tar.gz” with the actual filename for your OS):
```
tar -xvf chartmetric-cli-filename.tar.gz
```
Move the binary to a directory in your PATH:
```
sudo mv cm /usr/local/bin
```

Bypass the security warning attribute:

sudo xattr -rd com.apple.quarantine /usr/local/bin/cm

Initial Run

Once installed, run the root command from your terminal to view available commands, flags, and other info:

cm

(if the binary is not in your PATH, you may need to run this as “./cm”)

Refresh Token

The first time you attempt to run a command that queries the Chartmetric API, you will be prompted to enter a Chartmetric API refresh token. This token will be saved to a config file, so you will not need to enter it again.

If you did not enter a valid refresh token, or if you wish to change the refresh token in the future, edit the config file directly at ~/.chartmetric. It should resemble something similar to the following:

access_token: IGNORE_AS_IT_WILL_BE_AUTOFILLED
api_host: https://api.chartmetric.com
refresh_token: ENTER_YOUR_REFRESH_TOKEN_HERE

Test Installation

Once installed, the simplest way to test if the tool works correctly is to run the following command from your terminal:

cm artists list

If you receive a JSON response with the expected information, then the tool is working correctly.

Caveats

A few things worth mentioning:

In general, default values for flags are left to the Chartmetric API to decide.
- Occasionally I break this rule, to enable some commands to generate results with minimal input.
- If you suspect this is affecting your results, simply run the command with explicit values set for all flags.
In some cases, the Chartmetric CLI attempts to normalize some inconsistencies in the Chartmetric API.
- For example, many Chartmetric API endpoints use platform as the name of the parameter that filters by a data source. Some endpoints use source and still other endpoints use domain. The Chartmetric CLI will normalize these to a single flag platform for consistency, and map to the correct API parameters respectively.
- Another example is the use of type vs chart_type vs chart-type to request a specific type of chart. The Chartmetric CLI will normalize these to a single flag type for consistency, and map to the correct API parameters respectively.
- These mappings are highlighted in the appropriate help screens.
In other cases, the Chartmetric CLI will not perform any normalization and simply use the API parameters as named.
- For example, the parameters code2 and country_code are both used across different API endpoints to filter results by a 2-letter country code. For now the CLI leaves these as-is, but if you feel these should be normalized as well, let me know.

Feedback

If the Chartmetric CLI is interesting or useful to you, I would appreciate any feedback to better improve this tool. Let me know at jay@jayhung.com.