Elastic Path Composable Commerce Command Line Interface

Overview

This project is designed as a tool for power users to interact with the Elastic Path Composable Commerce API via the command line and the project is designed to fill three distinct niches:

1. Provide a fast way for users familiar with the API to interact with it.
2. Provide a simpler way to do scripting with the API (i.e., instead of using curl and creating JSON in the shell)
3. Provide a reusable set of scripts for creating data sets with Runbooks.

This tool is not meant for new users unfamiliar with the API, new users are highly encouraged to use the Elastic Path Composable Commerce Postman Collection instead of this tool.

Additionally, this tool is not necessarily meant to be a new command line equivalent of Commerce Manager, it should just feel at all times like you are interacting with a JSON based REST API.

Getting Started

Installation

1. Download the appropriate release from the GitHub Release Page.
2. Add the epcc binary to your path.
3. Load the autocompletion into your shell (See instructions here).

It is highly recommended that new users check out the Tutorial.

Command Overview

The following is a summary of the main commands, in general you can type epcc help to get an updated list and see all commands as well as flags.

CRUD Commands

Authentication Commands

Debugging Commands

Power User Commands

Tuning Runbooks

1. --execution-timeout will control how long the epcc process can run before timing out.
2. --rate-limit will control the number of requests per second to EPCC.
3. --max-concurrency will control the maximum number of concurrent commands that can run simultaneously.
   • This differs from the rate limit in that if a request takes 2 seconds, a rate limit of 3 will allow 6 requests in flight at a time, whereas --max-concurrency would limit you to 3. A higher value will slow down initial start time.

Headers

Headers can be set in one of three ways, depending on what is most convenient

1. Via the -H argument.
   • This header will be one time only.
2. Via the EPCC_CLI_HTTP_HEADER_0 environment variable.
   • This header will be always be set.
3. Via the epcc header set
   • These headers will be set in the current profile and will stay until unset. You can see what headers are set with epcc headers status
   • Headers set this way support aliases.
   • You can also additionally group headers into groups with --group and then clear all headers with epcc headers clear <GROUP>

Configuration

Via Prompts

Run the epcc configure and it will prompt you for the required settings, when you execute any EPCC CLI command you can pass in the --profile argument, or set the EPCC_PROFILE environment variable to use that profile.

Via Environment Variables

The following environment variables can be set up to control which environment and store to use with the EPCC CLI.

It is recommended to set EPCC_API_BASE_URL, EPCC_CLIENT_ID, and EPCC_CLIENT_SECRET to be able to interact with most things in the CLI.

Auto Completion

For convenience this cli has been set up with auto-completion. To make the most of the EPCC CLI start by running the following commands to set up completion for your shell:

Zsh

If shell completion is not already enabled in your environment, you will need to enable it. Run the following command once:

echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions for each session, execute once:

epcc completion zsh > “${fpath[1]}/_epcc

You will need to start a new shell for this setup to take effect

Bash

You will need to have the bash-completion ( e.g., Ubuntu, Arch, Gentoo) package installed, and restart your bash session.

To load completions for each session, execute once:

Linux

epcc completion bash > /etc/bash_completion.d/epcc

macOS

epcc completion bash > /usr/local/etc/bash_completion.d/epcc

PowerShell

For PowerShell run:

epcc completion powershell | Out-String | Invoke-Expression

To load completions for every new session, run:

epcc completion powershell > epcc.ps1

and source this file from your PowerShell profile.

fish

For fish run:

epcc completion fish | source

To load completions for each session, execute once:

epcc completion fish > ~/.config/fish/completions/epcc.fish

Tips

JQ Output

The --output-jq option can post process the output of epcc create epcc get and epcc update, for instance the following can be used to create richer output.

$epcc create customer --auto-fill 
INFO[0000] (0001) POST https://api.moltin.com/v2/customers ==> HTTP/2.0 201 Created 
{
  "data": {
    "type": "customer",
    "id": "49d8e601-d110-42b7-99d2-60db73a6fb62",
    "authentication_mechanism": "password",
    "email": "thorabartell@gutmann.org",
    "name": "Michele Schuppe",
    "password": false
  }
}

$epcc create customer --auto-fill 
INFO[0001] (0001) POST https://api.moltin.com/v2/customers ==> HTTP/2.0 201 Created 
{
  "data": {
    "type": "customer",
    "id": "bf642721-44e5-4919-9fa5-b9c7da1ded1f",
    "authentication_mechanism": "password",
    "email": "kavondonnelly@yost.info",
    "name": "Matt Robel",
    "password": false
  }
}
$epcc get customers  --output-jq '.data[] | "\(.name) has id \(.id)"'
INFO[0000] (0001) GET https://api.moltin.com/v2/customers ==> HTTP/2.0 200 OK 
[
  "Michele Schuppe has id 49d8e601-d110-42b7-99d2-60db73a6fb62",
  "Matt Robel has id bf642721-44e5-4919-9fa5-b9c7da1ded1f"
]

The JQ Manual has some additional guidance on syntax, although this is based on GoJQ which has a number of differences.

Waiting for things

The --retry-while-jq argument can be used to wait for certain conditions to happen (e.g., a catalog publication, or an eventual consistency condition).

For example:

epcc get pcm-catalog-release --retry-while-jq '.data.meta.release_status != "PUBLISHED"' name=Ranges_Catalog last_release

The JQ Manual has some additional guidance on syntax, although this is based on GoJQ which has a number of differences.

How to determine the store you are using

epcc runbooks run misc get-store-info

Development Tips

Fast rebuilds

For development the following command using Reflex can speed up your development time, by recreating the command line tool.

git fetch --all --tags && reflex -v -s -r '(\.go$)|(resources.yaml|go.mod)|(runbooks/.+\.ya?ml)$' -- sh -c "go build -ldflags=\"-X github.com/elasticpath/epcc-cli/external/version.Version=$(git describe --tags --abbrev=0)+1 -X github.com/elasticpath/epcc-cli/external/version.Commit=$(git rev-parse --short HEAD)-dirty\" -o ./epcc" 

Git Hooks

The following git pre-commit hook will run go fmt before committing anything

#!/bin/bash

echo "Running go fmt"
go fmt "./..."

echo "Adding changed files back to git"
git diff --cached --name-only --diff-filter=ACM | grep -E "\.(go)$" | xargs  git add