Skip to content

Command Line Interface

The Command Line Interface (CLI) for interacting with Packages is fully integrated with the kxi CLI as outlined here. The package command within the kxi CLI allows a user to create, package and manage packages locally and within a KX Insights installation. Installation of the kxi CLI can be achieved following the instructions outlined here.

The following is the list of available commands:

$ kxi package --help
Usage: kxi package [OPTIONS] COMMAND [ARGS]...

  KX Package Import/Export CLI

Options:
  --version                   Version Info
  --artifact-store DIRECTORY  Directory in which to store package
                              artifact;[default] $KX_ARTIFACT_PATH
  --pkg-lib DIRECTORY         Directory in which packages will be
                              installed;[default] $KX_PACKAGE_PATH
  --debug                     Enable stacktrace prints for easier debugging
  --help                      Show this message and exit

Commands:

  When pulling/pushing to a remote deployment, use these commands:

    pull           Download an artifact from a running service to your local dir
    push           Publish a package artifact to a running service
    remote-list    List all installed packages or artifacts on the remote system
    remote-remove  Remove packages/artifacts from remote service specified as
                   'name/ver' and...

  For local development, use these commands:

    init       Creates a bare package at the specified target path
    install    Install a package given a requirement or path
    list       List all installed packages or artifacts
    packit     Create a package artifact given source code directory
    uninstall  Locally remove packages/artifacts packages can be specified as
               'name/ver'...

Interactions with packages are local or remote with the storage of packages and their associated artifacts with a user defined path at KX_PACKAGE_PATH and KX_ARTIFACT_PATH respectively both locally and on an Insights Installation.

Quickstart

This quickstart provides a step-by-step guide to:

  1. Initialise a package locally.
  2. Update this package to include user defined code.
  3. Package this entity to generate an artifact.
  4. Install this package locally allowing it to be loaded and used locally.

The quickstart assumes that a user has:

  1. Installed the kxicli package (version >= 1.0.0) following the instructions here

Generate a simple package locally

  • Create and define the artifact and package paths.

    $ mkdir -p /tmp/packages
    $ mkdir -p /tmp/artifacts
    $ export KX_PACKAGE_PATH=/tmp/packages
    $ export KX_ARTIFACT_PATH=/tmp/artifacts
    
  • Initialize a package with minimal content.

    $ kxi package init qpackage
    Creating package at location: qpackage
    Creating: manifest.json
    {
        "name": "qpackage",
        "version": "0.0.1",
        "entrypoints": {
            "default": "init.q"
        },
        "metadata": {
            "description": "",
            "authors": {
                "username": {
                    "email": null
                }
            }
        },
        "dependencies": {}
    }
    Creating: init.q
    
    qpackage
    ├── init.q
    └── manifest.json
    
  • Create a file src/sp.q which contains a User Defined Function (UDF) and variable, documentation outlining the structure for this UDF is provided here.

    $ cat src/sp.q
    .test.variable:1b
    
    // @udf.name("sp_map")
    // @udf.tag("sp")
    // @udf.category("map")
    .test.sp.map:{[table;params]
       select from table where x<10
       }
    
  • Update the init.q file to load the src/sp.q file.

    $ cat init.q
    // Load the src/sp.q file relative to package root
    .kxi.packages.file.load["src/sp.q"]
    
  • Package the artifact defining the version of the package on command line.

    Note

    If the package has multiple dependencies you may want to specify --all-deps to create an archive with all of the sub-dependencies included.

    $ cd ..
    $ kxi package packit qpackage --version 1.0.0 --tag
    Creating package from /Users/username/qpackage
    Package created: /tmp/artifacts/qpackage-1.0.0.kxi
    {
        "qpackage-1.0.0.kxi": "CREATED"
    }
    
  • Install the package locally such that it can be loaded into processes using Python/q locally.

    $ kxi package install qpackage-1.0.0.kxi
    Installing /tmp/artifacts/qpackage-1.0.0.kxi
      Getting qcode=1.0.0 from [local] /tmp/artifacts/qpackage-1.0.0.kxi
        Unpacking qcode: /tmp/packages/qpackage/1.0.0
    Successfully installed qpackage
    {
        "qpackage": [
            {
                "version": "1.0.0",
                "_status": "InstallationStatus.SUCCESS"
            }
        ]
    }
    
  • List the current artifacts available locally.

    $ kxi package list --artifacts
    Listing artifacts at: /tmp/artifacts
    {
        "qpackage": [
            "1.0.0"
        ]
    }