The kl command

Use the kl command inside a workspace to show the session environment, manage packages and build container images.

Last updated 24 Oct 2026

On this page

Description and operation
General
Container images
Commands that you do not type
Tasks
Show the session environment
Manage packages from the workspace
Build and push a container image
Troubleshooting

The command kl runs inside a workspace, with the credential of that workspace, for you or your AI agent. Outside a workspace it stops with an error such as KL_WORKSPACE_ID is not set — kl runs inside a kloudlite workspace. On a laptop, use kloudlite.

An agent does the same actions with tools: workspace_get for the session and environment, packages_list, packages_add, packages_remove, packages_update, container_build and container_push. kl reads the workspace token from /etc/kloudlite/ssh/workspace-token. The exec tool runs in a sandbox that hides /etc/kloudlite (see Confinement), so exec cannot run kl. Use the tools, or run kl from a shell of the workspace.

Command	Function
`kl env`	Shows the session of the workspace and its environment, or `none`. It changes nothing.
`kl pkg list`	Shows the packages and their locked versions.
`kl pkg add ENTRY...`	Adds packages. An entry is `name` or `name@version`.
`kl pkg rm NAME...`	Removes packages.
`kl pkg update`	Looks up again every package that has a version.
`kl container build -t NAME [CONTEXT]`	Builds a container image and pushes it to a connected registry.
`kl container push [--registry NAME] SOURCE NAME...`	Copies an image of a registry to more names.
`kl container images [--registry NAME] [--owner NAMESPACE]`	Lists the images that a registry holds under its `namespace`, and their tags. `--owner` lists another namespace. An empty one lists everything that the credential sees.

You cannot change the session of a workspace from inside it. See Sessions. After a package change the new tools install in the background. The forms of an entry and the locks are in Packages.

Container images

A workspace has no container engine, so docker run, docker pull and docker ps do not apply. kl container build builds on your builder and pushes when the build finishes. The builder starts at the first build, and kl waits up to 150 seconds for it. kl container push copies inside the registry and needs at least one new name. After a build, kl prints each pushed name as NAME@sha256:DIGEST. With no registry configured, a build answers no registry is configured.

Name in `-t`	Pushed as
`hello`	`HOST/NAMESPACE/hello`
`hello:1`	`HOST/NAMESPACE/hello:1`
A name that starts with a connected host, as `docker.io/acme/hello:1`	The name unchanged

HOST and NAMESPACE are the host and the namespace of a registry connector. With one registry connected, kl uses it. With several, kl uses the one that is yours alone, or refuses and asks for --registry.

Option	Function
`-t`, `--tag NAME`	The image name. Required. Repeat it for more names.
`--registry NAME`	The name of the registry connector to push to, for example `acme-dockerhub-1`.
`-f`, `--file PATH`	The path of the Dockerfile.
`--build-arg KEY=VALUE`	A build argument. Repeat it for more.
`--platform PLATFORM`	The target platform, for example `linux/amd64`.
`--no-cache`	Skips the cache of the builder.
`CONTEXT`	The context directory. The default is `.`.

Commands that you do not type

Other programs run four more verbs, and kl --help does not list them: kl ide serve (the tool server), kl credential-helper get (registry logins for docker-credential-kl), kl sandbox run (the command of a sandbox) and kl git-credential get.

git runs kl git-credential get for an HTTPS clone of github.com or gitlab.com and gets a short-lived login. It prints nothing for a URL that has a user name, and it never fails the clone. It uses KL_GIT_TOKEN when the variable is set, as in a pipeline job. Otherwise it uses the token of the workspace. It writes kl git-credential: SENTENCE to the error output when the API refuses, and it waits at most 15 seconds.

Tasks

Show the session environment

Reason for the task: Find the session and the environment that the workspace is connected to.

Job set-up

Access: you
Agent tool: workspace_get
Conditions: you have a shell in the workspace. See Connect with SSH. The fields session and environment of workspace_get hold the same values.
References: GET /v1/workspaces/{id}, SDK workspaces.get

Procedure

Run this command in the workspace.
CLI
```
kl env
```

Close-out

Read the output. The first line shows the session, the second the environment.

Manage packages from the workspace

Reason for the task: Show, add, remove and update the packages of the workspace from a shell in it.

Job set-up

Access: you
Agent tool: packages_add
Conditions: you have a shell in the workspace, and it is ready. An agent sends one tool call for each command, with workspace and, for add and remove, packages.
References: PATCH /v1/workspaces/{id}, SDK workspaces.set_packages, Packages

Procedure

Show the packages.
CLI
```
kl pkg list
```
Add a package. Add @version to the name to lock a version.
CLI
```
kl pkg add jq nodejs@22
```
Remove a package.
CLI
```
kl pkg rm jq
```
Run this command to look up the locked versions again.
CLI
```
kl pkg update
```

Close-out

Run kl pkg list. The list shows your changes, and (locked VERSION) for a package with a version.

Build and push a container image

Reason for the task: Build a container image from a Dockerfile and keep it in your registry.

Job set-up

Access: you, or your agent. To push under a team name, a team member.
Agent tool: container_build
Conditions: you have a shell in the workspace, in a directory with a Dockerfile. An agent calls container_build with workspace and tags, then container_push with workspace, src and dst.
References: kloudlite builder status

Procedure

Run this command to build the image. Use your own name and tag.
CLI
```
kl container build -t hello:1 .
```
Add another name to the image.
CLI
```
kl container push hello:1 hello:latest
```

Close-out

Run kl container images. The output shows the image and the tag 1.

Troubleshooting

Symptom	Possible cause	Corrective action
`KL_WORKSPACE_ID is not set — kl runs inside a kloudlite workspace`	You run `kl` outside a workspace.	Open a shell in the workspace.
`no workspace credential at /etc/kloudlite/ssh/workspace-token — kl runs inside a kloudlite workspace`	The platform has not written the credential file yet.	Wait a short time and run the command again.
A sentence from the API after `kl pkg add`, `rm` or `update`	The API refused the package list.	Find the sentence in the Packages troubleshooting.
`jq: not in the package list`	`kl pkg rm` names a package that the list does not hold.	Use a name from `kl pkg list`.
`no packages declared — kl pkg add jq`	`kl pkg list` finds an empty list.	Add a package with `kl pkg add`.
`no registry named NAME; connected: NAMES`	`--registry` names a connector that you cannot use.	Use one of the names in the message.
`the builder did not answer within 150 s`	The builder did not start in time.	Run the command again. If it fails again, run `kloudlite builder status` on your computer and read the `why` line.
`no registry is configured`	You and your team have no connected container registry.	Connect a container registry.
`several registries are connected: NAMES; pass --registry`	More than one registry fits and none is only yours.	Add `--registry` with one of the names.
`a build pushes as it finishes — ...`	`kl container push` has no new name.	Give the source image and at least one new name.