Skip to content

Create a Package

This page describes how to create a package using the kdb Insights Enterprise CLI.

Using the web interface or the CLI

kdb Insights Enterprise provides both a web interface and command line interface (CLI). To create packages using the web interface, refer to the web interface documentation.

Create a new package

To create a package in kdb Insights Enterprise, use the kxi package init command.

Run the --help command to see information on additional options. Expand for details 

kxi package init --help

 Usage: kxi package init [OPTIONS] [PATH_TO_PACKAGE]                            

 Creates a bare package at the specified target path.                           
 Note: this will not be saved to your KX_PACKAGE_PATH unless `install` is       
 explicitly run.                                                                

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --force                                         Overwrite without prompting  │
│                                                 for confirmation.            │
│ --reset                                         Overwrite the manifest only. │
│                                                 (Default behavior)           │
│                                                 [deprecated]                 │
│ --clean                                         Overwrite the existing       │
│                                                 directory entirely.          │
│ --version                         TEXT          Version of the package to    │
│                                                 initialise.                  │
│ --output-format               -o  [json|table]  Output format for the        │
│                                                 command. default: 'table'.   │
│ --hostname,--url                  TEXT          Insights URL                 │
│                                                 [env: INSIGHTS_URL]          │
│ --realm                           TEXT          Realm                        │
│                                                 [env: INSIGHTS_REALM]        │
│ --client-id                       TEXT          Client id                    │
│                                                 [env: INSIGHTS_CLIENT_ID]    │
│ --client-secret                   TEXT          Client secret                │
│                                                 [env:                        │
│                                                 INSIGHTS_CLIENT_SECRET]      │
│ --auth-enabled/--auth-disabl                    Retrieve Bearer Token        │
│ ed                                              [env: KXI_AUTH_ENABLED]      │
│ --server-timeout                  INTEGER       Timeout for Insights server  │
│                                                 calls  [env:                 │
│                                                 INSIGHTS_SERVER_TIMEOUT]     │
│ --yes,--assume-yes            -y                Automatic yes to prompts;    │
│                                                 assume "yes" as answer to    │
│                                                 all prompts and run          │
│                                                 non-interactively.           │
│ --help                                          Show this message and exit.  │
╰──────────────────────────────────────────────────────────────────────────────╯

Example workflow

Run the following command to create a new package:

kxi package init packagename

This command triggers the following:

  • If the directory does not exist, a new directory is created and the following files are generated:

    • manifest.yaml
    • .kxignore

  • If the directory already exists, you see a warning displayed.

  • If the directory is already recognized as a package, you are prompted to confirm before overwriting it.

  • If the directory exists but is not yet a package, initialization proceeds after the warning.

Note

Initialization does not create init.q, any other source file, or a default entrypoint. Add your source files and define entrypoints explicitly after initialization.

Alternatively, use force initialization. If you want to overwrite an existing package directory without being prompted for confirmation, use --force:

kxi package init packagename --force

--force suppresses confirmation prompts. If the target directory already contains a package, existing package initialization files may be overwritten.

Once the package has been initialized you can check what's inside by looking at the manifest.yaml file.

# yaml-language-server: $schema=https://code.kx.com/insights/enterprise/packaging/schemas/package.json#/$defs/Manifest
metadata: {}
name: packagename
version: 0.0.1
dependencies: []
tables: {}
databases: {}
pipelines: {}
views: {}
patches: []

Note

A package UUID identifies the package within kdb Insights Enterprise. It is not written as a top-level field in a newly initialized manifest.yaml.

Convert folder to package

If you have already developed source code locally, you can initialize that folder as a package.

To convert an existing source code folder into a package, run:

kxi package init foldername --force

This command updates the folder adding a bare bones manifest.yaml file to the root.

Example yaml:

# yaml-language-server: $schema=https://code.kx.com/insights/enterprise/packaging/schemas/package.json#/$defs/Manifest
metadata: {}
name: foldername
version: 0.0.1
dependencies: []
tables: {}
databases: {}
pipelines: {}
views: {}
patches: []

Your existing source files are left untouched. To have a component load one of them on startup, add an entrypoint explicitly.

Important

The folder being converted should contain only source code. Components such as databases, pipelines, or other deployment objects must be added explicitly using kxi package add. They are not automatically detected during package initialization.

Considerations

  • A package created using kxi package init exists locally only. To use it within kdb Insights Enterprise, you must push the package to a kdb Insights Enterprise deployment.

  • User-defined custom fields are not supported in manifest.yaml.

Next steps

Back to top