themelio-cli 0.2.0

Command-line client for the Themelio ML platform

themelio CLI

A Hugging Face–style command-line client for the Themelio ML platform. It talks to the Themelio web service HTTP API for metadata and orchestration, and hands repository content transfer off to your own git / git-lfs.

See plans/themelio-cli/SPEC.md, ADR-0021, and DD-0021 for the full design.

Install

Published on PyPI:

pipx install themelio-cli        # isolated, recommended
uvx themelio                     # or run ad-hoc with uv
pip install themelio-cli         # into the current environment

Requires Python ≥ 3.11. (A zero-prerequisite standalone binary via curl … | sh is planned but not yet published — see DD-0021 §Distribution.)

Quick start

themelio auth login                          # paste an api-scoped PAT
themelio git-setup --apply                   # configure the git credential helper

themelio models ls                           # Repository column = usable ns/repo refs
themelio -q models ls                        # just the refs, one per line (scriptable)
themelio models alice/bert info              # inspect a repo (metadata + actions)
themelio models alice/bert download          # prints the git clone command

themelio models alice/bert actions ls        # actions declared in the repo
themelio models alice/bert actions describe train
themelio models alice/bert actions run train --param epochs=3 --follow

themelio models alice/bert jobs ls           # observe compute
themelio models alice/bert jobs logs 123 --follow

Output reads as a platform-native client: GitLab internals (global ids, gitlabUrl, etc.) are stripped in both human and --json output, and repositories are addressed by their namespace/repo reference everywhere.

Command grammar

Repo-scoped commands read themelio <type> <ns/repo> <verb>, e.g. themelio models alice/bert info. Resource types: models, datasets, spaces, repos. Compute-bearing types (models, spaces, repos) additionally carry actions, jobs, and deployments subgroups. ls lists a whole type; to list a repo's contents use ls-files.

Global flags: --json (raw JSON), -q/--quiet (ids only), -y/--yes, --host, --token. Full command reference: the themelio CLI guide.

Configuration

Precedence (highest first): --host/--token flags → THEMELIO_HOST/THEMELIO_TOKEN env → ~/.themelio/config (or OS keyring) → default host https://dev.themelio.pharos.grnet.gr.

Development

pip install -e '.[dev]'
ruff check . && mypy && pytest

Publishing to PyPI (maintainers)

Releases are built with hatchling and uploaded with twine. The version is read from src/themelio/__init__.py (__version__).

# 1. Bump the version in src/themelio/__init__.py, then:
python -m pip install --upgrade build twine

# 2. Build a clean sdist + wheel
rm -rf dist && python -m build

# 3. Validate the artifacts
twine check dist/*

# 4. (Recommended for a first release) rehearse on TestPyPI
twine upload --repository testpypi dist/*
pipx install --index-url https://test.pypi.org/simple/ themelio-cli

# 5. Publish to PyPI
twine upload dist/*

Authenticate twine with a PyPI API token (username __token__, password the pypi-… token) — set TWINE_USERNAME=__token__ and TWINE_PASSWORD=<token>, or use ~/.pypirc. Tag the release in git to match the published version.