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:
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).
The Refactr CLI is hosted on npm. In order to install the CLI, you will first need to install Node.js, which includes 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
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.
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>
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 otherget
- retrieves a single organization, project, pipeline, pipeline revision job and otherlist
- retrieves a list of organizations, projects, pipelines and other to which you have an accessdelete
- deletes a projects, pipelines and otherrun
- schedules a run of a pipeline or jobrerun
- reruns an already finished pipeline runThe resources available for each command are listed below.
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'
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>
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...]
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
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...]
Schedules a run of a pipeline or job.
$ refactrctl run <resource> [options...] <id>
where
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.
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.