Package: uip-cli
Universal Integration Platform Command Line UtilityOverviewuip-cliis a command line utility by Stonebranch Inc. that is used
to interface with the Universal Extension Web Service APIs. The goal of
the CLI is to make the process of creating, editing, and deploying
Extensions convenient and fast.FeaturesQuickly prototype Extensions using starter (or custom) Extension TemplatesBuild and upload Extensions and/or Universal TemplatesPull the latest Universal Template source files from the ControllerDownload the full Universal Template packageGetting StartedRequirementsuip-cliworks with Python 3.6 and greater on Windows, Linux, and
MacOS, and uses the following third party libraries:jsonschema(3.2.0)colorama(0.4.4)requests(2.26.0)jinja2(2.11.3)prettytable(1.0.1)pyyaml(5.4.1)setuptools(44.1.1)wheel(0.37.1)All the required libraries listed above are automatically installed
during the installation processInstallationTo installuip-cli, download it fromPyPIand install it withpip.
To ensure proper installation/upgrade, the version ofpipinstalled should be 20.0.1 or greater.Thesetuptoolsmodule, which should already be installed withpipis required to installuip-cli. To ensure a smooth installation,  we recommend usingsetuptoolsversion 44.1.1
or greater.To upgradepipandsetuptoolsprior to installinguip-cli, enter the following command:$ python -m pip install --upgrade pip setuptoolsTo install:$ pip install uip-cliTo upgrade:$ pip install uip-cli --upgradeThe CLI is installed asuip. To confirm it is installed properly, type the following:$ uipand you should see something similar to:usage: uip [-h] <command> ...

optional arguments:
-h --help
                show this help message and exit

commands:
  <command>
    init         initialize a new project with starter Extension templates
    template     used to perform actions on built-in (and external) templates
    build        used to build Extension or full package
    upload       upload Extension (or full package) to the Controller
    push         build and upload Extension (or full package) to the Controller
    pull         pulls the latest template.json (and template_icon.png, if
                present)
    download     downloads the full Universal Template package
    clean        used to purge build artifacts
    task         used to perform actions on Universal Extension tasks
    template-list
                list of available Extension templates. Note: this command will
                be deprecated in two releases

examples:
uip <command>
uip init
uip downloadBasic Usageuip-clicurrently supports the following commands:inittemplatelistadddeleteexportbuilduploadpushpulldownloadcleantasklaunchstatusoutputtemplate-list (will be deprecated in two releases. replaced by thetemplate listcommand)A brief overview of each of the commands is provided below along with
some examples. It is highly recommended to go through theExtension Developmentdocument for a more detailed demonstration.initThis command is used to initialize a new project using a custom, user-specified
template or one of the provided starter Extension templates. It can also be used
to initialize an existing,partially validExtension project.To initialize a brand new project using a starter Extension template, issue the
following command:$ uip init -t ue-task -e 'extension_name=my_sample_extension'The-toption accepts the name of the starter Extension template. For a full
list of the available Extension templates, see thetemplate listcommand below.The-eoption is used to configure the starter Extension template with user-defined
variables. See thetemplate listcommand for instructions on obtaining
a full list of configurable variables.Once the CLI executes the command, a project will be initialized in the current
working directory with the following structure:|   setup.cfg
|   setup.py
|   __init__.py
|
|---.uip
|   |---config
|           uip.yml
|
|---src
    |   extension.py
    |   extension.yml
    |   __init__.py
    |
    |---templates
            template.jsonNote that the file system layout above demonstrates a complete, valid Extension project.Users who created an Extension project outside ofuip-cli(e.g., the project structure
was created manually following instructions in the How-To/Getting Started guide) will not
have the.uipfolder. Such a directory structure ispartially valid.To convert an existing, partially valid Extension project into a fully valid one,
issue the following command:$ uip initThe CLI will first check to make sureextension.py,extension.yml, andtemplate.jsonexist in their respective directories shown above. If so, the CLI will create the.uipfolder.
Additionally, ifsetup.pyandsetup.cfgare not present, they will be
created along with the.uipfolder.How to create a custom/configurable Extension template:The CLI is equipped with two built-in, configurable Extension templates:ue-taskandue-publisher. These two templates may not be enough for some
users. To get around this, the CLI supports initializing from external, user-built
Extension templates.This section will outline the basic requirements for creating a custom, configurable
Extension template.Assuming a folder namedmy_templateexists, it must contain (at minimum) the following
files/folders to be considered a valid Extension template:my_template
â”œâ”€â”€ template_config.yml
â””â”€â”€ src/
    â”œâ”€â”€ extension.py
    â”œâ”€â”€ extension.yml
    â””â”€â”€ templates/
        â””â”€â”€ template.jsonAside from the usual Extension related files,template_config.ymlis also needed to make
the template configurable.The file must contain:name: a string that identifies the name of the template (this is NOT referring to the Universal Template name).version: a string that identifies the template version. Not restricted tox.y.z(SemVer); it could be anything (e.g.v1).description: a string describing the template.and can optionally contain:files_to_template: an array containing paths to files that will be “templated” usingJinja2. All files must be specified relative totemplate_config.yml.variables: a mapping/dictionary of variables that will be substituted in the relevant files specified byfiles_to_template. The value of each key/variable is another mapping/dictionary that must containdefaultanddescription.Shown below is a sampletemplate_config.yml:name: my_template

version: 1.0.0

description: this is the description for my_template

files_to_template:
  - src/extension.py
  - src/templates/template.json

variables:
  msg:
    default: test_message
    description: message to print to STDOUT and STDERR
  log_level:
    default: Info
    description: Universal Template Log LevelAs mentioned, the CLI uses theJinja2module to substitute the variables in each file fromfiles_to_template. For instance,
ifsrc/extension.pyorsrc/templates/template.jsonmention{{ msg }}or{{ log_level }}, the entirety of{{ msg }}/{ log_level }}will be replaced with the user-specified value (or the default, if nothing is specified).Once the custom Extension template is created, it can be zipped up or pushed out to a Git repository. The CLI supports initializing from both
of these ways, which makes the custom template easy to distribute. The next section will outline the details regarding this functionality.Packaging custom-built Extension Templates:Once a custom template has been created, it must be packaged into either a
zip file or a Git repository.Shown below is the structure of a valid, custom template zip calledmy_template.zip:my_template.zip
â”œâ”€â”€ template_config.yml
â””â”€â”€ src/
    â”œâ”€â”€ extension.py
    â”œâ”€â”€ extension.yml
    â””â”€â”€ templates/
        â””â”€â”€ template.jsonThe custom template can also be pushed out to a Git repository. In this case, the zip file
won’t be part of the repository. In other words, the top-level file and folder should betemplate_config.ymlandsrc/, respectively.Initializing a custom-built Extension Template:Assuming a custom template has been packaged based on the guidelines from the previous
section, it is ready to be used!The CLI supports initializing custom-built templates from:a zip filea http(s) link to a zip filea Git repositoryInitializing from a zip file:To initialize the template zip without saving it:$ uip init -t <path to zip file>To initialize and save the template zip:$ uip init -t <path to zip file> --saveOnce saved, the template will be available in thetemplate listcommand. At this point, the template can be
initialized similarly toue-taskandue-publisher.Initializing from a http(s) link:The CLI supports initializing from both HTTP and HTTPS links that point to a zip file (link normally ends in .zip).It also supports basic authentication. The syntax ishttp://<username>:<password>@<actualurl>(applies to HTTPS as well). For instance, if the url ishttp://mytestserver/test/my_template.zip, the username istestuser, and password istestpwd, the formatted URL would behttp://testuser:testpwd@mytestserver/test/my_template.zip.To initialize the template without saving it:$ uip init -t <link to http(s) url>To initialize and save the template zip:$ uip init -t <link to http(s) url> --saveInitializing from a Git repository:The CLI also supports initializing directly from a Git repository (similar to how pip installs work from a Git repo). The repo should not contain the zip file, just the raw files/folders that make up the template.The CLI relies on Git being installed on the system. If it is not, the CLI will issue an error.Both SSH and HTTPS protocols are supported.For HTTPS protocol, the url must start withgit+followed by the HTTPS clone url. For instance, if the HTTPS Clone URL ishttps://gitlab-tst.com/test/templates/my_template.git, then the syntax:To initialize the template without saving it:$ uip init -t git+https://gitlab-tst.com/test/templates/my_template.gitTo initialize and save the template zip:$ uip init -t git+https://gitlab-tst.com/test/templates/my_template.git --saveIf the repository is private and requires a username and access token to clone it, the URL should be specified as:git+https://<USERNAME>:<ACCESSTOKEN>@gitlab-tst.com/test/templates/my_template.git.For the SSH protocol, the url must start withgit+followed by the SSH clone url. For instance, if the SSH Clone URL isgit@gitlab-tst.com:test/templates/my_template.git, then the syntax:To initialize the template without saving it:$ uip init -t git+git@gitlab-tst.com:test/templates/my_template.gitTo initialize and save the template zip:$ uip init -t git+git@gitlab-tst.com:test/templates/my_template.git --saveThe CLI also supports cloning a specific branch/commit/tag. This can be done by appending the branch/commit SHA/tag at the end of the URL using@branch,@commit, or@tag. For instance, to clonea branch namedtest1HTTPS URL: git+https://gitlab-tst.com/test/templates/my_template.git@branch:test1
SSH URL: git+git@gitlab-tst.com:test/templates/my_template.git@branch:test1a commit with SHA9ab454ef:HTTPS URL: git+https://gitlab-tst.com/test/templates/my_template.git@commit:9ab454ef
SSH URL: git+git@gitlab-tst.com:test/templates/my_template.git@commit:9ab454efa tag namedv1:HTTPS URL: git+https://gitlab-tst.com/test/templates/my_template.git@tag:v1
SSH URL: git+git@gitlab-tst.com:test/templates/my_template.git@tag:v1templateThis command is used to perform actions on all the available, custom-built and
starter Extension templates. As of now, four actions/subcommands are supported:list,add,delete, andexport.To see the list of available templates, type the following:$ uip template listSomething similar to the output below should be shown:+--------------------+---------+---------------------------------------------------------+
| Extension Template | Version | Description                                             |
+--------------------+---------+---------------------------------------------------------+
| ue-task            | 1.0.0   | starter Extension with minimal code                     |
+--------------------+---------+---------------------------------------------------------+
| ue-publisher       | 1.0.0   | starter Extension with a local Universal Event template |
+--------------------+---------+---------------------------------------------------------+To see the list of configurable variables for one of the templates shown above,
type the following (same process applies toue-publisher):$ uip template list ue-taskand a table of variables will be shown:+---------------------------+------------------+--------------------------------+
| Variable Name             | Default          | Description                    |
+---------------------------+------------------+--------------------------------+
| extension_name            | ue-task          | Extension name                 |
| extension_version         | 1.0.0            | Extension version              |
| extension_api_level       | 1.1.0            | Extension API level            |
| extension_requires_python | >=2.6            | Extension Python requirement   |
| owner_name                | Stonebranch      | Extension owner's name         |
| owner_organization        | Stonebranch Inc. | Extension owner's organization |
| universal_template_name   | UE Task          | Universal Template name        |
+---------------------------+------------------+--------------------------------+To add a custom-built Extension template:$ uip template add <path to zip / link to zip / link to Git repository>Similar to theinitcommand, thetemplate addcommand also supports
adding/saving custom-built templates from:a zip filea http(s) link to a zip filea Git repositoryIn fact, it does so in the same exact manner. See theinitsection for details.Once the template is added, it will be available for use just likeue-taskandue-publisher.To delete a custom-built Extension template:$ uip template delete <template name>To export an Extension template:$ uip template export <template name>buildThis command is used to build an Extension or the full package.
A full package build consists of the Universal Template and the Extension.The command also supports building extensions with third-party Python packages.
To do so, create a file calledrequirements.txtin the Extension folder.
Runninguip buildwill then create a3ppfolder, install all PyPi packages
specified inrequirements.txtto3pp, and package it in the extension zip
(or the full package).To build the Extension only:$ uip buildTo build the full package:$ uip build -aTo build the dependency wheel file only:$ uip build -duploadThis command is used to upload an Extension or the full package to the
Controller.To upload the Extension only:$ uip uploaduip-cliuploads the Extension to the Universal Template specified in thetemplate.jsonfile. If the template.json file is corrupted or name field
is missing, the upload will fail.To upload the full package:$ uip upload -apushThis command is a combination of the build and upload command.To push the Extension only:$ uip pushuip-clipushes the Extension to the Universal Template specified in thetemplate.jsonfile. If the template.json file is corrupted or name field
is missing, the push will fail.To push the full package (the Universal Template and Extension):$ uip push -apullThis command is used to pull the Universal Template source filestemplate.jsonandtemplate_icon.png(if present). These files
are placed in thesrc/templatesfolder.As with thepushcommand,uip-cliobtains the Universal Template name
from thetemplate.jsonfile that exists in the project directory.
If thetemplate.jsonfile is corrupted or the name field is missing, the
pull will fail.To pull the source files:$ uip pulldownloadThis command is used to download the full Universal Template as a zip.uip-cliobtains the Universal Template name from thetemplate.jsonfile that exists in the project directory. If thetemplate.jsonfile
is corrupted or the name field is missing, the download will fail.To download the full Universal Template:$ uip downloadOptionally, it is possible to download another Universal Template by
specifying the Universal Template name:$ uip download -n <universal template name>cleanThis command is used to purge build artifacts.Build artifacts include anything inside the dist, build, and temp folders
(including the folders themselves).To purge the build artifacts:$ uip cleanOptionally, it is also possible to purge the 3pp folder (if it exists) using:$ uip clean --alltaskThis command is used to perform actions on Universal Extension tasks.
As of now, three actions/subcommands are supported:launch,status,
andoutputwhich allow the CLI to launch, get status, and get output of
Universal Extension tasks.All three subcommands must be used in a complete, valid Extension project
to work.To launch an Universal Extension task:$ uip task launch <task name>By default, the CLI will launch the task and continuously print the status
of the task until it succeeds/fails. Upon success/failure, the task output
will be printed as well. If the--no-waitoption is specified, the CLI
will exit immediately after launching the task (task status and output will
NOT be printed).To get the status of Universal Extension task instances:$ uip task status <task name>By default, the CLI will print the status and exit code of the most recent
task instance of the specified task. The--num-instancesoption can be
used to specify the number of task instances to get the status of. If a
nonpositive integer is specified, the status of all the instances will be
printed.To get the output of an Universal Extension task instance:$ uip task output <task name>By default, the CLI will print the output of the most recent task instance
of the specified task. The--instance-numberoption can be used to
specify the number of the task instance to get the output of.ConfigurationThere are three primary ways to configure the CLI and its commands (listed in order of precedence):Command Line ArgumentsEnvironment VariablesConfiguration FilesCommand Line ArgumentsSimilar to most CLI applications,uipsupports both short and long command line arguments.
The short arguments start with a single dash and long arguments start with two dashes as shown below:$ uip build -a
$ uip build --allEnvironment VariablesMost of the options that can be configured through the command line can also be configured using
environment variables. All environment variables are prefixed withUIP_.Configuration FilesThe CLI can be configured through two types of configuration files: global and local.The local configuration file has precedence over the global one.The global configuration file is installed when uip-cli is used for the first timeOn Windows, the file is located inC:\Users\<USER>\AppData\Local\UIP\configwhereUSERis the one who installed the CLI.On Linux/MacOS, the file is located in~/.config/uip/configwhere~is the user’s
home directory.The local configuration file is installed with the init commandAs you may have seen in the directory structure above, the.uipfolder contains aconfigfolder which houses the local configuration file. Whenever a new project or
an existing project is initialized usinginit, the CLI will automatically create the.uipfolder along with the configuration file. This allows separate projects to have
their own set of configurations.Configuration file formatBoth the global and local configuration files are calleduip.yml. The files must be
formatted using proper YAML format. See the example below:userid: admin
url: http://localhost:8080/uc
build-all: yesFull List of Configuration OptionsLogin OptionsLogin ArgumentsOption NameShort ArgLong ArgEnvironment VariableConfiguration File ArgDefaultUser ID-u--useridUIP_USERIDuseridNonePassword-w--passwordUIP_PASSWORDNoneNoneURL-i--urlUIP_URLurlNoneinitcommand optionsOptional ArgumentsOption NameShort ArgLong ArgEnvironment VariableConfiguration File ArgRequiredDefaultExtension Template-t--extension-templateNoneNoneNONoneVariables-e--variablesUIP_TEMPLATE_VARIABLESvariablesNONoneSave-s--saveNoneNoneNOFalseUpgrade-u--upgradeNoneNoneNOFalseValues for thevariablesoption can be specified in three different ways:Using the-eoption multiple times:$ uip init -t ue-task -e 'var1=value1' -e 'var2=value2' -e 'var3=value3'Using a JSON string:$ uip init -t ue-task -e '{"var1": "value1", "var2": "value2", "var3": "value3"}'Using a JSON/YAML file:$ uip init -t ue-task -e '@vars.yml'wherevars.ymlcontainsvar1: value1
var2: value2
var3: value3Note that the filename/filepath must be prefixed with ‘@’Positional ArgumentsOption NameRequiredDefaultDescription<dir>NOCurrent Working DirectoryWhere to initialize the Extension template. For example, in the following command:uip init-tue-task-e'@vars.yml' my_extension_dir,my_extension_diris
where theue-taskExtension template will be initialized.template listcommand optionsPositional ArgumentsOption NameRequiredDefaultDescription<extension template name>NONoneThe name of the Extension template to get more details of. For example, in the
following command:uip template listue-task,ue-taskis the value of<extension template name>.Optional ArgumentsOption NameShort ArgLong ArgEnvironment VariableConfiguration File ArgRequiredDefaultJSON-j--jsonNoneNoneNOFalsetemplate addcommand optionsPositional ArgumentsOption NameRequiredDefaultDescription<extension template>YESNoneThe name of the Extension template to add. Valid values include path to a zip
file, HTTP(S) url pointing to a zip file, or a Git repository clone url.template deletecommand optionsPositional ArgumentsOption NameRequiredDefaultDescription<extension template>YESNoneThe name of the Extension template to deletetemplate exportcommand optionsPositional ArgumentsOption NameRequiredDefaultDescription<extension template>YESNoneThe name of the Extension template to exportbuildcommand optionsOptional ArgumentsOption NameShort ArgLong ArgEnvironment VariableConfiguration File ArgRequiredDefaultBuild All-a--allUIP_BUILD_ALLbuild-allNOFalseBuild Dependency Wheel Only-d--dep-whl-onlyUIP_BUILD_DEPENDENCY_WHEEL_ONLYdep-whl-onlyNOFalseuploadcommand optionsOptional ArgumentsOption NameShort ArgLong ArgEnvironment VariableConfiguration File ArgRequiredDefaultUpload All-a--allUIP_UPLOAD_ALLupload-allNOFalsepushcommand optionsOptional ArgumentsOption NameShort ArgLong ArgEnvironment VariableConfiguration File ArgRequiredDefaultPush All-a--allUIP_PUSH_ALLpush-allNOFalsedownloadcommand optionsOptional ArgumentsOption NameShort ArgLong ArgEnvironment VariableConfiguration File ArgRequiredDefaultTemplate Name-n--template-nameUIP_TEMPLATE_NAMEtemplate-nameNOName fromtemplate.jsoncleancommand optionsOptional ArgumentsOption NameShort ArgLong ArgEnvironment VariableConfiguration File ArgRequiredDefaultClean All-a--allUIP_CLEAN_ALLclean-allNOFalsetask launchcommand optionsPositional ArgumentsOption NameRequiredDefaultDescription<task name>YESNoneName of the Universal Extension task to launchOptional ArgumentsOption NameShort ArgLong ArgEnvironment VariableConfiguration File ArgRequiredDefaultNo Wait-N--no-waitUIP_NO_WAITno-waitNOFalsetask statuscommand optionsPositional ArgumentsOption NameRequiredDefaultDescription<task name>YESNoneName of the Universal Extension task to get status ofOptional ArgumentsOption NameShort ArgLong ArgEnvironment VariableConfiguration File ArgRequiredDefaultNum Instances-n--num-instancesUIP_NUM_INSTANCESnum-instancesNO1task outputcommand optionsPositional ArgumentsOption NameRequiredDefaultDescription<task name>YESNoneName of the Universal Extension task to get the output ofOptional ArgumentsOption NameShort ArgLong ArgEnvironment VariableConfiguration File ArgRequiredDefaultInstance Number-s--instance-numberUIP_INSTANCE_NUMBERinstance-numberNOmost recent task instanceLicenseuip-cliis released under theGNU General Public LicenseAcknowledgementsuip-cliacknowledges the use of the following open source Python modules:colorama(BSD License)Jinja2(BSD-3-Clause License)prettytable(BSD-3-Clause License)jsonschema(MIT)PyYAML(MIT)requests(Apache 2.0)setuptools(MIT)CopyrightCopyright (c) 2023. Stonebranch, Inc. All rights reserved.