Skip to main content
Version: ACE 5

ACE CLI

Deployment in ACE5 can be managed using the ACE CLI tool ace-cli.

The tool can be installed locally as NPM package or used directly from the ace-deployment-server service where it is packed as part of the docker image.

NPM package installation​

Connect to the sapiens-registry feed and install the tool globally using a package manager.

Connect to the registry​

Add a .npmrc file to your user or root directory (e.g., ~/.npmrc or $PREFIX/.npmrc) and populate it with the following contents:

registry=https://pkgs.dev.azure.com/spnsdigital/_packaging/sapiens-registry/npm/registry/ 
                        
always-auth=true
note

If the .npmrc file already exists, extend it instead

Setup token in Windows​

Run vsts-npm-auth to get an Azure Artifacts token added to your .npmrc file:

vsts-npm-auth -config <path-to-your-npmrc-file>

Setup token in Linux​

Generate token​

Generate a Personal Access Token from Azure User settings -> Personal access tokens with Packaging read & write scopes.

Populate .npmrc​

Copy the code below to your .npmrc file:

; begin auth token
//pkgs.dev.azure.com/spnsdigital/_packaging/sapiens-registry/npm/registry/:username=spnsdigital
//pkgs.dev.azure.com/spnsdigital/_packaging/sapiens-registry/npm/registry/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
//pkgs.dev.azure.com/spnsdigital/_packaging/sapiens-registry/npm/registry/:email=npm requires email to be set but doesn't use the value
//pkgs.dev.azure.com/spnsdigital/_packaging/sapiens-registry/npm/:username=spnsdigital
//pkgs.dev.azure.com/spnsdigital/_packaging/sapiens-registry/npm/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
//pkgs.dev.azure.com/spnsdigital/_packaging/sapiens-registry/npm/:email=npm requires email to be set but doesn't use the value
; end auth token

Base64 encode token​

Base64 encode the Personal Access Token (PAT) from the previous step. You can run the following script to encode the token using node:

node -e "require('readline') .createInterface({input:process.stdin,output:process.stdout,historySize:0}) .question('PAT> ',p => { b64=Buffer.from(p.trim()).toString('base64');console.log(b64);process.exit(); })"

Replace both [BASE64_ENCODED_PERSONAL_ACCESS_TOKEN] values in your .npmrc file with the base64 encoded token.

Install the package​

Install the tool with your preferred package manager globally:

# npm
npm install -g @sapiens-digital/ace-cli
# yarn (alternative)
yarn global add @sapiens-digital/ace-cli

Using the CLI​

From local installation​

Since ace-cli commands call the ace-deployment-server, it is recommended to set the appropriate DEPLOYMENT_SERVICE_URL environment variable to avoid manually passing the url as a flag every time.

Use the ace-cli command to inspect available commands. The --help flag is available to expand information for a specific command, e.g.:

ace-cli <command> --help

From deployment service​

It is not necessary to configure DEPLOYMENT_SERVICE_URL for the ace-cli tool when using it directly from the ace-deployment-server container. The ace-cli tool will point to the local service by default.

Execute commands as usual:

ace-cli <command>

Available commands​

deploy schedules​

The deploy schedules command installs all schedules found in the workspace to the environment at DEPLOYMENT_SERVICE_URL. Once schedules are installed they will start executing based on the specified pattern.

new

This command can be used in place of the ace-versioning sync-scheduler command.

Usage
ace-cli deploy schedules (--git <url> | --folder <path> | --zip <path>) [...flags for '--git' mode]
Flags
  -a, --authToken=<value>  (env: DEPLOYMENT_SERVICE_AUTH_TOKEN) authorization token for deployment service

  MODE FLAGS
    -g, --git=<value>     specify workspace details using '--branch', '--token', '--workspacePath', '--commit', '--username'
    -w, --folder=<value>
    -z, --zip=<value>

  MANDATORY FLAGS
    -u, --deploymentServiceUrl=<value>  (required) (env: DEPLOYMENT_SERVICE_URL) url of the deployment service

  GIT MODE FLAGS
    --branch=<value>         (default: 'master')
    --commit=<value>         if left empty, target latest commit
    --token=<value>          (required)
    --username=<value>
    --workspacePath=<value>  (default: '/src/ace') this is the path to your workspace in the repository (e.g., '/src/ace')
Examples
# deploy from a git repository:
  ace-cli deploy schedules --git https://dev.azure.com/myproj/proj/_git/ace --branch release-v1.0 --token d3a97sax0clma00nax

# deploy from a local workspace (make sure to specify the workspace root if the entire repository is present - e.g., '/src/ace'):
  ace-cli deploy schedules --folder ./ace-workspace/src/ace/

# deploy from an exported workspace zip file:
  ace-cli deploy schedules --zip ./ace-workspace.zip

deploy workspace​

The deploy workspace command installs a workspace to the environment at DEPLOYMENT_SERVICE_URL.

new

This command can be used in place of the ace-versioning import-git command.

Usage
ace-cli deploy workspace (--git <url> | --folder <path> | --zip <path>) [...flags for '--git' mode]
Flags
  -a, --authToken=<value>  (env: DEPLOYMENT_SERVICE_AUTH_TOKEN) authorization token for deployment service
  -s, --skipPackageInstallation=<value> (default: false) if set to true will skip ACE package installation
  --merge                        whether the source workspace should merge with the existing deployment instead of replacing it
  --secrets=<value>...           Pass multiple secrets for env variable replacement in package.yaml file, use format name=value, e.g. --secrets name1=value1
                                 name2=value2

MODE FLAGS
  -g, --git=<value>     specify workspace details using '--branch', '--token', '--workspacePath', '--commit', '--username'
  -w, --folder=<value>
  -z, --zip=<value>

MANDATORY FLAGS
  -u, --deploymentServiceUrl=<value>  (required) (env: DEPLOYMENT_SERVICE_URL) url of the deployment service

GIT MODE FLAGS
  --branch=<value>         (default: 'master')
  --commit=<value>         if left empty, target latest commit
  --token=<value>          (required)
  --username=<value>
  --workspacePath=<value>  (default: '/src/ace') this is the path to your workspace in the repository (e.g., '/src/ace')
Examples
# deploy from a git repository:
ace-cli deploy workspace --git https://dev.azure.com/myproj/proj/_git/ace --branch release-v1.0 --token d3a97sax0clma00nax

# deploy from a local workspace (make sure to specify the workspace root if the entire repository is present - e.g., '/src/ace'):
ace-cli deploy workspace --folder ./ace-workspace/src/ace/

# deploy from an exported workspace zip file:
ace-cli deploy workspace --zip ./ace-workspace.zip

install dependencies​

The install command installs dependencies according to a workspace package.yaml file to a specified filesystem directory.

Usage
ace-cli install -w <value> -d <value> [--secrets <value>]
Flags
  -d, --dependencyPath=<value>  (required) Path where the dependencies should be installed to
  -w, --workspacePath=<value>   (required) [default: <cwd>] Path to the workspace which should contain a package.yaml file, e.g. /user/src/ace. 
  --secrets=<value>...          Pass multiple secrets for env variable replacement in package.yaml file, use format name=value, e.g. --secrets name1=value1
                                name2=value2

bundle workspace into zip file​

The bundle command bundles the workspace and resolved dependencies into a conveniently formatted zip file for deploying and importing into ACE UI.

Usage
ace-cli bundle -w <value> -d <value> -o <value> [-r <value>]
Flags
  -d, --dependencyPath=<value>  (required) Path where the dependencies are located
  -o, --out=<value>             (required) Path to the which bundled zip file should be saved.
  -r, --repositoryPath=<value>  [default: <cwd>] Path to the repository.
  -w, --workspacePath=<value>   (required) [default: <cwd>] Path to the workspace which should contain a package.yaml file, e.g. /user/src/ace.

merge​

danger

This functionality is removed since 25.1.0.

The merge command is also available in the ace-runtime-server service and is used for merging workspaces in the container filesystem for deployment purposes.

Usage
ace-cli merge <from> <to> (--verbose)

The command accepts two paths. All workspace items in the source path (<from>) will be merged with the target path (<to>). The merge happens as follows:

For APIs​

Overwrites new operations, leaves other operations as-is. Overwrites non-operation properties with new ones.

API
# source (api.yaml)
description: "Pets v1.0.0"
paths:
  /pet:
    get:
      description: Retrieves the pet
    post:
      description: Updates the pet

# target (api.yaml)
description: "Pets v0.0.0"
paths:
  /pet:
    delete:
      description: Deletes the pet
    post:
      description: Method not supported

# target after merge
description: "Pets v1.0.0"
paths:
  /pet:
    get:
      description: Retrieves the pet
    delete:
      description: Deletes the pet
    post:
      description: Updates the pet

For Variables​

Overwrites new variables, leaves other variables as-is.

Variables
# source (env.yaml)
variables:
  - name: GIT_URL
    value: https://prod.git.com
  - name: SERVICE_URL
    value: https://service.com

# target (env.yaml)
variables:
  - name: GIT_URL
    value: https://dev.git.com
  - name: ENABLE_LOGS
    value: https://service.com

# target after merge
variables:
  - name: GIT_URL
    value: https://prod.git.com
  - name: SERVICE_URL
    value: https://service.com
  - name: ENABLE_LOGS
    value: https://service.com

For other files​

Other files (flows, schemas, etc.) will have their content overwritten if there is a newer item present in the source.

clear-data redisCache​

The clear-data redisCache is used to clear cache from redis database

new

This command can be used in place of the ace-versioning clear-redis-cache command.

Usage
ace-cli clear-data redisCache -u <value>
Flags
 -a, --authToken=<value>  (env: DEPLOYMENT_SERVICE_AUTH_TOKEN) authorization token for deployment service

MANDATORY FLAGS
  -u, --deploymentServiceUrl=<value>  (required) (env: DEPLOYMENT_SERVICE_URL) url of the deployment service