{"id":20397099,"url":"https://github.com/elasticpath/epcc-cli","last_synced_at":"2025-10-06T23:13:32.290Z","repository":{"id":38067369,"uuid":"474204535","full_name":"elasticpath/epcc-cli","owner":"elasticpath","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-28T00:12:46.000Z","size":1111,"stargazers_count":34,"open_issues_count":46,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-08-28T05:16:24.545Z","etag":null,"topics":["cli","elastic-path","elastic-path-commerce-cloud","go"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elasticpath.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-03-26T00:48:15.000Z","updated_at":"2025-08-09T22:00:14.000Z","dependencies_parsed_at":"2024-04-14T17:24:59.676Z","dependency_job_id":"90abeada-f3c5-4e70-97a0-a364cebfa55a","html_url":"https://github.com/elasticpath/epcc-cli","commit_stats":null,"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/elasticpath/epcc-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elasticpath%2Fepcc-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elasticpath%2Fepcc-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elasticpath%2Fepcc-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elasticpath%2Fepcc-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elasticpath","download_url":"https://codeload.github.com/elasticpath/epcc-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elasticpath%2Fepcc-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278693079,"owners_count":26029432,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","elastic-path","elastic-path-commerce-cloud","go"],"created_at":"2024-11-15T04:11:48.595Z","updated_at":"2025-10-06T23:13:32.285Z","avatar_url":"https://github.com/elasticpath.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Elastic Path Composable Commerce Command Line Interface\n\n## Overview\n\nThis project is designed as a tool for power users to interact with the [Elastic Path Composable Commerce API](https://documentation.elasticpath.com/commerce-cloud/docs/api/) via the command line and the project is designed to fill three distinct\nniches:\n\n1. Provide a fast way for users familiar with the API to interact with it.\n2. Provide a simpler way to do scripting with the API (i.e., instead of using curl and creating JSON in the shell)\n3. Provide a reusable set of scripts for creating data sets with [Runbooks](docs/runbook-development.md).\n\nThis 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](https://elasticpath.dev/docs/commerce-cloud/api-overview/test-with-postman-collection)\ninstead of this tool.\n\nAdditionally, 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.\n\n## Getting Started\n\n### Installation\n\n1. Download the appropriate release from the [GitHub Release Page](https://github.com/elasticpath/epcc-cli/releases).\n2. Add the `epcc` binary to your path.\n   * On macOS, since the binary is unsigned, you will need to run `xattr -dr com.apple.quarantine /path/to/epcc` to allow it to execute otherwise you will get an error.\n3. Load the autocompletion into your shell (See instructions [here](#auto-completion)).\n\nIt is highly recommended that new users check out the [Tutorial](docs/tutorial.md).\n\n### Command Overview\n\nThe 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.\n\n#### CRUD Commands\n\n| Command                                                     | Description                                                               |\n|-------------------------------------------------------------|---------------------------------------------------------------------------|\n| `epcc get \u003cRESOURCE\u003e [ID] ... [QUERY_PARAM_KEY] [VAL] ...`  | Retrieves either a list of objects, or an particular object from the API. |\n| `epcc create \u003cRESOURCE\u003e [ID]... [KEY] [VAL] [KEY] [VAL]...` | Create an object.                                                         |\n| `epcc update \u003cRESOURCE\u003e [ID]...[KEY] [VAL] [KEY] [VAL]...`  | Update an object.                                                         |\n| `epcc delete \u003cRESOURCE\u003e [ID]...`                            | Delete an object.                                                         |\n\nKey and Value pairs are specified in a specific format documented in the [Tutorial](docs/tutorial.md#advanced-json-encoding).\n\n#### Authentication Commands\n\n| Command                         | Description                                                       |\n|---------------------------------|-------------------------------------------------------------------|\n| `epcc login client_credentials` | Login to the API using a Client Credential Token                  |\n| `epcc login customer`           | Login to the API using a Customer Token                           |\n| `epcc login account-management` | Login to the API using an Account Management Authentication Token |\n| `epcc login implicit`           | Login to the API using an Implicit Token                          |\n| `epcc login status`             | Determine the current state of the login                          |\n\n#### Debugging Commands\n\n| Command                                            | Description                                                                  |\n|----------------------------------------------------|------------------------------------------------------------------------------|\n| `epcc docs \u003cRESOURCE\u003e`                             | Open the API docs for a resource in your browser                             |  \n| `epcc docs \u003cRESOURCE\u003e [create/read/update/delete]` | Open the API docs for a resource with a specification action in your browser |\n| `epcc aliases list`                                | List all known resource aliases                                              |\n| `epcc resource-list`                               | List all supported resources                                                 |\n| `epcc test-json [KEY] [VAL] [KEY] [VAL] ...`       | Render a JSON document based on the supplied key and value pairs             |\n\n#### Power User Commands\n\n| Command                                 | Description                                                                |\n|-----------------------------------------|----------------------------------------------------------------------------|\n| `epcc reset-store \u003cSTORE_ID\u003e`           | Reset the store to an initial state (on a best effort basis)               |\n| `epcc runbooks show \u003cRUNBOOK\u003e \u003cACTION\u003e` | Show a specific runbook (script)                                           |\n| `epcc runbooks validate`                | Validates all runbooks (built in and user supplied, outputting any errors) |\n| `epcc runbooks run \u003cRUNBOOK\u003e \u003cACTION\u003e`  | Run a specific runbook (script)                                            |\n\n#### Tuning Runbooks\n\n1. `--execution-timeout` will control how long the `epcc` process can run before timing out.\n2. `--rate-limit` will control the number of requests per second to EPCC.\n3. `--max-concurrency` will control the maximum number of concurrent commands that can run simultaneously.\n    * 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.\n\n#### Headers\n\nHeaders can be set in one of three ways, depending on what is most convenient\n\n1. Via the `-H` argument.\n    * This header will be one time only.\n2. Via the `EPCC_CLI_HTTP_HEADER_0` environment variable.\n    * This header will be always be set.\n3. Via the `epcc header set`\n    * 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`\n    * Headers set this way support aliases.\n    * You can also additionally group headers into groups with `--group` and then clear all headers with `epcc headers clear \u003cGROUP\u003e`\n\n### Configuration\n\n#### Via Prompts\n\nRun 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.\n\n#### Via Environment Variables\n\nThe following environment variables can be set up to control which environment and store to use with the EPCC CLI.\n\n| Environment Variable                | Description                                                                                                                                                                                                                                                                                                                                                          |\n|-------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| EPCC_API_BASE_URL                   | This is the API base URL which can be retrieved via CM.                                                                                                                                                                                                                                                                                                              |\n| EPCC_BETA_API_FEATURES              | This variable allows you to set [Beta Headers](https://documentation.elasticpath.com/commerce-cloud/docs/api/basics/api-contract.html#beta-apis) for all API calls.                                                                                                                                                                                                  |\n| 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. You can also specify headers using `-H` or `epcc headers`. |\n| EPCC_CLI_SUPPRESS_NO_AUTH_MESSAGES  | This will supress warning messages about not being authenticated or logged out                                                                                                                                                                                                                                                                                       |\n| EPCC_CLI_URL_MATCH_REGEXP_**N**     | Setting this value causes the _path_ section of a URL to be matched and replaced with a corresponding value from the `EPCC_CLI_URL_MATCH_SUBSTITION_**N**` header, if not set the empty string is used.                                                                                                                                                              |\n| EPCC_CLI_URL_MATCH_SUBSTITION_**N** | The replacement string to use when a match is found. Capture groups and back references are supported (see [ReplaceAllString](https://pkg.go.dev/regexp#Regexp.ReplaceAllString)).                                                                                                                                                                                   |\n| EPCC_CLI_DISABLE_TLS_VERIFICATION   | Disables TLS verification.                                                                                                                                                                                                                                                                                                                                           | \n| EPCC_CLIENT_ID                      | This is the Client ID which can be retrieved via CM.                                                                                                                                                                                                                                                                                                                 |                                            \n| EPCC_CLIENT_SECRET                  | This is the Client Secret which can be retrieved via CM.                                                                                                                                                                                                                                                                                                             |\n| EPCC_PROFILE                        | A profile name that allows for an independent session and isolation (e.g., distinct histories).                                                                                                                                                                                                                                                                      |\n| EPCC_RUNBOOK_DIRECTORY              | A directory that will be scanned for runbook, a runbook ends with `.epcc.yml`.                                                                                                                                                                                                                                                                                       |\n| EPCC_DISABLE_LEGACY_RESOURCES       | If set disables legacy endpoints from being available.                                                                                                                                                                                                                                                                                                               |\n| EPCC_CLI_DISABLE_TEMPLATE_EXECUTION | If set to true, `epcc` will not render templates in variabes (i.e., `{{` will be treated literally), recommended when input might be untrusted.                                                                                                                                                                                                                      |\n| EPCC_CLI_DISABLE_RESOURCES          | A comma seperated list of resources that will not be available with commands or in the resource list                                                                                                                                                                                                                                                                 |                                                                                                                                                                                          \n\nIt 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.\n\n### Auto Completion\n\nFor 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:\n\n#### Zsh\n\nIf shell completion is not already enabled in your environment, you will need to enable it.\nRun the following command once:\n\n`echo \"autoload -U compinit; compinit\" \u003e\u003e ~/.zshrc`\n\nTo load completions for each session, execute once:\n\n`epcc completion zsh \u003e “${fpath[1]}/_epcc`\n\nYou will need to start a new shell for this setup to take effect\n\n#### Bash\n\nYou will need to have the [bash-completion](https://github.com/scop/bash-completion) (\ne.g., [Ubuntu](https://packages.ubuntu.com/search?keywords=bash-completion), [Arch](https://archlinux.org/packages/extra/any/bash-completion/), [Gentoo](https://packages.gentoo.org/packages/app-shells/bash-completion)) package installed, and restart\nyour bash session.\n\nTo load completions for each session, execute once:\n\n##### Linux\n\n`epcc completion bash \u003e /etc/bash_completion.d/epcc`\n\n##### macOS\n\n`epcc completion bash \u003e /usr/local/etc/bash_completion.d/epcc`\n\nIf installed using Homebrew, use the following command:\n\n`epcc completion bash \u003e $(brew --prefix)/etc/bash_completion.d/epcc`\n\n#### PowerShell\n\nFor PowerShell run:\n\n`epcc completion powershell | Out-String | Invoke-Expression`\n\nTo load completions for every new session, run:\n\n`epcc completion powershell \u003e epcc.ps1`\n\nand source this file from your PowerShell profile.\n\n#### fish\n\nFor fish run:\n\n`epcc completion fish | source`\n\nTo load completions for each session, execute once:\n\n`epcc completion fish \u003e ~/.config/fish/completions/epcc.fish`\n\n## Tips\n\n### JQ Output\n\nThe `--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\noutput.\n\n```bash\n$epcc create customer --auto-fill \nINFO[0000] (0001) POST https://api.moltin.com/v2/customers ==\u003e HTTP/2.0 201 Created \n{\n  \"data\": {\n    \"type\": \"customer\",\n    \"id\": \"49d8e601-d110-42b7-99d2-60db73a6fb62\",\n    \"authentication_mechanism\": \"password\",\n    \"email\": \"thorabartell@gutmann.org\",\n    \"name\": \"Michele Schuppe\",\n    \"password\": false\n  }\n}\n\n$epcc create customer --auto-fill \nINFO[0001] (0001) POST https://api.moltin.com/v2/customers ==\u003e HTTP/2.0 201 Created \n{\n  \"data\": {\n    \"type\": \"customer\",\n    \"id\": \"bf642721-44e5-4919-9fa5-b9c7da1ded1f\",\n    \"authentication_mechanism\": \"password\",\n    \"email\": \"kavondonnelly@yost.info\",\n    \"name\": \"Matt Robel\",\n    \"password\": false\n  }\n}\n$epcc get customers  --output-jq '.data[] | \"\\(.name) has id \\(.id)\"'\nINFO[0000] (0001) GET https://api.moltin.com/v2/customers ==\u003e HTTP/2.0 200 OK \n[\n  \"Michele Schuppe has id 49d8e601-d110-42b7-99d2-60db73a6fb62\",\n  \"Matt Robel has id bf642721-44e5-4919-9fa5-b9c7da1ded1f\"\n]\n```\n\nThe [JQ Manual](https://stedolan.github.io/jq/manual/) has some additional guidance on syntax, although\nthis is based on [GoJQ which has a number of differences](https://github.com/itchyny/gojq#difference-to-jq).\n\n### Waiting for things\n\nThe `--retry-while-jq` argument can be used to wait for certain conditions to happen (e.g., a catalog publication, or an eventual consistency condition).\n\nFor example:\n\n```bash\nepcc get pcm-catalog-release --retry-while-jq '.data.meta.release_status != \"PUBLISHED\"' name=Ranges_Catalog last_release\n```\n\nThe [JQ Manual](https://stedolan.github.io/jq/manual/) has some additional guidance on syntax, although\nthis is based on [GoJQ which has a number of differences](https://github.com/itchyny/gojq#difference-to-jq).\n\n### How to determine the store you are using\n\n```bash\nepcc runbooks run misc get-store-info\n```\n\n## Development Tips\n\n### Fast rebuilds\n\nFor development the following command using [Reflex](https://github.com/cespare/reflex) can speed up your development time, by recreating the command line tool.\n\n```bash\ngit fetch --all --tags \u0026\u0026 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 -X github.com/elasticpath/epcc-cli/external/version.Date=\\$(date -u +'%Y-%m-%dT%H:%M:%SZ')\\\" -o ./epcc\" \n```\n\n### Git Hooks\n\nThe following git pre-commit hook will run go fmt before committing anything\n\n```bash\n#!/bin/bash\n\necho \"Running go fmt\"\ngo fmt \"./...\"\n\necho \"Adding changed files back to git\"\ngit diff --cached --name-only --diff-filter=ACM | grep -E \"\\.(go)$\" | xargs  git add\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felasticpath%2Fepcc-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felasticpath%2Fepcc-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felasticpath%2Fepcc-cli/lists"}