epcc-cli

README

Elastic Path Commerce Cloud Command Line Interface

Overview

This project is designed as a tool for power users to interact with the Elastic Path Commerce Cloud 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 Commerce Cloud 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

Command	Description
epcc get <RESOURCE> [ID] ... [QUERY_PARAM_KEY] [VAL] ...	Retrieves either a list of objects, or an particular object from the API.
epcc create <RESOURCE> [ID]... [KEY] [VAL] [KEY] [VAL]...	Create an object.
epcc update <RESOURCE> [ID]...[KEY] [VAL] [KEY] [VAL]...	Update an object.
epcc delete <RESOURCE> [ID]...	Delete an object.

Authentication Commands

Command	Description
epcc login client_credentials	Login to the API using a Client Credential Token
epcc login customer	Login to the API using a Customer Token
epcc login account-management	Login to the API using an Account Management Authentication Token
epcc login implicit	Login to the API using an Implicit Token
epcc login status	Determine the current state of the login

Debugging Commands

Command	Description
epcc docs <RESOURCE>	Open the API docs for a resource in your browser
epcc docs <RESOURCE> [create/read/update/delete]	Open the API docs for a resource with a specification action in your browser
epcc aliases list	List all known resource aliases
epcc resource-list	List all supported resources
epcc test-json [KEY] [VAL] [KEY] [VAL] ...	Render a JSON document based on the supplied key and value pairs

Power User Commands

Command	Description
epcc reset-store <STORE_ID>	Reset the store to an initial state (on a best effort basis)
epcc runbooks show <RUNBOOK> <ACTION>	Show a specific runbook (script)
epcc runbooks run <RUNBOOK> <ACTION>	Run a specific runbook (script)

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.

Environment Variable	Description
EPCC_API_BASE_URL	This is the API base URL which can be retrieved via CM.
EPCC_BETA_API_FEATURES	This variable allows you to set Beta Headers for all API calls.
EPCC_CLI_HTTP_HEADER_N	Setting any environment variable like this (where N is a number) will cause it's value to be parsed and added to all HTTP headers (e.g., EPCC_CLI_HTTP_HEADER_0=Cache-Control: no-cache will add Cache-Control: no-cache as a header). FYI, the surprising syntax is due to different encoding rules.
EPCC_CLI_SUPPRESS_NO_AUTH_MESSAGES	This will supress warning messages about not being authenticated or logged out
EPCC_CLIENT_ID	This is the Client ID which can be retrieved via CM.
EPCC_CLIENT_SECRET	This is the Client Secret which can be retrieved via CM.
EPCC_PROFILE	A profile name that allows for an independent session and isolation (e.g., distinct histories)
EPCC_RUNBOOK_DIRECTORY	A directory that will be scanned for runbook, a runbook ends with .epcc.yml

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

Sorting in Descending Order

The EPCC CLI supports sorting in descending order however you may get an error:

$ epcc get customers sort -updated_at
Error: unknown short flag: 'u' in -updated_at

You will need to use a bare double dash "--" before the argument, this signals that flag processing is complete and is a convention in many shells.

$ epcc get customers -- sort -updated_at

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