Metadata-Version: 2.4
Name: os3-cli
Version: 0.1.4
Summary: os3: the OS3 platform's command line, a thin client over its API (A16.2).
License: Proprietary
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx<1,>=0.27
Requires-Dist: os3-upload-client>=0.3.1

# os3-cli

`os3`, the OS3 platform's command line (A16.2): a thin client over the control-plane API. Each
command makes the API calls `COMMANDS` in `os3_cli/__init__.py` lists for it and nothing else;
its flags are the request's fields, the API checks them, and it prints the API's JSON response
(`--field a.0.b` prints one value). `os3 <command> --help` names the calls, and
`os3 api METHOD PATH [--json BODY|@file] [--idempotency-key KEY]` makes any call of the API
reference at `$OS3_API_URL/docs` (the key: the API's Idempotency-Key header, so a rerun with it
is the first call's result).

```bash
pip install https://api.os3robotics.com/downloads/os3_upload_client-0.3.1-py3-none-any.whl \
  https://api.os3robotics.com/downloads/os3_cli-0.1.4-py3-none-any.whl  # httpx and the upload client only
export OS3_API_KEY=<an API key>
os3 --help
```

It calls the hosted API, `https://api.os3robotics.com`; set `OS3_API_URL` to call another. The
API serves this package's and the upload client's wheels at `/downloads/`, built from its own
commit (`infra/controlplane/Dockerfile`), and lists the current ones at `/downloads`; they are
not on PyPI. From a checkout:
`pip install ./upload_client ./cli`.

A run's life from the command line: `os3 jobs list [--workspace <id>]` lists the runs, newest
first; `os3 jobs logs <job id> [--tail N] [--follow]` prints its log, and with `--follow` new
lines until the run ends; `os3 jobs cancel <job id>` stops it; `os3 jobs wait <job id> --field
state` waits until it has ended and prints how.

`os3 deploy` creates an endpoint, then binds each `--robot` to it. It creates the endpoint under an
Idempotency-Key of its own, one per run of the command, and sends it again under that key on a
network error, so an endpoint whose answer was lost is not made twice. A binding refused or failed
does not stop the others: the output is the endpoint with each binding's deployment or error
(`bindings`), and the exit status is 1 if any failed. `os3 deploy --endpoint <endpoint id> --robot
<robot id>` binds robots to an existing endpoint without creating one, so a rerun binds the robots
left (a new endpoint with the same `--name` would conflict).

A robot's: `os3 robots list [--workspace <id>]` lists them, the deleted left out; `os3 robots revoke <robot id>`
ends its credential for good; `os3 robots delete <robot id>` revokes it and takes it off the list
(its history keeps it). Both are an owner's or admin's (a tenant-wide key with `admin`).

A dataset's: `os3 datasets delete <dataset id>` deletes it with every version, `--version N` that
version alone: it is removed from your organisation. It asks first (`--yes` does not), prints the
API's deletion rows, and on stderr what went. An owner's or admin's (a tenant-wide key holding
`datasets:write` and `admin`); the API refuses it (409, naming the version) while a run or OS3
still reads a version.

`os3 budget set --workspace <id> --hard-cap 100` caps a workspace's GPU use at 100 normalised
H100-hours a month, the unit the portal shows budgets in (the API stores H100-seconds).

[docs/quickstarts](../docs/quickstarts/README.md) walks through enroll, record, upload, fine-tune
two bases in parallel, and compare and deploy with it; `tests/cli/test_quickstarts.py` runs those
walkthroughs against the API. The portal shows the same commands next to its actions
(`web/src/lib/cli.ts`, checked against `COMMANDS` by `tests/cli/test_portal_cli.py`).

A robot runs `os3-robot` instead ([robot_client](../robot_client/README.md): `os3-robot enroll`,
`install-service` and `connect`; a robot OS3 installed has robotcontrol's at
`/opt/os3/agent/bin/os3-robot`); this client has no `robot` command and is not installed there.
