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...]

When using the CLI, do not use square brackets in your commands.

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 The catalog the project should align with (required with multiple catalogs)

--organization The organization that the user is a part of (can be found on API Keys page)

--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 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. 

NOTE

For Mac users - When attempting to run an alignment on a Mac, some users can run into a 'permissions denied' error message. To remedy this, users will need to ensure the directory where the CLI is installed is unlocked.

Screen_Shot_2023-01-12_at_4.52.28_PM.png

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

--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 (required, if not stored in .tidelift) Organization name, can be found on the API Keys page.

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

--recursive/-R 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],[DIRECTORY] in tandem to narrow down your build manifests.

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/-b [BRANCH-NAME] The branch name of the project. 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/-r [REVISION-NAME] The name of the revision for the alignment. A revision is a unique identifier for the alignment. If omitted, it will be automatically generated.

--external-identifier [IDENTIFIER] (optional) An identifier for the alignment and its revision that can be correlated to some other system (such as an application version).

-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_percentunapproved_count, unapproved_percent, denied_count, denied_percentrequested_count, and  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 is not 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-NAME]

The status command checks the status of the alignment associated with the passed revision.Options (only available for status)

--directory/-d [DIRECTORY] The directory of the project. If omitted, the current directory will be used

--revision/-r [REVISION-NAME] (required) The revision of the alignment

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

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

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


Projects

projects

Subcommand: new

new [PROJECT-NAME] --organization [ORG-NAME] --default-branch [BRANCH-NAME] --catalog [CATALOG-NAME] --group [GROUP-NAME] --external-identifier [IDENTIFIER] --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 [CATALOG-NAME] The catalog the project should align with (required if the organization has multiple catalogs)

--group [GROUP-NAME] What group the project should be assigned to.  Multiple groups can be specified using --group [GROUP1] --group [GROUP2] --group [GROUP3]

--default-branch [BRANCH-NAME] The default version control branch name to use. Defaults to main

--external-identifier [IDENTIFIER] (optional) An identifier for the project that can be correlated to some other system (such as an application id, or source repository). Defaults to the git repository, if detected

--branching-behavior (specified_branch|latest_aligned_branch) Determines whether the latest default alignment will be from the branch specified by default-branch (specified_branch), or from the latest alignment from any branch (latest_aligned_branch).

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

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

Subcommand: list

list --organization [ORG-NAME] Lists all accessible projects.

Subcommand: delete

delete --project [PROJECT-NAME] --organization [ORG-NAME] Deletes the specified project.

Subcommand: new-key

new-key --project [PROJECT-NAME] --organization [ORG-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`.

Subcommand: update

update --project [PROJECT-NAME] --catalog [CATALOG-NAME] --default-branch [BRANCH-NAME] --group [GROUP] --name [NEW-NAME]

Updates the project with the specified values.

Options

--catalog [CATALOG-NAME] The catalog the project should align with

--default-branch [BRANCH-NAME] The default version control branch name to use

--name [NEW-NAME] The new name for the project

--group [GROUP-NAME] What group the project should be assigned to.  Multiple groups can be specified using --group [GROUP1] --group [GROUP2] --group [GROUP3]

--external-identifier [IDENTIFIER] (optional) An identifier for the project that can be correlated to some other system (such as an application id, or source repository). Defaults to the git repository, if detected

--branching-behavior (specified_branch|latest_aligned_branch) Determines whether the latest default alignment will be from the branch specified by default-branch (specified_branch), or from the latest alignment from any branch (latest_aligned_branch).

Subcommand: save-lockfiles

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

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


Releases

releases

Subcommand: list

list --catalog [CATALOG-NAME]

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

Subcommand: lookup

lookup [PACKAGE-MANAGER] [PACKAGE-NAME]

Display information and approved releases for a package in your catalog


Groups

groups

Subcommand: list

list --organization [ORG-NAME]

Display all existing groups in the organization.

Subcommand: new

new [GROUP-NAME] --organization [ORG-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. 

Subcommand: remove

remove [GROUP-NAME] --organization [ORG-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.

Subcommand: list-users

list-users [GROUP-NAME] --organization [ORG-NAME]

List all users associated with the group.

Subcommand: add-user

add-user [GROUP-NAME] [USER-EMAIL-ADDRESS] --organization [ORG-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. 

Subcommand: remove-user

remove-user [GROUP-NAME] [USER-EMAIL-ADDRESS] --organization [ORG-NAME]

Removes user with the provided email address from the specified group

Subcommand: add-project

add-project [GROUP-NAME] [PROJECT-NAME] --organization [ORG-NAME]

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

Subcommand: remove-project

remove-project [GROUP-NAME] [PROJECT-NAME] --organization [ORG-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)
Was this article helpful?
2 out of 2 found this helpful

Comments

0 comments

Article is closed for comments.

Articles in this section