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.
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.
--baseline-alignment [integer] Use the specified alignment number as the baseline for this alignment. For more information, see Using alignment results to drive action.
--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
How to use alignment to determine actions in your organization
Please see Using alignment results to drive action.
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. Note that this must be unique within an organization.
--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...
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)