Skip to main content
Version: Next

Use an OCI-based registry

KCL package management tool supports saving and sharing KCL packages through OCI Registries.

Default OCI Registry​

KCL package management tool uses ghcr.io to save KCL packages by default.

Default registry - https://github.com/orgs/kcl-lang/packages

Use Custom OCI Registry​

There are several hosted container registries with OCI support that you can use to store your KCL module.

You can adjust the registry and repository name of the OCI registry by the follow methods.

By environment variable​

You can adjust the configuration of OCI Registry by setting the three environment variables KPM_REG, KPM_REGO.

# set default registry
export KPM_REG="ghcr.io"
# set default repository
export KPM_REPO="kcl-lang"

By configuration file​

The configuration file of the KCL package management tool is located at $KCL_PKG_PATH/.kpm/config/kpm.json, if the environment variable KCL_PKG_PATH is not set, it is saved by default in $HOME/.kcl/kpm/.kpm/config/kpm.json.

The default content of the configuration file is as follows:

{
  "DefaultOciRegistry": "ghcr.io",
  "DefaultOciRepo": "kcl-lang"
}

Quick start​

In the following content, we will use localhost:5001 as an example OCI Registry, and add an account test with a password 1234 to this OCI Registry, and upload a package named MyPkg with v0.1.0.

kcl registry login to login OCI Registry​

You can use kcl registry login in four ways.

1. Login OCI Registry with account and password​

kcl registry login -u <account_name> -p <password> <oci_registry>

For the example, the command is as follows:

kcl registry login -u test -p 1234 localhost:5001

2. Login OCI Registry with account and interactive input password​

kcl registry login -u <account_name> <oci_registry>
Password:
Login succeeded

For the example, the command is as follows:

kcl registry login -u test localhost:5001
Password: 1234
Login succeeded

3. Login OCI Registry with interactive input account and password​

kcl registry login <oci_registry>
Username: <account_name>
Password:
Login succeeded

For the example, the command is as follows:

kcl registry login localhost:5001
Username: test
Password: 1234
Login succeeded

kcl registry logout to logout OCI Registry​

You can use kcl registry logout to logout an OCI Registry.

kcl registry logout <registry>

For the example, the command is as follows:

kcl registry logout localhost:5001

kcl mod push to upload a KCL package​

You can use kcl mod push to upload a KCL package to an OCI Registry.

# Create a new kcl package.
kcl mod init <package_name>
# Enter the root directory of the kcl package
cd <package_name>
# Upload the kcl package to an oci registry
kcl mod push

For the example, the commands are as follows:

kcl mod init MyPkg
cd MyPkg
kcl mod push

You can also specify the url of the OCI registry in the kcl mod push command.

# Create a new kcl package.
kcl mod init <package_name>
# Enter the root directory of the kcl package
$ cd <package_name>
# Upload the kcl package to an oci registry
kcl mod push <oci_url>

For the example, you can push the kcl package to localhost:5001 by the command

kcl mod init MyPkg
cd MyPkg
kcl mod push oci://localhost:5001/test/MyPkg --tag v0.1.0

kcl mod pull to download a KCL package​

You can use kcl mod pull to download a KCL package from the default OCI registry. KPM will automatically search for the kcl package from the OCI registry in kpm.json.

kcl mod pull <package_name>:<package_version>

For the example, the command is as follows:

kcl mod pull MyPkg:v0.1.0

Or, you can download a kcl package from the specified OCI registry url.

kcl mod pull <oci_url>

For the example, the command is as follows:

kcl mod pull oci://localhost:5001/test/MyPkg --tag v0.1.0

kcl mod add to add a KCL package from OCI registry as a dependency​

You can use kcl mod add to add a KCL package from the default OCI registry. KPM will automatically search for the kcl package from the OCI registry in kpm.json.

kcl mod add <package_name>:<package_version>

For the example, the command is as follows:

kcl mod add MyPkg:v0.1.0

Or, you can download a kcl package from the specified OCI registry url.

kcl mod add <oci_url>

For the example, the command is as follows:

kcl mod add oci://localhost:5001/test/MyPkg --tag v0.1.0

kcl run to compile a KCL package​

KCL package management tool can directly compile a kcl package through the url of OCI.

kcl run <oci_url>

For the example, the command is as follows:

kcl run oci://localhost:5001/test/MyPkg --tag v0.1.0