outo-models-cli 0.2.3__tar.gz → 0.2.4__tar.gz

outo_models_cli-0.2.4/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.5
+Name: outo-models-cli
+Version: 0.2.4
+Summary: Command-line client for self-hosted outo-models servers — auth, repo, download, and upload.
+Project-URL: Homepage, https://github.com/outo-models/outo-models
+Project-URL: Documentation, https://github.com/outo-models/outo-models/blob/main/omc/README.md
+Project-URL: Repository, https://github.com/outo-models/outo-models
+Project-URL: Issues, https://github.com/outo-models/outo-models/issues
+Author: outo-models developers
+License: Apache-2.0
+License-File: LICENSE
+Keywords: cli,huggingface,model-hub,outo-models,self-hosted
+Classifier: Development Status :: 4 - Beta
+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 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Typing :: Typed
+Requires-Python: <3.13,>=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.8
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# outo-models-cli
+
+`omc` — the user-facing command-line client for self-hosted
+[outo-models](https://github.com/outo-models/outo-models) servers.
+Hugging Face CLI surface, adapted to a self-hosted multi-server world.
+
+The CLI is documented entirely in-band: typing `omc` (bare) or
+`omc --help` prints a comprehensive reference covering PURPOSE,
+CONCEPTS, GETTING STARTED, COMMAND INDEX, CONFIG, and MORE HELP.
+Every subcommand (`omc auth login`, `omc repo create`, `omc upload`,
+...) has the same six-section layout — PURPOSE / USAGE / EXAMPLES /
+EXIT CODES / NOTES — so an AI agent reading one page has the full
+mental model of every other page.
+
+## Install
+
+```bash
+pip install outo-models-cli
+```
+
+Both `omc` and `outo-models-cli` console scripts are installed.
+
+## Quickstart (copy-pasteable)
+
+```bash
+# 1. Log in (prompts for a PAT, masked)
+omc auth login --server https://models.example.com
+
+# 2. Verify
+omc auth whoami
+omc auth status
+
+# 3. Create a model repo
+omc repo create my-model --kind model --public --description "My first model"
+
+# 4. Browse the tree
+omc ls alice/my-model
+
+# 5. Download everything
+omc download alice/my-model --local-dir ./my-model
+
+# 6. Upload a folder
+omc upload alice/my-model ./checkpoints --path-in-repo weights --message "v1"
+```
+
+## Command index
+
+| Command          | Purpose                                              | Auth |
+| ---------------- | ---------------------------------------------------- | ---- |
+| `omc auth login`    | Verify a PAT and store it for one server.          | no   |
+| `omc auth logout`   | Remove the stored credential for one server.       | no   |
+| `omc auth whoami`   | Print user, server, role, and token source.        | yes  |
+| `omc auth status`   | List every configured server and the default one.  | no   |
+| `omc repo create`   | Create a new repository on the target server.      | yes  |
+| `omc repo delete`   | Delete a repository (owner or admin only).         | yes  |
+| `omc repo list`     | List repositories on the target server.            | yes  |
+| `omc ls`            | List one directory of a repository at a revision.  | yes  |
+| `omc download`      | Recursively download a repository (resumable, LFS).| yes  |
+| `omc upload`        | Upload a file or folder (auto-routes >100 MiB → LFS). | yes  |
+
+For the full PURPOSE / USAGE / EXAMPLES / EXIT CODES / NOTES reference
+of any command, run `omc <command> --help` (e.g. `omc upload --help`).
+
+## Environment variables
+
+Every environment variable the CLI reads:
+
+* `OMC_SERVER` — server URL override. Highest priority, but below
+  the `--server` flag. Never persisted.
+* `OMC_TOKEN` — bearer credential override. Used verbatim, never
+  persisted; lets CI jobs run without a config file.
+* `OMC_CONFIG_DIR` — full override for the config directory.
+* `XDG_CONFIG_HOME` — standard XDG base directory (used when
+  `OMC_CONFIG_DIR` is unset).
+* `HOME` — fallback (`$HOME/.config/omc`) when neither of the above
+  is set.
+
+Resolution order (highest priority first):
+
+```
+--server flag  >  OMC_SERVER  >  default_server in config  >
+first server in config file
+OMC_TOKEN  >  token stored for the resolved server
+```
+
+## Configuration
+
+Credentials are stored at `$OMC_CONFIG_DIR/config.json` (defaults to
+`$XDG_CONFIG_HOME/omc/config.json` or `~/.config/omc/config.json`).
+The file has mode `0600`, owned by the current user; the CLI tightens
+the permissions on every save, so a stray `chmod 644` is repaired
+automatically.
+
+File shape:
+
+```json
+{
+  "default_server": "https://models.example.com",
+  "servers": {
+    "https://models.example.com": {
+      "token": "...",
+      "username": "alice"
+    }
+  }
+}
+```
+
+URL keys are normalized: trailing slashes stripped, scheme + host
+lower-cased, `http://` prepended when the input carries no scheme.
+
+## Git LFS
+
+Files larger than 100 MiB are uploaded through Git LFS automatically;
+the CLI partitions the input set, runs the LFS batch + PUT dance for
+each large file, and commits the resulting pointer text alongside any
+small files in a single commit. No `git lfs track` setup is required
+on the user side. The download command follows the same path
+transparently.
+
+## Exit codes
+
+Every command emits one of:
+
+| Code | Meaning                                                           |
+| ---- | ----------------------------------------------------------------- |
+| `0`  | Success.                                                          |
+| `1`  | Command failed (network, auth, validation, file system).           |
+| `2`  | Typer-level usage error (unknown flag, missing required argument).|
+
+Re-run with `--debug` to get a full Python traceback instead of the
+single English error line on stderr.
+
+## License
+
+Apache-2.0.

outo_models_cli-0.2.4/README.md

@@ -0,0 +1,135 @@
+# outo-models-cli
+
+`omc` — the user-facing command-line client for self-hosted
+[outo-models](https://github.com/outo-models/outo-models) servers.
+Hugging Face CLI surface, adapted to a self-hosted multi-server world.
+
+The CLI is documented entirely in-band: typing `omc` (bare) or
+`omc --help` prints a comprehensive reference covering PURPOSE,
+CONCEPTS, GETTING STARTED, COMMAND INDEX, CONFIG, and MORE HELP.
+Every subcommand (`omc auth login`, `omc repo create`, `omc upload`,
+...) has the same six-section layout — PURPOSE / USAGE / EXAMPLES /
+EXIT CODES / NOTES — so an AI agent reading one page has the full
+mental model of every other page.
+
+## Install
+
+```bash
+pip install outo-models-cli
+```
+
+Both `omc` and `outo-models-cli` console scripts are installed.
+
+## Quickstart (copy-pasteable)
+
+```bash
+# 1. Log in (prompts for a PAT, masked)
+omc auth login --server https://models.example.com
+
+# 2. Verify
+omc auth whoami
+omc auth status
+
+# 3. Create a model repo
+omc repo create my-model --kind model --public --description "My first model"
+
+# 4. Browse the tree
+omc ls alice/my-model
+
+# 5. Download everything
+omc download alice/my-model --local-dir ./my-model
+
+# 6. Upload a folder
+omc upload alice/my-model ./checkpoints --path-in-repo weights --message "v1"
+```
+
+## Command index
+
+| Command          | Purpose                                              | Auth |
+| ---------------- | ---------------------------------------------------- | ---- |
+| `omc auth login`    | Verify a PAT and store it for one server.          | no   |
+| `omc auth logout`   | Remove the stored credential for one server.       | no   |
+| `omc auth whoami`   | Print user, server, role, and token source.        | yes  |
+| `omc auth status`   | List every configured server and the default one.  | no   |
+| `omc repo create`   | Create a new repository on the target server.      | yes  |
+| `omc repo delete`   | Delete a repository (owner or admin only).         | yes  |
+| `omc repo list`     | List repositories on the target server.            | yes  |
+| `omc ls`            | List one directory of a repository at a revision.  | yes  |
+| `omc download`      | Recursively download a repository (resumable, LFS).| yes  |
+| `omc upload`        | Upload a file or folder (auto-routes >100 MiB → LFS). | yes  |
+
+For the full PURPOSE / USAGE / EXAMPLES / EXIT CODES / NOTES reference
+of any command, run `omc <command> --help` (e.g. `omc upload --help`).
+
+## Environment variables
+
+Every environment variable the CLI reads:
+
+* `OMC_SERVER` — server URL override. Highest priority, but below
+  the `--server` flag. Never persisted.
+* `OMC_TOKEN` — bearer credential override. Used verbatim, never
+  persisted; lets CI jobs run without a config file.
+* `OMC_CONFIG_DIR` — full override for the config directory.
+* `XDG_CONFIG_HOME` — standard XDG base directory (used when
+  `OMC_CONFIG_DIR` is unset).
+* `HOME` — fallback (`$HOME/.config/omc`) when neither of the above
+  is set.
+
+Resolution order (highest priority first):
+
+```
+--server flag  >  OMC_SERVER  >  default_server in config  >
+first server in config file
+OMC_TOKEN  >  token stored for the resolved server
+```
+
+## Configuration
+
+Credentials are stored at `$OMC_CONFIG_DIR/config.json` (defaults to
+`$XDG_CONFIG_HOME/omc/config.json` or `~/.config/omc/config.json`).
+The file has mode `0600`, owned by the current user; the CLI tightens
+the permissions on every save, so a stray `chmod 644` is repaired
+automatically.
+
+File shape:
+
+```json
+{
+  "default_server": "https://models.example.com",
+  "servers": {
+    "https://models.example.com": {
+      "token": "...",
+      "username": "alice"
+    }
+  }
+}
+```
+
+URL keys are normalized: trailing slashes stripped, scheme + host
+lower-cased, `http://` prepended when the input carries no scheme.
+
+## Git LFS
+
+Files larger than 100 MiB are uploaded through Git LFS automatically;
+the CLI partitions the input set, runs the LFS batch + PUT dance for
+each large file, and commits the resulting pointer text alongside any
+small files in a single commit. No `git lfs track` setup is required
+on the user side. The download command follows the same path
+transparently.
+
+## Exit codes
+
+Every command emits one of:
+
+| Code | Meaning                                                           |
+| ---- | ----------------------------------------------------------------- |
+| `0`  | Success.                                                          |
+| `1`  | Command failed (network, auth, validation, file system).           |
+| `2`  | Typer-level usage error (unknown flag, missing required argument).|
+
+Re-run with `--debug` to get a full Python traceback instead of the
+single English error line on stderr.
+
+## License
+
+Apache-2.0.

{outo_models_cli-0.2.3 → outo_models_cli-0.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "outo-models-cli"
-version = "0.2.3"
+version = "0.2.4"
 description = "Command-line client for self-hosted outo-models servers — auth, repo, download, and upload."
 readme = "README.md"
 requires-python = ">=3.12,<3.13"

outo_models_cli-0.2.4/src/outo_models_cli/commands/_help_text/__init__.py

@@ -0,0 +1,132 @@
+"""Structured help text for every `omc` command and the root app.
+
+Every block follows the same six-section layout so an AI reading the
+help output can locate the bit it needs without scanning for prose:
+
+    PURPOSE      one paragraph: what the command does, when to use it
+    USAGE        exact invocation shape (positional args + flag list)
+    ARGUMENTS    covered by Typer's auto-generated table; here we list
+                 the env-var overrides that affect argument resolution
+    EXAMPLES     3-6 realistic invocations, each with a one-line note
+    EXIT CODES   every exit value the command can produce and its meaning
+    NOTES        auth requirements, config file location, server URL
+                 resolution order, common error strings + fixes
+
+The constants are plain strings (no `rich.console.Console` rendering),
+so a non-TTY pipeline (`omc --help | grep EXAMPLES`) reads them cleanly.
+`rich_markup_mode="rich"` is set on the root app, so the `[bold]` /
+`[dim]` tags inside the constants are processed by Typer when the help
+is rendered through a TTY and rendered verbatim otherwise.
+
+Why a dedicated subpackage: the six-section layout must be CONSISTENT
+across every command, and the markers are referenced both from the
+command definitions (`epilog=...`) and from the test suite (asserted on
+`omc <cmd> --help` output). Concentrating them in one import path
+keeps the markers and the prose in lock-step so a one-place edit
+cannot drift out of sync with the tests, while splitting the bodies
+across per-command files keeps each module under the 250-LOC ceiling.
+"""
+
+from __future__ import annotations
+
+from outo_models_cli.commands._help_text._auth import (
+    AUTH_APP_HELP,
+    AUTH_APP_MARKERS,
+)
+from outo_models_cli.commands._help_text._auth_cmds import (
+    AUTH_LOGIN_EPILOG,
+    AUTH_LOGIN_MARKERS,
+    AUTH_LOGOUT_EPILOG,
+    AUTH_LOGOUT_MARKERS,
+    AUTH_STATUS_EPILOG,
+    AUTH_STATUS_MARKERS,
+    AUTH_WHOAMI_EPILOG,
+    AUTH_WHOAMI_MARKERS,
+)
+from outo_models_cli.commands._help_text._common import (
+    COMMAND_INDEX_MARKER,
+    COMMON_EXIT_CODES,
+    CONCEPTS_MARKER,
+    CONFIG_MARKER,
+    CREDENTIAL_RESOLUTION_ORDER,
+    ENVIRONMENT_VARIABLES_MARKER,
+    EXAMPLES_MARKER,
+    EXIT_CODES_MARKER,
+    GETTING_STARTED_MARKER,
+    MORE_HELP_MARKER,
+    NOTES_MARKER,
+    PURPOSE_MARKER,
+    SERVER_RESOLUTION_ORDER,
+    USAGE_MARKER,
+)
+from outo_models_cli.commands._help_text._repo import (
+    REPO_APP_HELP,
+    REPO_APP_MARKERS,
+    REPO_CREATE_EPILOG,
+    REPO_DELETE_EPILOG,
+    REPO_LIST_EPILOG,
+    REPO_MARKERS,
+)
+from outo_models_cli.commands._help_text._root import ROOT_HELP, ROOT_MARKERS
+from outo_models_cli.commands._help_text._transfer import (
+    DOWNLOAD_EPILOG,
+    LS_EPILOG,
+    TRANSFER_MARKERS,
+    UPLOAD_EPILOG,
+)
+
+# Required markers per command - the test suite asserts on each entry.
+COMMAND_MARKERS: dict[str, tuple[str, ...]] = {
+    "auth login": AUTH_LOGIN_MARKERS,
+    "auth logout": AUTH_LOGOUT_MARKERS,
+    "auth whoami": AUTH_WHOAMI_MARKERS,
+    "auth status": AUTH_STATUS_MARKERS,
+    "repo create": REPO_MARKERS,
+    "repo delete": REPO_MARKERS,
+    "repo list": REPO_MARKERS,
+    "ls": TRANSFER_MARKERS,
+    "download": TRANSFER_MARKERS,
+    "upload": TRANSFER_MARKERS,
+}
+
+# Auth-app and repo-app markers (the `omc auth --help` / `omc repo --help`
+# intermediate screens).
+APP_MARKERS: dict[str, tuple[str, ...]] = {
+    "auth": AUTH_APP_MARKERS,
+    "repo": REPO_APP_MARKERS,
+}
+
+
+__all__ = [
+    "APP_MARKERS",
+    "AUTH_APP_HELP",
+    "AUTH_LOGIN_EPILOG",
+    "AUTH_LOGOUT_EPILOG",
+    "AUTH_STATUS_EPILOG",
+    "AUTH_WHOAMI_EPILOG",
+    "COMMAND_INDEX_MARKER",
+    "COMMAND_MARKERS",
+    "COMMON_EXIT_CODES",
+    "CONCEPTS_MARKER",
+    "CONFIG_MARKER",
+    "CREDENTIAL_RESOLUTION_ORDER",
+    "DOWNLOAD_EPILOG",
+    "ENVIRONMENT_VARIABLES_MARKER",
+    "EXAMPLES_MARKER",
+    "EXIT_CODES_MARKER",
+    "GETTING_STARTED_MARKER",
+    "LS_EPILOG",
+    "MORE_HELP_MARKER",
+    "NOTES_MARKER",
+    "PURPOSE_MARKER",
+    "REPO_APP_HELP",
+    "REPO_CREATE_EPILOG",
+    "REPO_DELETE_EPILOG",
+    "REPO_LIST_EPILOG",
+    "ROOT_HELP",
+    "ROOT_MARKERS",
+    "SERVER_RESOLUTION_ORDER",
+    "TRANSFER_MARKERS",
+    "UPLOAD_EPILOG",
+    "USAGE_MARKER",
+]

outo_models_cli-0.2.4/src/outo_models_cli/commands/_help_text/_auth.py

@@ -0,0 +1,38 @@
+"""Help text for the `omc auth` sub-Typer itself (the intermediate screen).
+
+The four subcommands' help lives in `_auth_cmds.py`; this module only
+owns the body shown by `omc auth --help` (the parent Typer's help) and
+the marker tuple the test suite uses to lock that body.
+"""
+
+from __future__ import annotations
+
+from outo_models_cli.commands._help_text._common import (
+    PURPOSE_MARKER,
+    USAGE_MARKER,
+)
+
+AUTH_SUBCOMMAND_INDEX: str = (
+    "AUTH SUBCOMMANDS\n"
+    "  login    Verify a PAT against the server and store it for `--server`.\n"
+    "  logout   Remove the stored credential for one server.\n"
+    "  whoami   Print the authenticated user, server, role, and token source.\n"
+    "  status   List every configured server and mark the default."
+)
+
+AUTH_APP_HELP: str = "\n\n".join(
+    [
+        "PURPOSE\n"
+        "  Manage stored credentials: log in, log out, verify, inspect.\n"
+        "  All four subcommands share the same server-resolution rules.",
+        "USAGE\n  omc auth [SUBCOMMAND] [OPTIONS]",
+        AUTH_SUBCOMMAND_INDEX,
+        "Run `omc auth <subcommand> --help` for the full PURPOSE / EXAMPLES /\n"
+        "EXIT CODES / NOTES reference of any individual subcommand.",
+    ],
+)
+
+AUTH_APP_MARKERS: tuple[str, ...] = (PURPOSE_MARKER, USAGE_MARKER)
+
+
+__all__ = ["AUTH_APP_HELP", "AUTH_APP_MARKERS", "AUTH_SUBCOMMAND_INDEX"]