Using the CLI

Usage documentation for the Refactr CLI, which can be used to perform actions in the Refactr Platform from a command prompt.

Overview

The Refactr CLI is a command line interface for the Refactr Platform 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
  • Re-schedule finished runs

The CLI is a wrapper around the API client, which is an upstream project located here. It 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 Refactr CLI is hosted on npm. In order to install the CLI, you will first need to install Node.js, which includes npm.

Click here to install Node.js

npm

To get the latest version of the CLI tool, use npm:

$ npm install -g @refactr/cli

or with yarn:

$ yarn global add @refactr/cli

Manual download

It is also possible to download and install binary distribution manually, visit the GitHub releases page to get a specific version of the CLI or get the latest version from 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 you need to generate an API token from the API Tokens page.

After you get token you can provide it as an --auth-token flag:

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

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

$ export REFACTR_AUTH_TOKEN=<auth-token>

Usage

The CLI is organized into commands, such as “list” and “create”. These commands are combined with an resource type, such as “project” or “pipeline”. Some commands require additional arguments.

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

Available ommands:

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

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.

--address=<address>

Address of the Refactr API server, default to https://api.refactr.it/v1

--format=<format>

Format of returned result data of an executed command. Format can be set to wide, json or yaml and set to wide by default. When format is set to wide the format of the returned result may be either formatted as table or as log - a list of events descriptions. When wide format is used not all data of the returned result may be presented, to get the full API response data use either json or yaml to get result as JSON or YAML formatted response correspondingly.

Here is an example of the 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>

It is possible to provide --filter option to get result data filtered according to provided filter, when --format is set either to json or yaml. JSONPath expression language is used to construct a filter.

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

Creates a project, pipeline, pipeline revision, job and other.

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

where <resource> is one of

project
pipeline-revision
pipeline
credential
job

To create pipeline revision call one of the following command

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

when positional argument is prefixed with at symbol @, the argument is treated as path to the configuration file, otherwise as a pipeline configuration.

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

Deletes a projects, pipelines and other.

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

where <resource> is one of

pipeline
job
project
runner
credential

<id> argument may be provided directly as a command argument, or as STDIN, e.g. (assuming bash):

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

Retrieves a list of organizations, projects, pipelines and other to which you have an access.

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

where <resource> is one of

credentials
projects
organizations
jobs
runs
pipeline-revision
runners
pipelines
get

Retrieves a single organization, project, pipeline, pipeline revision job and other.

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

where <resource> is one of

credential
job
project
pipeline
pipeline-revision
organization
run
runner

<id> argument may be provided directly as a command argument, or as STDIN, e.g. (assuming bash):

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

Schedules a run of a pipeline or job.

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

where is one of

job
pipeline

<id> argument may be provided directly as a command argument, or as STDIN, e.g. (assuming bash):

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

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

rerun

Reruns an already finished pipeline run.

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

or

<id> argument may be provided directly as a command argument, or as STDIN, e.g. (assuming bash):

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

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