# SDK and CLI

> The systemone Python package: browser login, search, pull with a shared cache, create and push.

Source: https://dev.systemonemodels.tech/docs/sdk

The `systemonemodels` package installs the `systemone` command and a small
Python library over the same HTTP API the website uses. It needs Python 3.10 or
newer.
It is open source — [systemonemodels/systemonemodels-sdk](https://github.com/systemonemodels/systemonemodels-sdk) on
GitHub, Apache-2.0 — so you can read exactly what it does with your token.

```bash
pip install systemonemodels
```

## Sign in

```bash
systemone login
```

The CLI shows an eight-letter code and opens [systemonemodels.tech/device](https://dev.systemonemodels.tech/device)
in your browser. Check the code matches, choose **Authorize**, and the terminal
finishes on its own. The token it receives is listed under
[Settings → Access tokens](https://dev.systemonemodels.tech/settings/tokens) as "CLI · your-machine", where you
can revoke it.

Over SSH, or anywhere a browser cannot open, the CLI prints the address instead —
open it on your laptop or phone and type the code. `--no-browser` does the same
on purpose.

For CI and scripts, skip the browser and use a token created in settings:

```bash
systemone login --token "$SYSTEMONE_TOKEN"   # store it
export SYSTEMONE_TOKEN=s1_pat_...            # or just set it; nothing is stored
systemone whoami
```

The stored token lives in your config directory with `0600` permissions.
`systemone logout` forgets it.

## Discover

```bash
systemone search snake
systemone search --capability route --architecture laya --sort downloads
systemone show biplov/snake-balanced-multilingual
```

`--sort` takes `relevance`, `recent`, `stars`, `downloads`, `accuracy` or
`latency`.

## Pull

```bash
systemone pull biplov/snake-balanced-multilingual --variant onnx-int8
systemone pull biplov/snake-balanced-multilingual --version 0.1.0 --dest ./snake
```

Files are cached by content, so a second pull downloads nothing and two variants
that share a tokenizer store it once. `--dest` links the tree into a folder of
your choosing instead of printing the cache path. `systemone cache info` shows
where the cache is and how big it has grown; `systemone cache clear` empties it.

## Publish

```bash
cd ~/my-workspace
systemone push
```

Run `push` in a folder and it finds every model underneath — trained
checkpoints and their ONNX and Core ML exports, GGUF files, any folder holding
`model.onnx`, `model.safetensors`, a `.gguf` or an `.mlpackage` — lists them,
and asks which to publish (`1,3-5` or `all`). Variants of one model are
published together, as one version with a folder each. To publish one folder
under a name of your choosing:

```bash
systemone push ./runs/snake/model --repo you/laya-snake
```

Nothing has to be retyped:

- The folder's `README.md` becomes the model card, and its Hugging Face front
  matter sets the licence, tags and base model. A model without one gets a card
  written from its evaluation, questions and variants.
- The `systemone.yaml` manifest is inferred: capabilities from the question
  schema; accuracy, calibration error and latency from a Laya Studio run's
  `eval.json` or an export's own measurements. `--manifest` uses yours instead.
- The version is the next minor after the latest (`0.1.0`, `0.2.0`, …), or
  `--version`.

`push` shows its plan and asks before sending anything, and `--dry-run` prints
the manifests, cards and files, then stops. Files already in the registry are
not uploaded again, so republishing with one changed file sends one file. Other
options: `--namespace` publishes under an organization, and `--license`,
`--readme`, `--variant`, `--notes` and `--private` do what they say.
`--all --yes` publishes everything found without a question, for scripts.

`systemone create you/name` makes an empty repository, and
`systemone validate systemone.yaml` runs the registry's own manifest check, so
a manifest that passes locally will not be rejected on push. Publishing needs a
verified email address. Folder discovery needs `systemonemodels` 0.2.0 or
later.

## In Python

```python
from systemone import snapshot_download

path = snapshot_download("biplov/snake-balanced-multilingual", variant="onnx-int8")
# path is a local directory with the version's files, served from the cache
# on every call after the first.
```

Running a model is up to the runtime it was exported for — ONNX Runtime, Core ML
and so on. The repository's model card says which, and `show` prints its runtime.