Getting started with CLI tool

This page will help you get started with Phylum CLI tool. You'll be up and running in a jiffy!

Introduction

The command line tool allows for easy interaction with Phylum's API to expose the product to our users. It is developed in Rust and has release binaries available for Linux. Windows and MacOS binaries can be easily built

The command line tool submits a package or group of packages to the Phylum API and returns JSON data about the packages.

Installation and Configuration

Follow the installation and configuration instructions from GitHub here

Usage

The Phylum CLI tool supports a number of subcommands. These can be viewed by passing the -h command line argument:

phylum-cli 0.0.6
Phylum, Inc.
Client interface to the Phylum system

USAGE:
    phylum-cli [OPTIONS] [SUBCOMMAND]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -c, --config <FILE>    Sets a custom config file
    -v <verbose>...        Sets the level of verbosity

SUBCOMMANDS:
    batch         Submits a batch of requests to the processing system
    cancel        Cancels a request currently in progress
    help          Prints this message or the help of the given subcommand(s)
    heuristics    List available heuristics / submit packages for heuristics
    init          Initialize a new project
    ping          Ping the remote system to verify it is available
    register      Register a new system user
    status        Polls the system for request / job / package status
    submit        Submits a request to the processing system
    tokens        Manage API tokens
    version       Display application version

Each subcommand also accepts the -h command line argument to explore the usage of the subcommand:

$ phylum-cli register -h
phylum-cli-register
Register a new system user

USAGE:
    phylum-cli register -u <email> -p <password> -f <first> -l <last>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -u <email>           User e-mail address
    -f <first>           First name
    -l <last>            Last name
    -p <password>        Password

To use the Phylum CLI tool, a user first needs to register an account on the Phylum API. This can be done with the following command:

$ phylum-cli register -u <email> -f <firstname> -l <lastname -p <password>

Registering an account with Phylum will update or create a configuration file name settings.yaml in the $HOME/.phylum directory that saves user authentication information. This file is needed to perform authenticated operations on the Phylum API.

The Phylum command-line tool is now installed and configured for use with a user account on Phylum's API.

Submitting packages for analysis

To submit a single package for analysis, first a project must be created. Projects can be created by:

$ phylum-cli init -p <project_name>

This will create a .phylum_project text file in the current working directory. This is used to correlate multiple submissions of a single project into the API for historical analysis. It's a great idea to add this file to the version control repository for the project, as well.

Next, use the "submit" subcommand specifying: -n and -v

$ phylum-cli submit -n <name of package> -v <version of package> 

A message will be printed to the shell with:

[status] Job ID: <GUID>

The GUID can be used to reference a submitted job when requesting package status.

To submit a list of packages for analysis, use the "batch" subcommand:

$ phylum-cli batch -h
phylum-cli-batch
Submits a batch of requests to the processing system

USAGE:
    phylum-cli batch [FLAGS] [OPTIONS]

FLAGS:
    -h, --help       Prints help information
    -u
    -u
    -V, --version    Prints version information

OPTIONS:
    -f <file>        file (or piped stdin) containing the list of packages (format
                     `<name>:<version>`)

Prepare a text file with a list of packages formatted in the following form:

<package_name>:<package_version>
<package_name>:<package_version>

Example:

react-is:17.0.1
react:16.13.1
yargs:16.1.0

Then submit the text file to the Phylum API:

$ phylum-cli batch -f package_list.txt
[success] Job ID: 5b6af9f5-76f3-45a2-b32c-be462b46cdf9

Checking Phylum job status

The Phylum API tracks status of all submitted jobs. The status can be viewed by using the "status" subcommand.

Invoking "status" without additional command line arguments will return a JSON object detailing status for all package analysis submissions.

$ phylum-cli status
[success] Response object:
[
  {
    "id": "9644ddaf-a554-4826-956d-0216a1352782",
    "user_id": "be4cd026-a628-4d97-b9ec-bec1bb35860a",
    "started_at": 1604964914529,
    "last_updated": 1605195978192,
    "status": "PROCESSING",
    "packages": [
      {
        "name": "react-is",
...

To request status of a specific job, use the "status" subcommand with the -i command line argument to specifiy the Job ID GUID:

$ phylum-cli status -i 5b6af9f5-76f3-45a2-b32c-be462b46cdf9
[success] Response object:
{
  "id": "5b6af9f5-76f3-45a2-b32c-be462b46cdf9",
  "user_id": "be4cd026-a628-4d97-b9ec-bec1bb35860a",
  "started_at": 1605196826721,
  "last_updated": 1605196833239,
  "status": "PROCESSING",
  "packages": [
    {
      "name": "react-is",
...

API Tokens

The Phylum CLI tool supports use of API tokens instead of username/password credentials for use in service accounts, CI/CD runners, and other automation uses.

API tokens can only be used to:

  • submit - submit packages to the Phylum API
  • status - query job status of previous submissions

To create an API token, first register a user account with the Phylum API as shown above. That user account can then create API tokens using the "tokens" subcommand:

$ phylum-cli tokens -h
phylum-cli-tokens
Manage API tokens

USAGE:
    phylum-cli tokens [FLAGS] [OPTIONS]

FLAGS:
    -c               Create new API token
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -d <delete>        Delete (de-activate) an existing token

Create an API token using the -c command line argument:

$ phylum-cli tokens -c
[success] Response object:
{
  "active": true,
  "key": "aee82db6-b5aa-4637-a33b-962a2d067092",
  "user_id": "be4cd026-a628-4d97-b9ec-bec1bb35860a"
}

When an API token is created, it will be automatically added to the settings.yaml configuration file in $HOME/.phylum.

This configuration file can then be stripped of username/password data for use in automation:

---
connection:
  uri: "https://api.phylum.io"
auth_info:
  api_token:
    active: true
    key: aee82aa6-b5aa-4637-AAAA-962a2d067092
    user_id: be4cd026-a628-AAAA-b9ec-bec1bb35860a
request_type: npm
packages: ~

Questions/Issues

Please contact Phylum with any questions or issues using the CLI tool.

Email: [email protected]


Did this page help you?