# @axway/axway-central-cli Axway Engage CLI package for managing Amplify Engage resources and DevOps operations. **For more documentation and examples please visit [Amplify Engage CLI documentation portal](https://docs.axway.com/bundle/amplify-central/page/docs/integrate_with_central/cli_central/index.html).** # Installation > **Note:** > OS support: Mac OS, Linux, Windows 10. > Node.js version support: >=12.13.0 > Terminal shell support: Mac Terminal, Linux Terminal, Windows Command Prompt, Windows PowerShell. > Not supported: Cygwin(Windows), Git Bash(Windows). > **Note for existing users**: The "Amplify CLI" core package has been deprecated in favor of the new "Axway CLI" package. The Axway Engage CLI supports both the old Amplify CLI core package and the new Axway CLI core package; however, for the purposes of this ReadME and the CLI command help text you may encounter, all commands that previously used the "amplify" keyword now use the "axway" keyword, even though both keywords are supported. > > Additionally, if you are a current user of the deprecated 'Amplify Engage CLI' package, please uninstall it by running > > ``` > [sudo] axway pm uninstall @axway/amplify-central-cli > ``` > > before following the instructions below to install this 'Axway Engage CLI' package. Assuming you are familiar with [Node.js](https://nodejs.org) and [npm](https://npmjs.com), **ensure you have Node.js >= 12.13.0, and npm >= 6.12.0 installed**. Then, install the [Axway CLI](https://npmjs.com/package/axway), which will give you connectivity to the [Axway Amplify Platform](https://www.axway.com/en/products/amplify). Note that you must first have an account on [https://platform.axway.com](https://platform.axway.com/), and be provisioned in Amplify Engage: ```bash $ [sudo] npm install -g axway ``` Use the Axway package manager command to install the Axway Engage CLI: ```bash # To install latest available version: $ axway pm install @axway/axway-central-cli # If you want to install a specific prod version: $ axway pm install @axway/axway-central-cli@1.0.0 # or a specific tag: $ axway pm install @axway/axway-central-cli@dev ``` ## Additional Installation Steps On Windows After successfully installing axway-central-cli, verify if OpenSSL is installed. OpenSSL is needed to generate public/private key pairs for service account authentication. This is a pre-requisite for the creation of service accounts. Install OpenSSL if not installed already. You can download and install OpenSSL from here [Download OpenSSL](https://slproweb.com/products/Win32OpenSSL.html) After installing OpenSSL, ensure it is added to your path (C:\Program Files\OpenSSL-Win64\bin) in environment variables. Verify if OpenSSL is installed and configured correctly ```bash openssl version ``` # Optional configurations ## Enabling shell autocompletion Our CLI provides autocompletion support for Bash or Zsh (Linux or MacOS), which can save you a lot of typing. - **Zsh** The completion script for Zsh can be generated with `axway engage completion --zsh`. Sourcing the completion script in your shell enables autocomplete for the CLI. ```bash # add autocomplete to zsh for the current shell source <(axway engage completion --zsh) # permanently add autocomplete to zsh echo "source <(axway engage completion --zsh)" >> .zshrc ``` If you get an error like `complete:13: command not found: compdef`, then add the following to the beginning of your ~/.zshrc file: ```bash autoload -Uz compinit compinit ``` - **Bash** If you are on a Mac you may need to install the bash-completion script before you begin. To do so run `brew install bash-completion` The completion script for Bash can be generated with `axway engage completion --bash`. Sourcing the completion script in your shell enables autocomplete for the CLI. ```bash # add autocomplete to bash for the current shell source <(axway engage completion --bash) # permanently add autocomplete to bash echo "source <(axway engage completion --bash)" >> .bashrc ``` # Getting started Log in to the [Axway Amplify Platform](https://www.axway.com/en/products/amplify) using the following command: ```bash # If using a regular account axway auth login # If using a service account axway auth login --client-id --secret-file ``` Log out of the [Axway Amplify Platform](https://www.axway.com/en/products/amplify) using the following command: ```bash $ axway auth logout ``` To see available help, options and examples add `-h` or `--help` option on any command: ```bash $ axway auth logout -h ``` # General usage ```bash USAGE: axway engage [options] Manage APIs, services and publish to the Amplify Marketplace Axway ENGAGE COMMANDS: apply Update resources from a file completion Output shell completion code config Configure Engage CLI settings create Create one or more resources from a file or stdin delete Delete resources edit Edit and update resources by using the default editor get List one or more resources install Install additional platform resources ``` # Commands reference: ## CONFIG Configuration is saved on disk to allow you to be able to use them across commands. ```bash axway engage config [options] CONFIG COMMANDS: list View Engage CLI settings set Set Engage CLI settings ``` ### Region configuration Region configuration identifies the Amplify Engage instance to whose servers you want to send your requests. Your current authenticated account's org setting is used by default (i.e., if your org belongs to the APAC region, it is going to be used automatically). You can always override the current region setting by configuring CLI with the following command (possible values are `US`, `EU` or `AP`): ```bash # to point CLI to EU region: axway engage config set --region=EU # to point CLI to US region: axway engage config set --region=US # to point CLI to APAC region: axway engage config set --region=AP ``` Or by adding optional `--region=` flag with any command: ```bash axway engage get environments --region=EU ``` ### Account configuration In general, it is not needed to manipulate the `account` configuration. CLI should be able to detect the current default account. However, if you want to use a specific account Axway Engage CLI allows you to provide `--account` with every command you run to override your `auth.defaultAccount` config in Axway CLI (you can check its value by running `axway config list` or `axway config get auth.defaultAccount`): ```bash axway engage get environments --account= # for example: axway engage get environments --account=amplify-cli:johndoe@axway.com ``` You can also achieve same goal by running `axway config set auth.defaultAccount ` command when needed. Keep in mind that this value is set automatically when you login to the platform using CLI. ### Extensions: You can set up extensions to the Axway Engage CLI. Extensions can be a npm package, a Javascript file or even an executable. Once set, you would be able to use these extensions as commands from within the Axway Engage CLI. Tip: You can create extensions using our [cli-kit](https://www.npmjs.com/package/cli-kit) which is the same framework used by Axway Engage CLI. ```bash axway engage config set extensions. ``` #### setting extension example: ```bash # set the name and the path to your extension axway engage config set extensions.my-extension '~/myExtension' # my-extension can then be used as a command from the Axway Engage CLI axway engage my-extension ... ``` ### Proxy configuration: **_Note: Please always check Axway CLI docs for the latest proxy configuration instructions._** Axway Engage CLI relies on the Axway CLI configuration for proxy support. To set the proxy URL: ```bash axway config set network.httpProxy http://proxy.int:9090 ``` If the proxy is using a self-signed certificate and you see SSL errors, you can disable the SSL check by setting 'strictSSL' to false: ```bash axway config set network.strictSSL false ``` ### Listing config: You can see all your saved configuration using: ```bash axway engage config ls ``` --- ### Proxies: create/update a proxy: The ability to create/update proxies have been deprecated from the CLI verison 2.19.0 --- ## GET Prints a table of the most important information about the specified resources. If the desired resource type is scoped you will need to specify the scope name by providing `-s, --scope (or /)` flag. You can query for more than one resource if using comma-separated resources in the command (see the examples). Querying for multiple resources will display multiple result tables, one result table for each resource you fetch. To see the list of all available resources on the server run `axway engage get`, for example (not an actual list, always check the CLI for the latest): ``` RESOURCE SHORT NAMES RESOURCE KIND SCOPED SCOPE KIND RESOURCE GROUP accessrequestdefinitions accreqdef AccessRequestDefinition true Environment management accessrequests accreq AccessRequest true Environment management apiserviceinstances apisi APIServiceInstance true Environment management apiservicerevisions apisr APIServiceRevision true Environment management apiservices apis APIService true Environment management apispecs apisp APISpec true K8SCluster management assetmappings assetmpng AssetMapping true Environment management assetmappingtemplates assetmpngtmpl AssetMappingTemplate true Environment management assetreleases assetrelease AssetRelease false catalog assetrequestdefinitions assetreqdef AssetRequestDefinition true Asset catalog assetrequestdefinitions assetreqdef AssetRequestDefinition true AssetRelease catalog assetrequests assetreq AssetRequest true Asset catalog assetrequests assetreq AssetRequest true AssetRelease catalog assetresources assetres AssetResource true Asset catalog assetresources assetres AssetResource true AssetRelease catalog assets asset Asset false catalog consumerinstances consumeri ConsumerInstance true Environment management consumersubscriptiondefs consumersd ConsumerSubscriptionDefinition true Environment management discoveryagents da DiscoveryAgent true Environment management documents docs Document true Asset catalog documents docs Document true AssetRelease catalog environments env Environment false management integrations integ Integration false management k8sclusters k8sc K8SCluster false management k8sresources k8sr K8SResource true K8SCluster management meshdiscoveries meshd MeshDiscovery true Mesh management meshes mesh Mesh false management meshservices meshsvc MeshService true Mesh management meshworkloads meshwrk MeshWorkload true Mesh management releasetags releasetag ReleaseTag true Asset catalog resourcediscoveries resourced ResourceDiscovery true K8SCluster management resourcehooks resourceh ResourceHook true Integration management secrets secret Secret true Integration management secrets secret Secret true Environment management specdiscoveries specd SpecDiscovery true K8SCluster management stages stg Stage false catalog traceabilityagents ta TraceabilityAgent true Environment management webhooks webh Webhook true Integration management webhooks webh Webhook true Environment management ``` ### Fetching, Filtering and Querying You can fetch resources by Resource, by Short Name, or by the specific Resource Name. You can "simple filter" resources by title, tag, and attribute. These simple filters can be used independently or in combination(logical AND), i.e. you can filter by title AND tag AND attribute. However, they only support -singular- filters: you can only filter by _one_ tag, _one_ title, _one_ attribute at a time. For more complex filtering and fetching(e.g. using logical OR, or filterieng by _multiple_ tags, titles, attributes, and other filters), you can also query for resources that match [RSQL-formatted](https://docs.axway.com/bundle/amplify-central/page/docs/integrate_with_central/cli_central/cli_command_reference/index.html#complex-query-filters) query parameters you pass in. See the linked documentation for examples of RSQL query syntax, and the "get examples" below for sample usage. Note: Using the --query flag will override any --title, --tag or --attribute flags you use. ### get usage ```text USAGE: axway engage get [options] [] Display one or many resources. GET ARGUMENTS: args... Command arguments, run "axway engage get" to see the examples GET OPTIONS: --attribute [key=value] Attribute in key=value pair format to filter by --no-cache Do not use cache when communicating with the server --account [value] Override your default account config --language=[langCode] Show the language detail of the retruned object. One of: * | fr-fr | en-us | de-de | pt-br --languageDefinition=[langCode] Show the language definition constraint of the returned object. One of: fr-fr | en-us | de-de | pt-br -o, --output [value] Additional output formats. One of: yaml | json -q, --query [RSQL query] RSQL-formatted query to search for filters that match specific parameters --region [value] Override your region config -s, --scope [[name|kind/name]"] Scope name or kind/name for scoped resources --tag [tag] Tag of resource(s) to fetch --title [title] Title of resource(s) to fetch ``` ### get examples ```bash # get all environments axway engage get envs # get all environments in yaml format axway engage get environments -o yaml # get environment by Resource/Common name in json format axway engage get env myenv -o json # get all webhooks axway engage get webhooks # get all webhooks by Short Name axway engage get webh # get all webhooks and apiservices by Short Name axway engage get webh,apis # get all environments and api services axway engage get envs,apisvc # get environment and apiservice which matches a Resource/Common Name in a specified scope(scope is required ater -s flag) in json format axway engage get env,apisvc commonname -s env1 -o json # get apiservice with name "testsvc" in the scope "Environment" with name "testenv" axway engage get apisvc testsvc -s Environment/testenv # get product with name "testproduct" with all available language information and output in json axway engage get products testproduct --language="*" -o json # get assets with titles that start with "a" axway engage get assets -q "title==a*" # get assets with titles that start with a or i axway engage get assets -q "title==a* or title==i*" # get assets with tags that match tag1 or tag2 axway engage get assets -q "tags=in=(tag1,tag2)" # get assets and filter the list to assets that have a specific title "test" axway engage get assets --title test # get assets and filter the list to assets that have a specific tag "tag1" axway engage get assets --tag tag1 # get assets and filter the list to assets that have a specific attribute "location=arizona" axway engage get assets --attribute location=arizona # get assets and filter the list with a combination of title, tag and attribute filters axway engage get assets --title test --tag tag1 --attribute location=arizona # To get a product with name "test-product" with French language translation if available in YAML format axway engage get products test-product --language="fr-fr" -o yaml # To get a product with name "test-product" with German language translation if available in YAML format axway engage get products test-product --language="de-de" -o yaml # To get a product with name "test-product" with US English language translation if available in YAML format axway engage get products test-product --language="en-us" -o yaml # To get a product with name "test-product" with Portugal language translation if available in YAML format axway engage get products test-product --language="pt-br" -o yaml # To get a stage with name "demo-stage" with the French language translation in JSON format axway engage get stages demo-stage --languageDefinition="fr-fr" -o json # To get a stage with name "demo-stage" with the US English language translation in JSON format axway engage get stages demo-stage --languageDefinition="en-us" -o json # To get a stage with name "demo-stage" with the German language translation in JSON format axway engage get stages demo-stage --languageDefinition="de-de" -o json # To get a stage with name "demo-stage" with the Portugese language translation in JSON format axway engage get stages demo-stage --languageDefinition="pt-br" -o json ``` --- ## CREATE ```text USAGE: axway engage create [options] Create one or more resources from a file or stdin CREATE COMMANDS: agent-resource Create an agent resource environment Create an environment with the specified name CREATE OPTIONS: --account [value] Override your default account config --no-cache Do not use cache when communicating with the server -f, --file [path] Filename to use to create the resource -o, --output [value] Additional output formats. One of: yaml | json --region [value] Override your region config -y, --yes Automatically reply "yes" to any command prompts. ``` ### create: multiple resources from a file ```text USAGE: axway engage create -f ``` ### create: specific resource by name **_Note: Only environments are currently available for this command._** ```text USAGE: axway engage create environment [options] Create an environment with the specified name ENVIRONMENT ARGUMENTS: name Name of new environment CREATE OPTIONS: --account [value] Override your default account config --no-cache Do not use cache when communicating with the server -f, --file [path] Filename to use to create the resource -o, --output [value] Additional output formats. One of: yaml | json --region [value] Override your region config -y, --yes Automatically reply "yes" to any command prompts. ``` ### create examples ```bash # create new environment with "newenv" name axway engage create env newenv # create new environment with "newenv" name and output result in yaml axway engage create environment newenv -o yaml # create multiple resources from file axway engage create -f ./some/folder/resources.yaml # create an agent resource axway engage create agent-resource ``` --- ## APPLY (create or update) The resource name must be specified in the file. This resource will be created if it doesn't exist yet. > **Note:** apply command removes the resourceVersion from metadata of the resource to avoid conflict of resource creation ```text USAGE: axway engage apply [options] Update resources from a file APPLY OPTIONS: --account [value] Override your default account config -f, --file [path] Filename to use to create or update the resources. One of: yaml | json --language [langCode] Only update language portion. One of: fr-fr | en-us | de-de | pt-br --no-cache Do not use cache when communicating with the server -o, --output [value] Additional output formats. One of: yaml | json --region [value] Override your region config --subresource [name] Name of the 1 subresource to update. Will prevent main resource and all other subresources from being updated. -y, --yes Automatically reply "yes" to any command prompts. ``` ### apply examples ```bash # create or update multiple resources from file axway engage apply -f ./some/folder/resources.yaml # create or update multiple resources from file and output results in YAML format axway engage apply -f ./some/folder/resources.json -o yaml # only update 1 language "en-us" for multiple resources from file axway engage apply -f ./some/folder/resources.yaml --language en-us # only update 1 subresource named "state" for multiple resources from file axway engage apply -f ./some/folder/resources.yaml --subresource state ``` --- ## SUB-RESOURCES CREATE/UPDATE File content used for `create` or `apply` commands allows the creation or updates to the sub-resources by providing values as part of the payload in the file (in the same way the APIs return it). For example, using this payload for an `Asset` resource will create `x-custom` and `state` sub-resources for an `Asset` "testasset": ```yaml --- apiVersion: v1alpha1 kind: Asset name: testasset title: title spec: type: API x-custom: x-custom value state: state value ``` --- ## DELETE Delete resources by type and name or by filename. When deleting a resource by its name, if the desired resource type is scoped, you will need to specify the scope name by providing `-s, --scope (or /)` flag. If the resource might exist in multiple scopes a prompt will be displayed to prevent the unintended deletion of multiple resources. You can skip this prompt by providing `-y, --yes`flag. To see the list of all available resources on the server run `axway engage delete`. ```text USAGE: axway engage delete [options] [] Delete resources DELETE ARGUMENTS: args... Command arguments, run "axway engage delete" to see the examples DELETE OPTIONS: --account [value] Override your default account config --no-cache Do not use cache when communicating with the server -f, --file [path] Filename to use to delete the resource. --region [value] Override your region config -s, --scope [name] or [kind/name] Scope name or kind/name for scoped resources. --wait Wait for the resources to be completely deleted. -y, --yes Automatically reply "yes" to any command prompts. --forceDelete Force delete a resource (Warning: Ignores finalizers on the resource and the resources scoped under it) ``` ### delete examples ```bash # delete environment by name axway engage delete environment newenv # delete api service by name (a scoped resource) axway engage delete apisvc someapisvc -s newenv # delete document with name "somedoc" in all scopes named "somescope" without confirmation prompt axway engage delete docs somedoc -s somescope -y # delete document with name "somedoc" in all scope "AssetRelease" named "somescope" axway engage delete docs somedoc -s AssetRelease/somescope -y # delete all resources specified in the file axway engage delete -f ./some/folder/resources.yaml # force delete environment by name with a prompt axway engage delete environment newenv --forceDelete # force delete API service by name (a scoped resource) with a prompt axway engage delete apisvc someapisvc -s newenv --forceDelete # force delete all resources specified in the file without a prompt axway engage delete -f ./some/folder/resources.yaml --forceDelete --yes ``` --- ## EDIT ```text USAGE: axway engage edit [options] Edit and update resources by using the default editor EDIT COMMANDS: environment Edit an environment with the specified name. EDIT OPTIONS: --account [value] Override your default account config --no-cache Do not use cache when communicating with the server -o, --output [value] Additional output formats. One of: yaml|json --region [value] Override your region config ``` ### edit: resource by name _Using "environment" as an example._ ```text USAGE: axway engage edit environment [options] Edit an environment with the specified name. ENVIRONMENT ARGUMENTS: name Name of the environment EDIT OPTIONS: --account [value] Override your default account config --no-cache Do not use cache when communicating with the server -o, --output [value] Additional output formats. One of: yaml|json --region [value] Override your region config ``` ### edit examples ```bash # delete environment by name axway engage edit environment newenv ``` --- ## INSTALL (axway engage / platform resources) ```text USAGE: axway engage install [options] [] Install additional platform resources INSTALL COMMANDS: agents Install Amplify API Gateway / Amazon API Gateway / Azure API Gateway / Istio / Apigee X Gateway / GitHub / GitLab / Kafka / SwaggerHub INSTALL ARGUMENTS: args... Command arguments, run "axway engage install" to see the examples INSTALL OPTIONS: --account [value] Override your default account config --no-cache Do not use cache when communicating with the server --region [value] Override your region config ``` ### install: agents configuration ```text USAGE: axway engage install agents [options] Amplify API Gateway / Amazon API Gateway / Azure API Gateway / Istio / Apigee X Gateway / GitHub / GitLab / Kafka / SwaggerHub INSTALL OPTIONS: --account [value] Override your default account config --no-cache Do not use cache when communicating with the server --region [value] Override your region config ``` ### install examples ```bash # install agent configuration in interactive mode axway engage install agents ``` --- ## Author Axway https://axway.com ## License This code is proprietary, closed source software licensed to you by Axway. All Rights Reserved. You may not modify Axway’s code without express written permission of Axway. You are licensed to use and distribute your services developed with the use of this software and dependencies, including distributing reasonable and appropriate portions of the Axway code and dependencies. Except as set forth above, this code MUST not be copied or otherwise redistributed without express written permission of Axway. This module is licensed as part of the Axway Platform and governed under the terms of the Axway license agreement (General Conditions) located here: [https://support.axway.com/en/auth/general-conditions](https://support.axway.com/en/auth/general-conditions); EXCEPT THAT IF YOU RECEIVED A FREE SUBSCRIPTION, LICENSE, OR SUPPORT SUBSCRIPTION FOR THIS CODE, NOTWITHSTANDING THE LANGUAGE OF THE GENERAL CONDITIONS, AXWAY HEREBY DISCLAIMS ALL SUPPORT AND MAINTENANCE OBLIGATIONS, AS WELL AS ALL EXPRESS AND IMPLIED WARRANTIES, INCLUDING BUT NOT LIMITED TO IMPLIED INFRINGEMENT WARRANTIES, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, AND YOU ACCEPT THE PRODUCT AS-IS AND WITH ALL FAULTS, SOLELY AT YOUR OWN RISK. Your right to use this software is strictly limited to the term (if any) of the license or subscription originally granted to you.