@zeroheight/adoption-cli

@zeroheight/adoption-cli

CLI for measuring component usage to view in your zeroheight account.

For full walk through on how to use this CLI tool, head over to our help centre article.

Release notes

Install

npm i @zeroheight/adoption-cli

Usage

Authentication

Interactive mode

When running a command, you will be prompted to authenticate. This will save the Client ID and Access Token to your local machine.

Alternatively, you can authenticate by running the following command:

zh-adoption auth

Non-interactive mode

When running a command with the --interactive false flag, you will need to provide the Client ID and Access Token as environment variables.

export ZEROHEIGHT_CLIENT_ID="your-client-id"
export ZEROHEIGHT_ACCESS_TOKEN="your-access-token"

Error logging

When running a command with the --log-level <level> --log-file ./my-log-file.log flags, diagnostic information will be written to a file. This can help diagnose issues and can be optionally shared with zeroheight directly to help resolve. If you don't specify --log-file, logs will be output to stderr.

There are 4 levels of increasing severity:

• info
• warn
• error
• fatal

Note: You will see logs for the specified level and those from the higher severity groups. For example, if you you choose --log-level error then the error and fatal level logs will be surfaced.

Telemetry

To help improve the experience this CLI uses Sentry for error tracking. If you don't want to share error data, you can disable it by setting the environment variable ZEROHEIGHT_CLI_DISABLE_TELEMETRY=true

Color usage analysis

Help center article

In the repository in which you wish to get usage metrics around how raw color values are being used, run the following command:

zh-adoption analyze --color-usage

Component usage analysis

Help center article

In the React repository in which you wish to get usage metrics around how components from your design system packages are being used, run the following command:

zh-adoption analyze --component-usage

Analyze command options

-e / --extensions

Provide a glob pattern to search for files with a specific extension.

zh-adoption analyze -e "**/*.{js,jsx,ts,tsx}"

-i / --ignore

Provide a glob pattern to ignore files, directories or file extensions when analyzing.

zh-adoption analyze -i "**/*.{test,spec}.*"

To pass multiple patterns, use the option multiple times e.g.

zh-adoption analyze -i "**/*.{test,spec}.*" -i "**/*.d.ts"

To ignore nothing, even the default patterns (['**/*.{test,spec}.*', '**/*.d.ts']), pass an empty value

zh-adoption analyze -i

-r / --repo-name

Provide a name for the current repository. This must be passed when -in / --interactive is set to false.

zh-adoption analyze -r "My Repo"

-in / --interactive

Pass in false to disable the interactive mode e.g. when running in a CI environment.

zh-adoption analyze --interactive false -r "My Repo"

--log-level

Provide a severity to output diagnostic messages.

zh-adoption analyze --log-level info

Write logs to a file so they can read and/or shared later.

--log-file

zh-adoption analyze --log-file ./dev.log

--dry-run

Run the command in dry run mode, which allows output to be viewed without sending data to zeroheight.

zh-adoption analyze --dry-run

Monitor repo

Help center article

This will analyze your code repository to help you understand what packages are being used and at what version.

In the repository in which you wish to monitor, run the following command:

zh-adoption monitor-repo

Options

-d / --dir

Provide a path to the specific folder to find package.json and lock file. This option can be passed through multiple times. If not included all folders with package.json and lockfile will be uploaded to zeroheight.

zh-adoption monitor-repo -d ./webApp

-p / --package-name

Provide a name for the current package.

zh-adoption monitor-repo -p "My Package"

--log-level

Provide a severity to output diagnostic messages.

zh-adoption monitor-repo --log-level info

Write logs to a file so they can read and/or shared later.

--log-file

zh-adoption monitor-repo --log-file ./dev.log

--dry-run

Run the command in dry run mode, which allows output to be viewed without sending data to zeroheight.

zh-adoption monitor-repo --dry-run

Track package

Help center article

This will give zeroheight the name and current version of your design system package so you can compare it to the version being used by your other code repositories.

In the repository containing your design system package, run the following command:

zh-adoption track-package

Options

-in / --interactive

Pass in false to disable the interactive mode e.g. when running in a CI environment.

zh-adoption track-package --interactive false

-p / --packages

Provide one or multiple package names to match when searching for design system packages. This must be passed when -in / --interactive is set to false.

zh-adoption track-package -in false -p package1 -p package2 -p package3

zh-adoption track-package -in false --packages package1,package2,package3

--log-level

Provide a severity to output diagnostic messages.

zh-adoption track-package --log-level info

Write logs to a file so they can read and/or shared later.

--log-file

zh-adoption track-package --log-file ./dev.log

--dry-run

Run the command in dry run mode, which allows output to be viewed without sending data to zeroheight.

zh-adoption track-package --dry-run

More info on the commands can be seen by running

zh-adoption --help