Tidelift CLI Reference

The Tidelift command line interface (Tidelift CLI) provides an alternate way to initiate scans of a repository and check the alignment of a repository with your organization's catalog of approved open-source packages.

Install instructions

Note: A Tidelift account is needed to use Tidelift CLI.

1. Install the CLI tool into your user's binary directory ( ~/bin on Mac & Linux) using the curl command below for your OS.

  • Linux: curl https://download.tidelift.com/cli/tidelift -o ~/bin/tidelift
  • MacOS: curl https://download.tidelift.com/cli/tidelift_darwin -o ~/bin/tidelift
  • Windows: curl https://download.tidelift.com/cli/tidelift.exe -o tidelift.exe -o tidelift.exe 
 2. Provide permissions to run the CLI tool (eg. on Mac & Linux:  chmod +x ~/bin/tidelift)
If ~/bin is in your path, you will be able to use Tidelift CLI by running  tidelift. Otherwise, run     ~/bin/tidelift.

Use case #1: Start a scan from Tidelift CLI

If you are using a catalog, a scan is a permanent snapshot of catalog alignment. Otherwise, scans identify issues as specified in your open source policy. In both cases, a scan can be used with CI/CD to block builds and generates a webpage with a recommended path forward. 

You can start a scan of your repository using the following steps. (Note: If you are using the GitHub integration, initiating scans from CLI is not available.)

  1. Retrieve and store a .tidelift file in your repository's root directory.
  2. From your repository's root directory, use tidelift scan --dry-run. The --dry-run flag shows which supported package files we automatically identified. If these files do not look right, you can also specify the correct package files as arguments (eg. tidelift scan --wait package.json package-lock.json)
  3. Start the scan by running tidelift scan --wait , along with package files listed if necessary.
  4. When the scan completes, you will receive a Scan Details URL with more information about the status of the scan.

If you do not use the the --wait flag, the command will start the scan but not wait until it completes. You can check the status of a scan later by using tidelift status.

Use case #2: Check a repository's alignment from Tidelift CLI

If you are using a Tidelift catalog, you can check alignment (i.e. if a repository is using only approved package releases) quickly using Tidelift CLI. Unlike a scan, using tidelift align does not save a record of the repository's current alignment. It is intended to be used as a faster and low-stakes alternative to tidelift scan.

You can check catalog alignment using the following steps:

  1. Retrieve and store a .tidelift file in your repository's root directory.
  2. From your repository's root directory, run tidelift align
  3. Once the alignment check completes, you will see the percent of package releases in the current repository that are approved in the organization's catalog.
  4. If any package releases are not available, you will see if you should request them using tidelift request --all and/or why they were previously denied.

Using with CI/CD

Tidelift CLI can be used as an alternative to our API to easily integrate scans with your CI/CD. When using Tidelift CLI with a CI/CD workflow, you can use the --json command to output the status of the scan in a machine-readable format.

When using the commands that use package files (e.g. scan, align), we highly recommend explicitly passing these files paths as arguments.

Commands and options

Command Structure

tidelift command [command options] [arguments...]

Scan

scan

The scan command starts a new scan for a repository. If you are using a catalog, a scan is a permanent snapshot of catalog alignment. Otherwise, scans identify issues as specified in your open source policy. In both cases, a scan can be used with CI/CD to block builds and generates a webpage with a recommended path forward. 

Options

--json Return JSON instead of formatted plaintext. (default: false)

--debug Print debug information about API responses, loaded files, and more. (default: false)

--team value (required, if not stored in .tidelift) Team name, can be found on the API Keys page.

--repo value (required, if not stored in .tidelift) Repository name, can be found on the API Keys page.

--directory value, -d value The directory of the repository. If omitted, the current directory will be used

--branch value, -b value The branch name of the repository: used for comparison to the default branch.

--revision value, -r value The name of the revision for the scan. If omitted, a revision will be automatically generated.

--wait  Wait for the scan to finish before returning

--dry-run Only print files that the scan would find, don't upload them

Status

status

Get the status (success/failure) for an uploaded scan using its revision number.

Options

--json Return JSON instead of formatted plaintext. (default: false)

--debug Print debug information about API responses, loaded files, and more. (default: false)

--team value (required, if not stored in .tidelift)  Team name, can be found on the API Keys page.

--repo value (required, if not stored in .tidelift)  Repository name, can be found on the API Keys page.

--directory value -d value The directory of the repository. If omitted, the current directory will be used

--revision value, -r value (required) The revision of the scan

--wait, -w wait for the scan to finish before returning

Align

align

Checks repository's alignment with a catalog (i.e. if a repository is using only approved package releases)

Options

--json Return JSON instead of formatted plaintext. (default: false)

--debug Print debug information about API responses, loaded files, and more. (default: false)

--team value (required, if not stored in .tidelift) Team name, can be found on the API Keys page.

--repo value (required, if not stored in .tidelift) Repository name, can be found on the API Keys page.

--directory value -d value The directory of the repository. If omitted, the current directory will be used


Updating and installing CLI

To update to the latest version of the CLI tool, you can run the command tidelift selfupdate

To uninstall Tidelift CLI, remove the downloaded binary from your computer (e.g. on Linux, rm tidelift).   

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us