Solution CLI

As a prerequisite to use the Solution CLI on your local system, it is necessary to install Node.js on your machine. Currently Node.js version 20.11.1 or higher is supported. Therefore, please make sure that you've installed the a supported version before you continue with installing the Solution CLI.

Helping links:

• Node.js
• Download Node.js Version20.x

1. Go to Solution Designer and open your modelled project.

2. At the bottom you will find a menu bar, click on Solution CLI to expand the bar.

3. Inside this pane, click on Solution CLI Setup to expand the section. You will find instructions on how to install and set up the CLI.

4. Click on the provided link to download the CLI.tar file.

5. After successfully downloading the file, open a terminal on your machine and paste in the following code to install the CLI on your computer (replace <download folder> with the folder you have downloaded the CLI.tar to):

   npm install --location=global file:<download folder>/CLI.tar

   If you are using a npm version < 8.11.0 or the k5 command is not found on your machine, try reinstall the CLI with the following command:

   npm install -g file:<download folder>/CLI.tar

6. Switch back to the Solution CLI Setup section in Solution Designer and download cli-config.json by clicking on the provided link

7. Run the following command in your terminal to set up the CLI (replace <download folder> with the folder you have downloaded the cli-config.json to):

    k5 setup --file <download folder>/cli-config.json

Switches to another git branch in your local project and triggers model validation and code generation based on the content of the branch. This command is used to isolate and parallelize feature development in your project. For the initial checkout, it will get the latest pushed state on the remote branch, but if you have checked out your branch locally before, it will just switch to your local state of the branch (similar as the native git checkout command). So it might be necessary to trigger a k5 pull afterwards if you want to keep your branch update your branch to the remote state.

Clones a project created in the Solution Designer to the local file system, validates the provided model and triggers code generation automatically. It requires two parameters:

• The project which consists of the group key and the project acronym
• The Git provider alias.

Command options:

Compile project files.

Displays the documentation of the Solution CLI.

Install or update all dependencies of the project.

Check project files for linting errors.

Used to log in to Solution Envoy for local debug/test support. It will ask for the Solution Envoy credentials.

Command options:

It will ask for the same credentials as the Solution Designer, the login is usually valid for a longer period, as defined by your company policies.

Command options:

Used to prepare debug sessions against the configured Solution Envoy environment. It will ask for the Solution Envoy credentials.

Pull in the latest changes of the current branch from the Git repository you are currently on, validate the model and generate code.

During the pull command, your local Git configurations will be applied automatically. If no value for the rebase strategy is set, pull.rebase=false will be applied as a default (Please check the Git documentation for further information). You can list all your set Git configurations by running git config -l.

Add, commit and push changes to the Git repository.

Command options:

Set up the Solution CLI to work with a Solution Envoy instance.

Command options:

Used to set up the Solution CLI to work with a Solution Designer installation. It takes all configuration as a base64 encoded string.

Command options:

For projects based on a Node.js stack:

• Runs integration tests defined within the src-impl folder, they are used to test implemented services against a runtime environment.

For projects based on a Java stack:

• The command maven test will be executed.

Generate code (solution framework and stub files) based on the design model files in the local directory {PROJECT_ROOT}/src-design.

Upgrade the Solution CLI to the latest version.

Validates the design model files in the local directory {PROJECT_ROOT}/src-design and displays all validation errors and warnings in the command line. Additionally, a log file will be written at {PROJECT_ROOT}/logs/validationErrors.log which holds more information about the validation issues and how to fix them.

There can be 2 different type of validation issues:

1. Invalid yaml content The yaml files in directory the {PROJECT_ROOT}/src-design need to be provided in a specific format (e.g. have required fields). If the format is not as expected, it will lead to unexpected behavior during your further development. In this case, the validation issues will mention all places where the format of the yaml files is invalid.

2. Invalid design model Even if the structure of the yaml files is valid, it can be that the defined design model itself is invalid or doesn't follow best practices. E.g. if a selection element property is defined without any enum values. In this case, the validation issues will give an overview of what is expected from a logically valid design model and help you with fixing the issues.

Displays the current version of the Solution CLI.

If you want to use a local feature branch for your development, you can use native Git commands and Solution CLI commands. This can be a helpful approach in case that your feature only requires changes in the implementation and you do not plan to make any changes in the Solution Designer.

Please execute the following steps:

1. Run git branch feature_01 to create a new local branch with the name "feature_01"
2. Run k5 checkout feature_01 to checkout the new branch
3. Implement changes in project files
4. Run k5 compile to ensure that your code is not having any compile issues
5. Push your local branch to the remote Git git push --set-upstream origin/feature_01 to make it available for everybody

During development, it keeps happening that the remote feature branch is ahead of your local branch. This especially occurs if changes in the Solution Designer were made and pushed or if multiple people are working on the same branch. In this situation, the command k5 push might fail and will not allow you to push to the remote branch and you first need to merge the remote branch into your local branch.

Please execute the following steps:

1. Run k5 pull to pull the remote state of the feature branch
   • If Git detects conflicts within uncommited changes during the pull, you'll be asked to commit or stash your local changes first. You can resolve this by running native Git commands (e. g. git add, git commit, git stash) and triggering k5 pull again.
2. In case of merge conflicts in your files you will be asked to resolve them manually
   • After resolving all conflicts, it is required to trigger the command k5 generate-code, so that the code is generated based on the latest local state
3. If no conflicts happened, the k5 pull command already generated the code automatically
4. If validation errors occur during code generation, please fix them and trigger k5 generate-code again
5. Run k5 compile to ensure that your code is not having any compile issues

For merging feature branches into default branches after development is done, it is recommended to use the native tools and processes set up in your Git provider. If the target branch is ahead of the feature branch, it might be necessary to merge those changes into your feature branch first.

To resolve this, please execute the following steps:

1. Run git fetch --all in your local terminal
2. Run git merge origin/<targetBranchName> to merge the latest state of the target branch into your local feature branch
   • In case of conflicts that appear during merging, please resolve them manually
3. Run k5 generate-code to trigger code generation again by using the merged state
   • This is neccessary to ensure that your implementation is still correct
   • If validation errors occur during code generation, please fix them and trigger k5 generate-code again
4. Run k5 compile to check for compilation issues and fix them if necessary
5. Run k5 push to push the local changes to your remote feature branch again
6. Your remote feature branch should now be ready to be merged into the target branch

The Solution CLI allows you to communicate directly with the cluster in order to provide local debugging.

After your project has been successfully deployed at least once you can connect the Solution CLI with the Solution Envoy running inside the deployment target of your choice. Typically, this would be a DEV environment or stage.

To connect the CLI with the Solution Envoy follow the steps below:

1. In the navigation bar on the left click on CI/CD.

2. On the Pipeline Configurations tab select the deploy pipeline configuration that points to the deployment target you want to work on

3. Click on the link to the Solution Envoy inside the row. This will open a new tab and lead you to the Solution Envoy.

4. Log in to Solution Envoy with valid credentials.

5. In the left navigation bar, click on Infrastructure and use the Download button on the Solution CLI Setup card to download the configuration file.

6. Now cd into the root of your project folder

7. Run the following command to set up the CLI (replace with the folder you have downloaded the file to and replace with the actual name of the downloaded file):

   k5 setup-envoy --file <download folder>/<filename>

8. After you have set up the CLI configuration you can connect to the cluster by executing the following command:

   k5 prepare-debug

If you are not already logged in to this deployment target, you will be prompted to enter your credentials. The CLI will then request a token for authentication against the deployment target's endpoint.

After having successfully logged in, you can start debugging from your local machine without having to run the pipeline.