Tidelift CLI reference

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

Command Structure

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

Authenticate

tidelift authenticate

The authenticate command allows you to authenticate with your user API key. On running the command, you will be provided with instructions on how to retrieve your key and prompted to enter it. Authentication is required to use Tidelift CLI on your local machine. (Note: If you are using Tidelift CLI as part of a CI/CD pipeline, do not authenticate with this command. See our article on Tidelift and Continuous Integration for more information.)


Init

tidelift init [PROJECT-NAME] --organization [ORGANIZATION-NAME] --catalog 
[CATALOG-NAME] [--skip-dot-tidelift/--force]

Begin tracking a new project with Tidelift, upload a bill of materials, and create an initial alignment record. The command should be run from within the project's root directory as it will generate a .tidelift file.

Options

--catalog valueThe catalog the project should align with (required with multiple catalogs)

--organization value The organization that the user is a part of

--force Overwrite an existing .tidelift file if one exists

--skip-dot-tidelift Do not create a new .tidelift file


Alignment

tidelift alignment

The alignment command allows you to generate a bill of materials for a project and check its alignment with your catalog. You can optionally save alignments (with the save subcommand) which is best used when integrating catalog alignment checks with CI/CD. 

Subcommands

alignment save Alignment save will store a record of the generated bill of materials and can be used for integrating with CI/CD. It requires using a Project Key, rather than a User API Key.

status Get the status (success/failure) for a saved alignment using its revision number.

Options (available for alignment and alignment save)

--dry-run Only print files that the alignment would find to generate the bill of materials, don't start an alignment

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

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

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

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

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

Options (only available for alignment)

--allow-requested  If there is an open request for all unapproved packages, the command will return an exit code of 0 (i.e. success); useful if using this command as a pre-commit hook

Options (only available for alignment save)

--branch value, -b value The branch name of the project: used for comparison to the default branch. NOTE: The branch value is required in CLI v1.3.0 and later. The Tidelift CLI will attempt to auto-detect the working GIT branch on the command line and CI. If the CLI is unable to detect the GIT branch automatically, it will need to be specified manually with the branch flag.

--revision value, -r value The name of the revision for the alignment. A revision is a unique identifier for the alignment. If omitted, it will be automatically generated.

-R (optional) Find supported manifest files in subdirectories. Note: it is not recommended to use this for an entire directory.

--wait  Wait for the alignment to finish before returning

Options (only available for status)

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

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

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


Blocking your build in other ways

By default, tidelift alignment returns an exit code of 1 when something is not aligned 100%. We have added the ability to see a break down of how things are aligned when using the --json flag, under the "statistics" object. The following keys are available underneath "statistics": total_count, approved_count, approved_percent, unapproved_count, unapproved_percent, denied_count, denied_percent, requested_count, requested_percent

To use this, instead of the default exit code, you we suggest using the jq tool, as it is relatively easy to use, by piping the output of --jsonto it. The following samples will allow you to continue where the denied count is not 0, or the denied percent is less than 10%.

tidelift alignment --json | jq ".statistics.denied_count == 0"
tidelift alignment --json | jq ".statistics.denied_percent < 0.1"


Projects

projects

Subcommands

new [PROJECT-NAME] --organization [TYPE/NAME] --default-branch [BRANCH-NAME] [--catalog CATALOG-NAME] [--group GROUP] [--force] [--skip-dot-tidelift]

Begin tracking a new project with Tidelift. The command should be run from within the project's root directory as it will generate a .tidelift file. This will not upload a bill of materials associated with the project. To upload a bill of materials associated with the project, use the `init` command.

Options

--catalog value The catalog the project should align with (required if the organization has multiple catalogs)

--group value What group the project should be assigned to

--force Overwrite an existing .tidelift file if one exists

--skip-dot-tidelift Do not create a new .tidelift file

new-key [PROJECT-NAME] --organization [TYPE/NAME]

Create a new Project Key for an existing project. Command expects to find a .tidelift file in the same directory. Project Keys are necessary to run `tidelift alignment save`.

update [--catalog CATALOG-NAME] [--default-branch BRANCH-NAME] [--group GROUP]

Options

--catalog value The catalog the project should align with

--default-branch value The default version control branch name to use

--group value What group the project should be assigned to


Releases

releases

Subcommands

lookup [package manager] [package name]

Display information and approved releases for a package in your catalog


Groups

groups

Subcommands

list --organization [TYPE/NAME]

Display all existing groups in the organization.

new [group name] --organization [TYPE/NAME]

Create a new group within the organization. If group name contains spaces, it needs to be in quotations.

remove [group name] --organization [TYPE/NAME] [--force]

Delete the group from the organization. If any projects/exceptions are applied to that group, a warning will be displayed to ask if you are sure. Group name needs to be the name in quotation marks, or the group slug.

list-users [group name] --organization [TYPE/NAME]

List all users associated with the group.

add-user [group name] [user email address] --organization [TYPE/NAME]

Adds user with the provided email address to the specified group. Note, a user with the provided email address must exist in the organization. 

remove-user [group name] [user email address] --organization [TYPE/NAME]

Removes user with the provided email address from the specified group

add-project [group name] [project name] --organization [TYPE/NAME]

Adds the specified user to the specified group. Note, a project with the provided name must exist

Options

--force Suppress any warning that might pop up when deleting a group


Request

request

Request packages to be approved in a catalog. Requests can be:

  • made for a single package with tidelift request [package manager] [package name] [release] (eg. tidelift request pypi urllib3 1.25.6)
  • made as a group for all packages not currently in the catalog with tidelift request --all (from the project's root directory

( Learn more about requests and how they're reviewed.)

Options

--all Request all packages not in the catalog

--wait Waits for a requests to finish processing before proceeding to next command. Commonly used in CI/CD to approve any new releases that would be automatically approved before running `tidelift alignment save`. Can only be used with `--all`.

--no-trees Disables any of the Code page 437 trees when outputting any lists


Selfupdate

tidelift selfupdate

Update CLI to the latest version.


Version

tidelift version

Print the version number of Tidelift CLI.


Global flags

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

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

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

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


Exit codes

Each command provides an exit code so that you can incorporate it into your workflow.

  • 0: Success (e.g. for align, this means the project is in alignment with the catalog)
  • 1: Critical failure (eg. for align, this means the catalog is not in alignment)
  • 2: Command not configured correctly (e.g. authentication failure or required options not provided)
Was this article helpful?
1 out of 1 found this helpful

Comments

0 comments

Article is closed for comments.

Articles in this section