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

Catalogs

tidelift catalogs list --organization [ORGANIZATION-NAME] 

List catalogs that are in the specified organization.

Options

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

Alignment

tidelift alignment [save] [--directory <path>] [file1 file2 file3]

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

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.

Arguments

file1... Passing explicit filenames will process those manifests, rather than searching for any supported manifest file.

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.

-R, --recursive process directories recursively when searching for manifest files

--exclude/-e <path1>,<path2>Used to exclude certain files/directories when searching for manifest files. For example:

-e file.txt,a-directory/,another-file.txt

You can use -R -e FILE_LIST in tandem to narrow down your build manifests.

--directory/-d <path> The absolute path directory of the project. If omitted, the current directory will be used. For example --directory /somewhere/over/the/rainbow/project

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

Blocking your build in other ways

By default, tidelift alignment returns an exit code of 1 when something is not 100% aligned.

If you want to make more nuanced decisions, more detailed information is available on the alignment when using the --json flag.

The JSON output includes detailed information, including information on approved, denied, and requested packages, and summary statistics. There are two summary objects: "statistics" (which calculates summary data for all packages in the alignment) and "production_statistics" (which calculates summary data for only packages that are included in a production scope, as opposed to development and test dependencies). Each statistics object includes the following information: 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, we suggest filtering the output of tidelift alignment or tidelift status with the jq tool. The following samples will allow you to continue where the denied count for all packages  isnot 0, or the denied percent of production-scoped packages is less than 10%.

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

Status

tidelift status <revision>

The status command checks the status of the alignment associated with the passed revision.

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

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

list --organization [TYPE/NAME]

Lists all accessible projects.

delete [PROJECT-NAME] --organization [TYPE/NAME]

Deletes the specified project.

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

Create a new Project API 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 [--project PROJECT-NAME] [--catalog CATALOG-NAME] [--default-branch BRANCH-NAME] [--group GROUP]

Updates the project with the specified values

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 

save-lockfiles [--zip]

Examine the project for manifest files, create lockfiles if needed, and display them to the user

Options

--zip Save any detected/processed lockfiles into a zipfile, instead of displaying them to the console

Releases

releases

Subcommands

list [--catalog CATALOG]

Displays a list of approved, denied, and requested releases in the specified catalog.

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. Only one group can be created at a time. 

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 project to the specified group. Note, a project with the provided name must exist

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

Removes the specified project from the specified group.

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
• made as a group for all packages in the specified file with tidelift request --all file1 file2 file3...

( 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)