Peridio Command Line Interface Overview

Peridio CLI, or peridio, is a command-line interface to Peridio for use in your terminal or your scripts.

It aims to have complete support for the Peridio Admin API.

Installation

peridio is available as a downloadable binary from the releases page.

Upgrade

The CLI can upgrade itself in place via peridio upgrade.

Precedence of Supplied Values

Options can be supplied in up to three ways, from highest to lowest precedence:

1. CLI arguments
2. Environment variables
3. Configuration files

Configuration Files

The Peridio CLI supports profile based configuration files as a means of supplying options that are relevant to many subcommands. A particular profile can be choosen explicitly via --profile. To use this functionality you must specify at least a config.json file and optionally, if you wish to specify API keys via this method, a credentials.json in the same directory.

By default, the directory searched for these files is:

OS	Default Config Directory
Linux	$HOME/.config/peridio
Windows	{FOLDERID_RoamingAppData}/peridio/config
macOS	$HOME/Library/Application\ Support/peridio

To override this directory, see --config-directory.

config.json

Contains a single object of the format:

Example

{
  "version": 1,
  "profiles": {
    "profile-name": {
      "organization_name": "organization-name"
    }
  },
  "signing_key_pairs": {
    "signing-key-pair-name": {
      "signing_key_prn": "prn:1:b8af964b-2736-423c-852b-a19d05e00d83:signing_key:15ba050a-82ee-4381-b461-d42181f9a81b",
      "signing_key_private_path": "private.pem"
    }
  },
  "ca_certificates": {
    "ca-certificate-name": {
      "certificate": "certificate.pem",
      "private_key": "private-key.pem"
    }
  }
}

Schema

{
  "version": VERSION,
  "profiles": {
    PROFILE_NAME: {
      "base_url": BASE_URL,
      "ca_path": CA_PATH,
      "organization_name": ORGANIZATION_NAME
    }
  },
  "signing_key_pairs": {
    SIGNING_KEY_PAIR_NAME: {
      "signing_key_prn": SIGNING_KEY_PRN,
      "signing_key_private_path": SIGNING_KEY_PRIVATE_PATH
    }
  },
  "ca_certificates": {
    CA_CERTIFICATE_NAME: {
      "certificate": CA_CERTIFICATE_PATH,
      "private_key": PRIVATE_KEY_PATH
    }
  }
  ...
}

Field	Required	Type	Description
VERSION	true	integer	Should be 1. See versioning.
PROFILE_NAME	false	string	The name of a profile. Corresponds to an entry in credentials.json. A particular profile can be choosen explicitly via --profile.
BASE_URL	false	string	See --base-url.
CA_PATH	false	string	See --ca-path.
ORGANIZATION_NAME	false	string	See --organization-name.
SIGNING_KEY_PAIR_NAME	false	string	The name of a signing key pair. Some commands that make use of signing keys will let you reference this configuration by name.
SIGNING_KEY_PRN	true	string	The PRN of the signing key that corresponds to the private key identified by the sibling SIGNING_KEY_PRIVATE_PATH field.
SIGNING_KEY_PRIVATE_PATH	true	string	The path to a private key's PEM file.
CA_CERTIFICATE_NAME	false	string	The name of a CA certificate. Some commands that make use of CA certificates will let you reference this configuration by name.
CA_CERTIFICATE_PATH	true	string	The path to a CA certificate's PEM file.
PRIVATE_KEY_PATH	true	string	The path to a CA certificate's private key's PEM file.

credentials.json

Contains a single object of the format:

Example

{
  "my-first-profile": {
    "api_key": "my-api-key"
  }
}

Schema

{
  PROFILE_NAME: {
    "api_key": API_KEY
  },
  ...
}

Field	Required	Type	Description
PROFILE_NAME	false	string	The name of a profile. Must correspond to an entry in config.json. A particular profile can be choosen explicitly via --profile.
API_KEY	false	string	See --api-key.

Global Options

Global options are options that are relevant to many commands. They are supplied after peridio but before a command, e.g., peridio --profile foo products list.

API Key

-a, --api-key <api-key>, $PERIDIO_API_KEY

The API key used to authenticate and authorize requests against the Peridio Admin API.

Can be provided via configuration files.

Base URL

-b, --base-url <base-url>, $PERIDIO_BASE_URL

Defaults to https://api.cremini.peridio.com.

The base URL of the Peridio Admin API.

Can be provided via configuration files.

CA Path

-c, --ca-path <ca-path>, $PERIDIO_CA_PATH

A path identifying a file containing PEM encoded CA certificates to additionally trust when making API requests.

Can be provided via configuration files.

Config Directory

-d, --config-directory <config-directory>, $PERIDIO_CONFIG_DIRECTORY

Defaults to $HOME/Library/Application\ Support/peridio on macOS.

A path identifying the directory the CLI should look within to find Peridio CLI configuration files.

Organization Name

-o, --organization-name <organization-name>, $PERIDIO_ORGANIZATION_NAME

If applicable, the case-sensitive name of the organization against which Peridio Admin API requests will be executed.

Can be provided via configuration files.

Profile

-p, --profile <profile>, $PERIDIO_PROFILE

Explicitly chooses a profile within a config.json to use. See configuration files.

Versioning

The current version of the CLI is 1.

Stale Configs

Starting with version 0.8.0, the CLI will halt and prompt you to upgrade your config if it is stale.

Unversioned Configs

The very first iteration of a config file was unversioned, accordingly, that "version" is identified by a config file that does not have a version key.