Installing the Kodexa CLI

Kodexa command line tools provide an easy way to work with a Kodexa platform instance from the command line. The tools are built on top of the Python SDK and provide a simple way to interact with the platform.

Installation

The Kodexa command line tools are available on PyPi and can be installed with pip:

$ pip install kodexa-cli

Usage

The Kodexa command line tools are available as a single command called kodexa. You can see the available commands by running kodexa --help:

$ kodexa --help
Usage: kodexa [OPTIONS] COMMAND [ARGS]...

Options:
  -v, --verbose  Enable verbose output.
  --help         Show this message and exit.

Commands:
  delete          Delete the given resource (based on ref)
  deploy          Deploy a component to a Kodexa platform instance from a...
  document
  export-project
  get             List the instance of the object type
  import-project
  login           Logs into the specified platform environment using the...
  logs            Get logs for an execution
  package         Package an extension pack based on the kodexa.yml file
  platform        Get the details for the Kodexa instance we are logged into
  project         Get all the details for a specific project
  query           Query the documents in a given document store
  send-event      Send an event to an assistant
  upload          Upload the contents of a file or directory to a Kodexa...
  version

Logging into Kodexa

The first thing you need to do is log into a Kodexa platform instance. You can do this by running the login command:

$ kodexa login

You will need to provide the URL of the Kodexa platform instance you want to log into. You can also provide the email and password for the Kodexa platform instance. Once you have successfully logged in you can see the details of the Kodexa platform instance you are logged into by running the platform command:

$ kodexa platform

Your personal API token will be stored in your home directory, based on your operating system it will be:

macOS ~/Library/Application Support/kodexa-cli
Linux ~/.local/share/kodexa-cli
Windows C:\\Documents and Settings\{User}\\Application Data\\Local Settings\\kodexa\\kodexa-cli or C:\\Documents and Settings\{User}\\Application Data\\kodexa\\kodexa-cli

This file is used to authenticate you to the Kodexa platform instance. You can also provide the API token as an environment variable called KODEXA_ACCESS_TOKEN.

Additional Notes on Kodexa CLI installation

When you install a package using pip, it will by default install the package into the site-packages directory of the currently active Python environment. If you haven't activated a virtual environment, it will install to the global Python environment's site-packages directory. To ensure that the package is installed in the default path of the global Python environment, you should:

Make sure you are not in a virtual environment. You can deactivate a virtual environment with the command deactivate if you are using venv, or by simply closing and reopening your terminal.
Check which Python and pip you are using with the following commands:

which python3
which pip3

These commands will show you the path of the Python and pip executables that will be used. If the output points to a directory inside a virtual environment (usually a path ending with env/bin/python), you are still inside a virtual environment and you need to exit it before proceeding. If the output points to a system path (like /usr/bin/python or /usr/local/bin/pip), then you are using the system-wide Python and pip and can proceed.

Once you have confirmed that you are using system-wide Python and pip, you can install the package with:

pip3 install kodexa-cli

After the installation completes, you can verify its location by checking the package information with:

pip3 show kodexa-cli

(myenv) ➜  ~ pip3 show kodexa-cli
Name: kodexa-cli
Version: 7.0.7426713829
Summary: Command Line Tools for Kodexa
Home-page:
Author: Austin Redenbaugh
Author-email: austin@kodexa.com
License:
Location: /Users/bluestaffordshire/myenv/lib/python3.9/site-packages
Requires: click, jinja2, kodexa, PyYAML, rich, wrapt
Required-by:

This command will display information about the installation, including the location of the installed package.

Remember, installing packages system-wide may require administrative privileges. If you encounter permission issues, you might need to prepend sudo to the pip install command (though this practice is generally discouraged due to security concerns). A safer alternative is to use a virtual environment or a user installation with the --user flag:

pip install --user kodexa-cli

A user installation will place the package in a site-packages directory under your user directory, which doesn't require administrative privileges and is safer than installing packages globally.

It's often safer and more manageable to use a virtual environment for each project, which isolates dependencies and doesn't require administrative permissions. You can create a virtual environment using venv:

python3 -m venv myenv
source myenv/bin/activate

Once you get in myenv, you can run the following command

pip3 install kodexa-cli

Upgrade pip when you receive this warning

WARNING: You are using pip version 21.2.4; however, version 24.0 is available.
You should consider upgrading via the '/Users/bluestaffordshire/myenv/bin/python3 -m pip install --upgrade pip' command.

By running this command specific to the path where you made the installation of pip

/Users/bluestaffordshire/myenv/bin/python3 -m pip install --upgrade pip

Before you are able to access kodexa development environments from your CLI, you will have to set up cloudflared. See . You will be asked to enter the URL, your username, and a profile token that you can obtain from the Profile Menu of the environment.

https://dev2.kodexacloud.com
yourtoken

Once you have Python installed, you can upgrade the version of the current CLI, you can run

pip install kodexa~=6.0.0b --upgrade

You can confirm it is installed by then running:

kodexa version

When you have already set your profile, you may login to Kodexa using the following steps:

kodexa profile dev2
cloudflared access login https://dev2.kodexacloud.com
export CF_TOKEN=$(cloudflared access token -app=https://dev2.kodexacloud.com)

← Previous

Getting Started

Project Templates

On this page

Installing the Kodexa CLI
Installation
Usage
Logging into Kodexa
Additional Notes on Kodexa CLI installation