Using the CLI

Usage documentation for the Sophos Factory Command Line Interface (CLI).

Overview

The Sophos Factory CLI is a command line interface for Sophos Factory that enables you to interact with the platform from comfort of your terminal. Some common things possible to do with the CLI:

  • View, create and delete projects, pipelines, jobs, etc.
  • Create new revisions of pipelines from provided YAML/JSON pipeline configuration files
  • Schedule job and pipeline runs
  • Reschedule finished runs

The CLI is a wrapper around the upstream API client. The CLI supports the most commonly-used API endpoints, and the CLI commands are closely mapped to the API endpoints. Some additional functionality is added to make complex actions easier (such as polling for run status).

Installation

The Sophos Factory CLI is hosted on npm. In order to install the CLI, you will first need to install Node.js, which includes npm. You can then proceed to download the Sophos Factory CLI package below.

Install using npm

$ npm install -g @sophos-factory/cli

Install using yarn

$ yarn global add @sophos-factory/cli

Manual download

It is also possible to download and install a binary distribution manually. Visit the GitHub releases page to get a specific version of the CLI or get the latest version here.

Download the archive file for your operating system/architecture. Unpack the archive, and put the binary somewhere in your $PATH (e.g. on UNIX-y systems /usr/local/bin). Make sure it has execution permission granted.

Authentication

Before using the CLI, generate an API token from the API Tokens page.

Provide the token using the --auth-token flag:

$ refactrctl <command> --auth-token=<auth-token> [options...] [args...]

The API token can also be provided in the FACTORY_AUTH_TOKEN environment variable:

$ export FACTORY_AUTH_TOKEN=<auth-token>

Usage

The CLI is organized into commands, such as list and create. These commands act on a resource type, such as project or pipeline. Some commands require additional arguments.

$ refactrctl <command> <resource> [options...] [args...]

Available commands:

  • create - creates a project, pipeline, pipeline revision, job and other
  • get - retrieves a single organization, project, pipeline, pipeline revision job and other
  • list - retrieves a list of organizations, projects, pipelines and other to which you have an access
  • delete - deletes a projects, pipelines and other
  • run - schedules a run of a pipeline or job
  • rerun - reruns an already finished pipeline run

The resources available for each command are listed below.

Command Options

A command option can be formatted either as --<key> <value> or --<key>=<value>.

The following options are available for all commands:

--auth-token=<auth-token>

Authentication token obtained from the API Tokens page.

--address=<address>

Address of the Sophos Factory API server. Defaults to https://api.factory.sophos.com/v1.

--format=<format>

Format for the data returned by an executed command. Options are:

  • wide (default)
  • json
  • yaml

When format is set to wide, the returned result may be a table or a log list of event descriptions. Some of the available data may not be presented. To ensure you get all available data from the API response, use either json or yaml formats.

Here is an example of table formatted data:

_id           name               pipeline_count  organization_id    created            
<project_id>  Name of a project  1               <organization_id>  01/11/2021, 8:40 PM

…and log formatted data:

01/25/2021, 11:26 PM info Executing run.
01/25/2021, 11:26 PM info Evaluating project variables.
01/25/2021, 11:26 PM info Project variables evaluated successfully.
01/25/2021, 11:26 PM info Evaluating run variables.
01/25/2021, 11:26 PM info Run variables evaluated successfully.
01/25/2021, 11:26 PM info Installing step module tool dependencies.
01/25/2021, 11:26 PM info Installed step module tool dependencies successfully.
01/25/2021, 11:26 PM info Executing pipeline step "Install Java".
01/25/2021, 11:26 PM info Pipeline step "Install Java" executed successfully.
01/25/2021, 11:26 PM info Executing pipeline step "Print version".
01/25/2021, 11:26 PM info Executing Shell script.
01/25/2021, 11:26 PM info stderr: openjdk version "15.0.1" 2020-10-20
OpenJDK Runtime Environment Zulu15.28+51-CA (build 15.0.1+9)
OpenJDK 64-Bit Server VM Zulu15.28+51-CA (build 15.0.1+9, mixed mode, sharing)
01/25/2021, 11:26 PM info Pipeline step "Print version" executed successfully.
01/25/2021, 11:26 PM info Run executed successfully.

--filter=<filter>

The --filter option allows you to filter the returned data when --format is set either to json or yaml. JSONPath expression language is used to construct a filter. For example:

$ ./bin/refactrctl.js list projects --format=json --filter='$.._id'

create

Create a resource.

$ refactrctl create <resource> [options...] <id>

…where <resource> is one of:

  • credential
  • job
  • pipeline
  • pipeline-revision
  • project

For example, to create a pipeline revision:

$ refactrctl create pipeline-revision \
    --project-id=<project-id> \
    --pipeline-id=<pipeline-id> \
    @./path/to/pipeline/config.yml

The positional argument prefixed with @ is treated as a path to the configuration file. Without the @ it indicates a pipeline configuration:

$ refactrctl create pipeline-revision \
    --project-id=<project-id> \
    --pipeline-id=<pipeline-id> \
    <pipeline-config>

The pipeline configuration can also be provided through STDIN:

$ cat /path/to/pipeline/config.yml | refactrctl create pipeline-revision \
    --project-id=<project-id> \
    --pipeline-id=<pipeline-id>

delete

Delete a resource.

$ refactrctl delete <resource> [options...] <id>

where <resource> is one of:

  • credential
  • job
  • pipeline
  • project
  • runner

The <id> argument may be provided as a command argument or through STDIN, for example:

$ echo <id> | refactrl delete <resource> [options...]

list

Retrieves a list of resources for which you have access.

$ refactrctl list <resource> [options...] <id>

…where <resource> is one of:

  • credentials
  • jobs
  • organizations
  • pipelines
  • pipeline-revisions
  • projects
  • runs
  • runners

get

Retrieve a single resource.

$ refactrctl get <resource> [options...] <id>

…where <resource> is one of:

  • credential
  • job
  • organization
  • pipeline
  • pipeline-revision
  • project
  • run
  • runner

The <id> argument may be provided as a command argument or through STDIN, for example:

$ echo <id> | refactrl get <resource> [options...]

run

Schedule a run of a pipeline or job.

$ refactrctl run <resource> [options...] <id>

…where <resource> is one of:

  • job
  • pipeline

The <id> argument may be provided as a command argument or through STDIN, for example:

$ echo <id> | refactrl run <resource> [options...]

A --wait option may be passed to wait until the scheduled run is finished. If --wait is set, all logs emitted during run execution are logged on the screen.

rerun

Rerun an already finished pipeline run.

$ refactrctl rerun [options...] <id>

The <id> argument may be provided as a command argument or through STDIN, for example:

$ echo <id> | refactrl rerun [options...]

A --wait option can be supplied to wait until the rescheduled run is finished.