GenAIz CLI

_{Genaiz Version 1.0.7}

The GenAIz CLI is a tool for creating, building and publishing Smart Functions to the GenAIz Orchestration platform. It also provides toolkits to manage Orchestrated Workspaces and execute their Workflows.

Installation
Running the GenAIz CLI
Development Guide
- Prerequisites
- Building from source
Troubleshooting
- GoLang
- Docker
Contributing
License

Installation

The genaiz command line tool can be downloaded from the Releases of this repository. There is also a GenAIz Setup Action, which can be used to configure GitHub Action Workflows.

Running the GenAIz CLI

Working with the GenAIz CLI is a simple series of commands. You may run genaiz --help at any time to get a list of available commands and their options.

Quickstart Examples

Creating a simple solution

The following example creates a solution solution-1 and a smart function my-bash-example using the recipe bash-example. It then builds the function with the default version assigned by create, 1.0.0, assigns a single node to the default workflow, authenticates a user with dev.genaiz.com and publishes the solution to the broker.

genaiz sn create mySolutionDir --name="My Solution" --handle="solution-1" \
  --oem="com.genaiz.examples" --description="A Description"
cd mySolutionDir
genaiz sf create mySmartFunction --recipe="bash-example" \
  --oem="com.genaiz.examples" --name="My Bash Example"
cd mySmartFunction
genaiz sf build
cd ..
genaiz wf nodes add default node1 --name="Single Node" \
  --description="My Single Node" \
  --sf="com.genaiz.examples/mySmartFunction:1.0.0"
genaiz ac login dev.genaiz.com
genaiz sn publish

Running a simple function

The following example creates a smart function function-1, without a parent solution. It then proceeds to build it out of context. We can then list and run the smart function on a local Docker installation within the folder created or out of it.

genaiz sf create function-1 --oem="com.genaiz.examples" --recipe="bash-example"
genaiz sf build --context=function-1/
cd function-1
genaiz sf list
genaiz sf run

Note

Run disposes of any container created for the operation

Testing a simple function with Properties

The following example creates a smart function function-2, without a parent solution. We then proceed to add property specifications to the function. The example completes with building the function in context, and testing it with the console attached using test.

genaiz sf create function-2 --oem="com.genaiz.examples" \
  --recipe="bash-example"
cd function-2
genaiz sf prop add MY_KEY --name="Key Example" \
  --default-value=10 --type=int
genaiz sf prop env MY_KEY 12
genaiz sf build
genaiz sf test

Testing a simple function with Data Link Properties

The following example creates a smart function function-3, without a parent solution. We then proceed to create and publish a data link datalink-1 and add it to the smart function for provisioning on a broker.

genaiz sf create function-3 --oem="com.genaiz.examples" --version="0.2.0" \
  --recipe="bash-example"
cd function-3
genaiz dk create datalink-1 --oem="com.genaiz.examples" --version="1.0.0" \
  --description="My DataLink"
cd function-3
genaiz data source add com.genaiz/datalink-1:1.0.0
genaiz sf build
genaiz ac login dev.genaiz.com
genaiz sf publish

Result Values

Support for result values is provided on genaiz sf publish only. From manually edited settings, for example:

function:
  build:
    repository: com.genaiz/result-values
    version: latest
  publish:
    handle: result-values
    name: result-values
    oem: com.genaiz
    resultvalues:
      - excel
      - valid-set
    type: function
    version: 1.0.0
  run:
    input: run/in
    log: run/{timestamp}/log
    output: run/{timestamp}/out
    var: run/{timestamp}/var

Auto-Completion

Auto-completion in Bash and other shell types can be achieved by generating the corresponding script file and sourcing it inside the terminal session:

genaiz completion --help
genaiz completion bash > ~/.config/genaiz/completion.sh
source ~/.config/genaiz/completion.sh

For Bash, the source instruction can be added to $HOME/.bashrc or $HOME/.bash_profile, depending on your terminal shell's configuration.

Account Management

login to OIDC enabled brokers

The account command can be used to authenticate with multiple OIDC enabled brokers with valid account credentials.

genaiz ac login dev.genaiz.com
genaiz ac list
genaiz ac login lab.genaiz.com
genaiz ac activate dev.genaiz.com
genaiz ac list --json

The command should print a JSON array with the sessions currently known to the SDK. Logging out of a session can be achieved by specifying the host account to log out or by simply logging out of the active session without adding any host argument:

genaiz ac logout dev.genaiz.com
genaiz ac logout

Environment logins for CI/CD

To facilitate a secure in-memory mechanism for handling credentials, the genaiz cli can use a combination of environment variables.

GENAIZ_AUTH_URL: the url that would be used on genaiz ac login command
GENAIZ_AUTH_SESSION: the session token emitted by a previous ac login command for that host

These 2 bits of information can be used on CI/CD configurations to avoid having to write a .auth file under $HOME/.cache/genaiz for a given session. The session token should typically be held in the Secrets of the CI/CD pipeline in need of calling the genaiz cli.

Datalink Management

When a Smart Function requires a connection to a service, Datalinks provide a schema for the required connection parameters to establish the connection. Orchestration deployments will typically only allow certain Datalink definitions to be used, the records managed by Admins.

The GenAIz CLI provides tooling for creating, publishing and assigning data source and store properties for the execution of a Smart Function.

Creating a Local Datalink

Datalink commands will write definitions under $HOME/.config/genaiz/Genaiz.yaml by default. The following commands are an example of how to define a new Datalink. Create will assume the version by default is always 1.0.0

genaiz dk create com.genaiz.examples/datalink-1 --name='DataLink 1'
genaiz dk prop add com.genaiz.examples/datalink-1:1.0.0 MY_KEY
genaiz dk prop add com.genaiz.examples/datalink-1:1.0.0 MY_KEY_2
genaiz dk prop edit com.genaiz.examples/datalink-1:1.0.0 MY_KEY_2 --name='My Key'
genaiz dk prop rm com.genaiz.examples/datalink-1:1.0.0 MY_KEY
genaiz dk prop add com.genaiz.examples/datalink-1:1.0.0 MY_KEY --secret

Publishing a Datalink

To be able to publish a Datalink a user needs to be logged in as an admin

genaiz ac login dev.genaiz.com
genaiz dk publish com.genaiz.examples/datalink-1:1.0.0

Workspace Management

Creating a Workspace

The GenAIz CLI provides commands to help manage workspaces associated with an account on a GenAIz Orchestration service.

genaiz workspace create myWorkspace

A Workspace is the root for all Solution executions. Once a Workspace is created, Solution Workflows need to be instantiated in terms of Workspace Flows.

genaiz workspace flow create myWorkspace com.genaiz/mySolution:1.0.0 myWorkflowHandle

Updating Workspace Nodes

With a workspace created and a solution workflow assigned to a workspace flow, a user can assign previously published Data sources and stores.

genaiz workspace node data source add myWorkspace myWorkflowHandle \
  mySmartFunctionHandle myDsName
genaiz workspace node data source rm myWorkspace myWorkflowHandle \
  mySmartFunctionHandle myDsName
genaiz workspace node data store add myWorkspace myWorkflowHandle \ 
  mySmartFunctionHandle myDsName
genaiz workspace node data store rm myWorkspace myWorkflowHandle \
  mySmartFunctionHandle myDsName

Credentials Management

The GenAIz CLI provides a way to manage Data Sources and Data Stores which would be used either with a Workspace on an Orchestration, or locally with the run, start and test commands.

The facilities are there to fortify usage of potentially sensitive information on local developer environments. Currently, those keys are still held in clear text in .env files, which is not recommended at large.

Creating a Data Locker

For Sources (read-only) or Stores (read/write) connections, a locker can be created and updated with:

genaiz locker init
genaiz locker source add myLocalHandle com.genaiz/my-link:1.0.0
genaiz locker source update myLocalHandle MyKey MyValue
gpg --decrypt myKeyfile.gpg | genaiz locker source update myLocalHandle MySecretKey

Publishing from a Data Locker

For Sources or Stores, a user can publish his configuration to an account on previously established session.

genaiz locker source publish myLocalHandle
genaiz locker store publish myLocalHandle --locker=myLockerFile.bin

Development Guide

Prerequisites

To be able to build the project you will need to install the following tools for your platform. You can find more information at the links provided here:

Golang - All tools and the SDK are written in Go
GNU Make - Not strictly required, but all build scripts are driven through Makefiles
Docker - The local execution and build runtime requires a local Docker installation

Building from Source

cd genaiz-cli
make genaiz/install

Tip

It is possible $HOME/go/bin is not included within a users' path. That can be fixed with export PATH=$PATH:$HOME/go/bin added to the users' .bashrc, .bash_profile or .profile file, depending on the OS and distribution.

Building the individual modules can be achieved in the same manner or simply by running the install target on the root project:

make install

Print a summary of all make targets by entering

make help

Troubleshooting

Golang

Go tools tag

We use 2 different environment builds. The prod build is the build configured by default under the Makefile of the project. It builds with an HTTP request gate which denies connections on http addresses. When this is not practical, for testing reasons, the dev tag can be enabled to exempt localhost from this restriction.

When using an IDE to run go tests, you will have to configure it manually with -tags dev. Under Intellij, this is configured under

Run/Debug Configurations
- Edit configuration templates
  - Go Test
    - Go tool arguments

Tests are failing with `permission denied`

Golang's testing tools rely on executing code from the /tmp folder. On many modern system /tmp is now mounted to tmpfs with noexec. It is a recommendation from CIS. You may have to fix GO's toolchain environment adding:

export GOTMPDIR="/var/tmp"

to your $HOME/.bashrc or $HOME/.bash_profile file. Note that /var/tmp is just another one of those "locations" that is usually the target for temporary files while compiling projects. You could very well just use $HOME/go/tmp, depending on how your partition layout was created, if /var/tmp is also "secured".

Tests are failing with nil panic traces

We use a flavor of Monkey Patching to capture calls to various core methods like os.Exit and fmt.Printf. These require the source to be compiled without function inlining enabled:

-gcflags=-l

The option is set in the Makefile requiring it for the test and report targets, but if you use an IDE Run configuration you will have to configure it manually. Under Intellij, this is configured under

Run/Debug Configurations
- Edit configuration templates
  - Go Test
    - Go tool arguments

Docker

Connection to /var/run/docker.sock failing

Check that docker is running the following under Systemd:

systemctl status docker

Under OpenRC:

rc-service docker status

Check that the permissions on /var/run/docker.sock allows your user to connect to it:

ls -l /var/run/docker.sock
groups

Your user should be in the same group owning the docker.sock file.

If all conditions are met, and you are using a Linx/amd64 distributions, write to sdk 'at' genaiz.com with the following details:

Docker version
OS and version
If you can build with docker build
the output of the command with --log-level=debug

Contributing

To contribute to this project, please follow these steps:

Fork this repository to your personal account.
Create a new branch for your feature or bug fix.
Commit and push changes to your forked repository.
Open a Pull Request (PR) to allow merging into the upstream repository.

License

The GenAIz CLI is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
acceptance-tests		acceptance-tests
genaiz-lib		genaiz-lib
genaiz		genaiz
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.work		go.work
go.work.sum		go.work.sum

Latest commit

History

Folders and files

Repository files navigation