Metadata-Version: 2.4
Name: themelio-cli
Version: 0.2.0
Summary: Command-line client for the Themelio ML platform
Project-URL: Homepage, https://dev.themelio.pharos.grnet.gr
Project-URL: Documentation, https://dev.themelio.pharos.grnet.gr
Project-URL: Source, https://gitlab.grnet.gr/themelio/themelio
Project-URL: Issues, https://gitlab.grnet.gr/themelio/themelio/-/issues
Author: Themelio
License: Apache-2.0
Keywords: cli,daedalus,gitlab,huggingface,ml,themelio
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=24.0
Requires-Dist: platformdirs>=4.0
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: tomli-w>=1.0
Requires-Dist: typer[all]>=0.12
Provides-Extra: build
Requires-Dist: pyinstaller>=6.0; extra == 'build'
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Description-Content-Type: text/markdown

# themelio CLI

A Hugging Face–style command-line client for the [Themelio](https://dev.themelio.pharos.grnet.gr)
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`](../../plans/themelio-cli/SPEC.md),
[ADR-0021](../../docs/docs/adr/0021-themelio-cli.md), and
[DD-0021](../../docs/docs/dd/0021-themelio-cli.md) for the full design.

## Install

Published on [PyPI](https://pypi.org/project/themelio-cli/):

```bash
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

```bash
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](../../docs/docs/product/guides/themelio-cli.md).

## 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

```bash
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__`).

```bash
# 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.
