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:

@sapiens-digital:registry=https://pkgs.dev.azure.com/spnsdigital/_packaging/sapiens-registry/npm/registry/
@sapiens: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​

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​

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.

validate workspace​

The validate command validates the workspace and logs the validation errors to the output. Monorepo path and dependencies are optional flags. If provided, the workspace is validated with resolved dependencies. Dependencies can be installed using install command.

Usage
ace-cli validate workspace [-z <value>] [-r <value>] [-w <value>] [-d <value> ]
Flags
  -z, --zip=<value>               Path to a workspace zip file to validate
  -r, --repo=<value>              Path to monorepo dependencies folder when workspace path is used for validation
  -w, --workspacePath=<value>     Path to a workspace folder to validate
  -d, --dependenciesPath=<value>  Path to folder where git dependencies are installed when workspace path is used for validation
Examples
  $ ace-cli validate workspace --zip ./ace-workspace.zip

  $ ace-cli validate workspace --repo ./repoPath --workspacePath ./repoPath/workspacePath --dependenciesPath ./dependenciesPath

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