Python Setup

The kleinkram CLI allows you to interact with Kleinkram directly from the command line. This guide will help you get started with the CLI. While it covers core workflows, some advanced administrative features still require the web interface.

Installation and Prerequisites

The CLI requires Python 3.10 or later; we test it on 3.10 and 3.13. We recommend Python 3.12 or later.

It is best practice to always install Python packages inside a virtual environment:

# Create a virtual environment using your default python version
python -m venv .venv

# Activate the virtual environment
source .venv/bin/activate

Once activated, you can install the CLI using pip:

pip install kleinkram

This will add the command klein to your PATH. You are ready to get started!

klein --help

Authentication

To use the CLI or the Python SDK, you must first authenticate your local setup. This is done exclusively using the CLI:

klein login

Alternative Authentication Methods

If the default login process does not work for your environment, consider one of the following options:

Headless Authentication

In case your device development server does not support a browser, or if the default port 8000 is already in use, you can run the login flow in headless mode:

klein login --headless

Authentication inside Actions

Inside a Kleinkram action you don't need to run klein login. The action container sets KLEINKRAM_API_KEY (together with KLEINKRAM_API_ENDPOINT and KLEINKRAM_S3_ENDPOINT), and the CLI picks these up automatically, so commands like klein upload or klein download work out of the box.

These variables are only used when there is no saved ~/.kleinkram.json. If your action image ships one, remove it before running CLI commands, otherwise the CLI uses the saved endpoint and credentials instead.

Customizing the OAuth Provider

By default, the CLI opens Google as the OAuth provider. If you want to use another provider (e.g. GitHub), specify it via the flag:

klein login --oauth-provider github

Supported providers are google and github.

Development Providers

For local development purposes, a fake-oauth provider is also available. See the Developer Guide for more details.

Logging Out

klein logout removes the saved credentials for the selected endpoint. klein logout --all removes them for every endpoint.

Endpoints and Self-Hosted Instances

By default the CLI talks to the public Kleinkram instance at datasets.leggedrobotics.com. To use another instance, for example one you host yourself, register it as an endpoint. An endpoint is a name plus the URL of the API server and the URL of the S3 storage:

# list the known endpoints; the selected one is marked
klein endpoint

# add an endpoint and select it
klein endpoint my-instance https://api.kleinkram.example.com https://s3.kleinkram.example.com

# switch to an endpoint that is already known
klein endpoint my-instance

# log in to the selected endpoint
klein login

Three endpoints are built in:

Name	API	S3
prod	https://api.datasets.leggedrobotics.com	https://s3.datasets.leggedrobotics.com
dev	https://api.datasets.dev.leggedrobotics.com	https://s3.datasets.dev.leggedrobotics.com
local	http://localhost:3000	http://localhost:9000

A release of kleinkram from PyPI selects prod by default, a -dev pre-release selects dev, and an editable install from a clone of the repository selects local.

Credentials are stored per endpoint, so you stay logged in to each endpoint you have used. The endpoints, the selected endpoint and the credentials are saved in ~/.kleinkram.json.

Next Steps

• Read the CLI Documentation to discover core workflows.
• For using the python package in automated scripts, see the Python SDK Reference.