owui-cli 0.3.0__tar.gz → 0.5.0__tar.gz

{owui_cli-0.3.0 → owui_cli-0.5.0}/.gitignore

@@ -1,3 +1,4 @@
+.env
 __pycache__/
 *.pyc
 dist/

owui_cli-0.5.0/AGENTS.md

@@ -0,0 +1,49 @@
+# AGENTS.md — owui-cli
+
+## Version management
+
+The version number appears in two places and **must be kept in sync**:
+
+- `pyproject.toml` → `version = "X.Y.Z"`
+- `src/owui_cli/__init__.py` → `__version__ = "X.Y.Z"`
+
+Bump both when cutting a release.
+
+## Publishing
+
+Every push to `main` auto-publishes to PyPI via GitHub Actions trusted publishing. Bump the version before pushing, and don't push broken code to main.
+
+## Local development install
+
+After making changes, reinstall locally with `uv tool install --force .` so your modified `owui-cli` is the one on your PATH.
+
+## Testing before committing
+
+Always verify changes work against a **production Open WebUI server** before committing. Set `OWUI_URL` and `OWUI_TOKEN` and run the relevant commands to confirm they succeed with real API responses — don't rely on local-only reasoning.
+
+## Architecture
+
+Single-file CLI in `src/owui_cli/cli.py`. The `Resource` base class handles generic CRUD (list, show, deploy, pull, pull-all, delete) for tools, functions, and skills. Special resources (models, knowledge, files, groups, users, chats, configs, prompts) use standalone functions. All commands are registered in the `COMMANDS` dispatch table at the bottom of the file.
+
+## API endpoint patterns
+
+The Open WebUI API is not fully consistent across resources:
+
+- **Tools/functions/skills:** `/api/v1/{resource}/id/{id}`
+- **Models:** `/api/v1/models/model?id={id}`
+- **Knowledge/users:** `/api/v1/{resource}/{id}`
+- **Groups:** `/api/v1/groups/id/{id}`
+
+Always verify the actual endpoint against a running instance when adding new commands.
+
+## Output conventions
+
+All commands support `--json` for machine-readable output. New commands should use the existing output helpers which handle JSON mode automatically:
+
+- `out(data)` — generic output (JSON in `--json` mode, pretty-printed otherwise)
+- `out_table(rows, cols)` — aligned columnar table
+- `out_kv(pairs)` — key-value display
+
+## Schema updates
+
+`update-schema.py` fetches OWUI router sources from GitHub and generates a prompt to feed an LLM. The LLM output goes in `src/owui_cli/data/api-schema.json`. See the script header for the full workflow.

{owui_cli-0.3.0 → owui_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: owui-cli
-Version: 0.3.0
+Version: 0.5.0
 Summary: Admin CLI for Open WebUI instances
 Project-URL: Homepage, https://github.com/rndmcnlly/owui-cli
 Project-URL: Repository, https://github.com/rndmcnlly/owui-cli

{owui_cli-0.3.0 → owui_cli-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "owui-cli"
-version = "0.3.0"
+version = "0.5.0"
 description = "Admin CLI for Open WebUI instances"
 readme = "README.md"
 license = "MIT"

owui_cli-0.5.0/src/owui_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.5.0"

{owui_cli-0.3.0 → owui_cli-0.5.0}/src/owui_cli/cli.py

@@ -43,8 +43,8 @@ def _api(url: str, path: str) -> str:
     return f"{url}{path}"
 
 
-def _get(c: httpx.Client, url: str, path: str, token: str) -> httpx.Response:
-    r = c.get(_api(url, path), headers=_headers(token))
+def _get(c: httpx.Client, url: str, path: str, token: str, params=None) -> httpx.Response:
+    r = c.get(_api(url, path), headers=_headers(token), params=params)
     r.raise_for_status()
     return r
 
@@ -369,6 +369,81 @@ functions_res = Resource("functions", "/api/v1/functions",
     workspace_path="/workspace/functions")
 
 
+# ── valves (admin/global and per-user, for tools and functions) ──────
+#
+# OWUI plugins can declare two valve schemas:
+#   class Valves(BaseModel)      -> /api/v1/{kind}/id/{id}/valves[/spec|/update]
+#   class UserValves(BaseModel)  -> /api/v1/{kind}/id/{id}/valves/user[/spec|/update]
+#
+# The unprefixed `valves*` commands target the admin/global path (most common
+# case: an admin-set API key). The `valves-user*` commands target the per-user
+# path (the calling user's personal valves on the plugin).
+
+def _valves_get(url, token, kind, item_id, scope=""):
+    with httpx.Client(timeout=TIMEOUT) as c:
+        r = _get(c, url, f"/api/v1/{kind}/id/{item_id}/valves{scope}", token)
+    out(r.json())
+
+def _valves_spec(url, token, kind, item_id, scope=""):
+    with httpx.Client(timeout=TIMEOUT) as c:
+        r = _get(c, url, f"/api/v1/{kind}/id/{item_id}/valves{scope}/spec", token)
+    out(r.json())
+
+def _valves_set(url, token, kind, item_id, json_path, scope=""):
+    with open(json_path) as f:
+        payload = json.load(f)
+    with httpx.Client(timeout=TIMEOUT) as c:
+        r = _post(c, url, f"/api/v1/{kind}/id/{item_id}/valves{scope}/update", token, payload)
+    out(r.json())
+
+def _valves_set_field(url, token, kind, item_id, key, value, scope=""):
+    """Set a single field. Value is parsed as JSON; falls back to string."""
+    try:
+        parsed = json.loads(value)
+    except (json.JSONDecodeError, ValueError):
+        parsed = value
+    with httpx.Client(timeout=TIMEOUT) as c:
+        current = _get(c, url, f"/api/v1/{kind}/id/{item_id}/valves{scope}", token).json()
+        current[key] = parsed
+        r = _post(c, url, f"/api/v1/{kind}/id/{item_id}/valves{scope}/update", token, current)
+    out(r.json())
+
+def _valves_unset_field(url, token, kind, item_id, key, scope=""):
+    with httpx.Client(timeout=TIMEOUT) as c:
+        current = _get(c, url, f"/api/v1/{kind}/id/{item_id}/valves{scope}", token).json()
+        if key not in current:
+            die(f"key '{key}' not found in valves")
+        del current[key]
+        r = _post(c, url, f"/api/v1/{kind}/id/{item_id}/valves{scope}/update", token, current)
+    out(r.json())
+
+# Wrappers — admin/global valves (unprefixed: the common case)
+def tools_valves_get(url, token, item_id):                  _valves_get(url, token, "tools", item_id)
+def tools_valves_spec(url, token, item_id):                 _valves_spec(url, token, "tools", item_id)
+def tools_valves_set(url, token, item_id, json_path):       _valves_set(url, token, "tools", item_id, json_path)
+def tools_valves_set_field(url, token, item_id, key, value):_valves_set_field(url, token, "tools", item_id, key, value)
+def tools_valves_unset_field(url, token, item_id, key):     _valves_unset_field(url, token, "tools", item_id, key)
+
+def functions_valves_get(url, token, item_id):                  _valves_get(url, token, "functions", item_id)
+def functions_valves_spec(url, token, item_id):                 _valves_spec(url, token, "functions", item_id)
+def functions_valves_set(url, token, item_id, json_path):       _valves_set(url, token, "functions", item_id, json_path)
+def functions_valves_set_field(url, token, item_id, key, value):_valves_set_field(url, token, "functions", item_id, key, value)
+def functions_valves_unset_field(url, token, item_id, key):     _valves_unset_field(url, token, "functions", item_id, key)
+
+# Wrappers — per-user valves (`valves-user*`)
+def tools_valves_user_get(url, token, item_id):                  _valves_get(url, token, "tools", item_id, "/user")
+def tools_valves_user_spec(url, token, item_id):                 _valves_spec(url, token, "tools", item_id, "/user")
+def tools_valves_user_set(url, token, item_id, json_path):       _valves_set(url, token, "tools", item_id, json_path, "/user")
+def tools_valves_user_set_field(url, token, item_id, key, value):_valves_set_field(url, token, "tools", item_id, key, value, "/user")
+def tools_valves_user_unset_field(url, token, item_id, key):     _valves_unset_field(url, token, "tools", item_id, key, "/user")
+
+def functions_valves_user_get(url, token, item_id):                  _valves_get(url, token, "functions", item_id, "/user")
+def functions_valves_user_spec(url, token, item_id):                 _valves_spec(url, token, "functions", item_id, "/user")
+def functions_valves_user_set(url, token, item_id, json_path):       _valves_set(url, token, "functions", item_id, json_path, "/user")
+def functions_valves_user_set_field(url, token, item_id, key, value):_valves_set_field(url, token, "functions", item_id, key, value, "/user")
+def functions_valves_user_unset_field(url, token, item_id, key):     _valves_unset_field(url, token, "functions", item_id, key, "/user")
+
+
 class SkillsResource(Resource):
     """Skills use frontmatter and have grant/revoke commands."""
 
@@ -614,9 +689,20 @@ def models_pull_all(url, token, out_dir="."):
 # ── knowledge (special: files subresource, file/remove is destructive) ─
 
 def knowledge_list(url, token):
+    kbs = []
+    page = 1
     with httpx.Client(timeout=TIMEOUT) as c:
-        data = _get(c, url, "/api/v1/knowledge/", token).json()
-    kbs = data if isinstance(data, list) else data.get("items", [])
+        while True:
+            data = _get(c, url, "/api/v1/knowledge/", token, params={"page": page}).json()
+            batch = data["items"] if isinstance(data, dict) else data
+            if not batch:
+                break
+            kbs.extend(batch)
+            if isinstance(data, dict):
+                if len(kbs) >= data.get("total", 0): break
+            else:
+                break
+            page += 1
     rows = [{"id": k.get("id",""), "name": k.get("name",""),
              "desc": (k.get("description") or "")[:50]}
             for k in sorted(kbs, key=lambda k: k.get("name",""))]
@@ -667,12 +753,25 @@ def knowledge_remove_file(url, token, kb_id, file_id):
 # ── files ─────────────────────────────────────────────────────────────
 
 def files_list(url, token):
+    rows = []
+    page = 1
     with httpx.Client(timeout=TIMEOUT) as c:
-        data = _get(c, url, "/api/v1/files/", token).json()
-    rows = [{"id": f.get("id",""),
-             "name": (f.get("meta") or {}).get("name") or f.get("filename",""),
-             "size": str((f.get("meta") or {}).get("size","?"))}
-            for f in data]
+        while True:
+            data = _get(c, url, "/api/v1/files/", token,
+                        params={"page": page, "content": "false"}).json()
+            # OWUI >= 0.9 returns {items, total}; older versions return a bare list.
+            batch = data["items"] if isinstance(data, dict) else data
+            if not batch:
+                break
+            rows.extend({"id": f.get("id",""),
+                         "name": (f.get("meta") or {}).get("name") or f.get("filename",""),
+                         "size": str((f.get("meta") or {}).get("size","?"))}
+                        for f in batch)
+            if isinstance(data, dict):
+                if len(rows) >= data.get("total", 0): break
+            else:
+                break  # bare-list response is unpaginated
+            page += 1
     out_table(rows, [("FILE_ID","id",36), ("NAME","name",30), ("SIZE","size",8)])
 
 def files_show(url, token, file_id):
@@ -1037,6 +1136,26 @@ for res in [tools_res, functions_res, skills_res]:
 
 # Register special resources
 COMMANDS.update({
+    ("tools",     "valves"):      (tools_valves_get,        "<id>",                  (1, 1)),
+    ("tools",     "valves-spec"): (tools_valves_spec,       "<id>",                  (1, 1)),
+    ("tools",     "valves-set"):  (tools_valves_set,        "<id> <valves.json>",    (2, 2)),
+    ("tools",     "valves-set-field"):  (tools_valves_set_field,   "<id> <key> <value>",  (3, 3)),
+    ("tools",     "valves-unset-field"):(tools_valves_unset_field, "<id> <key>",          (2, 2)),
+    ("tools",     "valves-user"):      (tools_valves_user_get,        "<id>",                  (1, 1)),
+    ("tools",     "valves-user-spec"): (tools_valves_user_spec,       "<id>",                  (1, 1)),
+    ("tools",     "valves-user-set"):  (tools_valves_user_set,        "<id> <valves.json>",    (2, 2)),
+    ("tools",     "valves-user-set-field"):  (tools_valves_user_set_field,   "<id> <key> <value>",  (3, 3)),
+    ("tools",     "valves-user-unset-field"):(tools_valves_user_unset_field, "<id> <key>",          (2, 2)),
+    ("functions", "valves"):      (functions_valves_get,    "<id>",                  (1, 1)),
+    ("functions", "valves-spec"): (functions_valves_spec,   "<id>",                  (1, 1)),
+    ("functions", "valves-set"):  (functions_valves_set,    "<id> <valves.json>",    (2, 2)),
+    ("functions", "valves-set-field"):  (functions_valves_set_field,   "<id> <key> <value>",  (3, 3)),
+    ("functions", "valves-unset-field"):(functions_valves_unset_field, "<id> <key>",          (2, 2)),
+    ("functions", "valves-user"):      (functions_valves_user_get,    "<id>",                  (1, 1)),
+    ("functions", "valves-user-spec"): (functions_valves_user_spec,   "<id>",                  (1, 1)),
+    ("functions", "valves-user-set"):  (functions_valves_user_set,    "<id> <valves.json>",    (2, 2)),
+    ("functions", "valves-user-set-field"):  (functions_valves_user_set_field,   "<id> <key> <value>",  (3, 3)),
+    ("functions", "valves-user-unset-field"):(functions_valves_user_unset_field, "<id> <key>",          (2, 2)),
     ("models",    "list"):        (models_list,          "",                    (0, 0)),
     ("models",    "show"):        (models_show,          "<id>",                (1, 1)),
     ("models",    "create"):      (models_create,        "<model.json>",        (1, 1)),
@@ -1130,7 +1249,12 @@ def main():
     resource, command = args[0], args[1]
     key = (resource, command)
 
+    # Subcommands are plural (chats, models, etc.) to mirror the OWUI API
+    # paths (/api/v1/chats/, /api/v1/models, ...), not typical CLI convention.
     if key not in COMMANDS:
+        plural = resource + "s"
+        if (plural, command) in COMMANDS:
+            die(f"resources are plural: use '{plural} {command}' not '{resource} {command}'")
         die(f"unknown: {resource} {command}")
 
     fn, arg_spec, (min_args, max_args) = COMMANDS[key]

owui_cli-0.5.0/uv.lock

@@ -0,0 +1,91 @@
+version = 1
+revision = 2
+requires-python = ">=3.11"
+
+[[package]]
+name = "anyio"
+version = "4.13.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "idna" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/19/14/2c5dd9f512b66549ae92767a9c7b330ae88e1932ca57876909410251fe13/anyio-4.13.0.tar.gz", hash = "sha256:334b70e641fd2221c1505b3890c69882fe4a2df910cba14d97019b90b24439dc", size = 231622, upload-time = "2026-03-24T12:59:09.671Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/da/42/e921fccf5015463e32a3cf6ee7f980a6ed0f395ceeaa45060b61d86486c2/anyio-4.13.0-py3-none-any.whl", hash = "sha256:08b310f9e24a9594186fd75b4f73f4a4152069e3853f1ed8bfbf58369f4ad708", size = 114353, upload-time = "2026-03-24T12:59:08.246Z" },
+]
+
+[[package]]
+name = "certifi"
+version = "2026.2.25"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/af/2d/7bf41579a8986e348fa033a31cdd0e4121114f6bce2457e8876010b092dd/certifi-2026.2.25.tar.gz", hash = "sha256:e887ab5cee78ea814d3472169153c2d12cd43b14bd03329a39a9c6e2e80bfba7", size = 155029, upload-time = "2026-02-25T02:54:17.342Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9a/3c/c17fb3ca2d9c3acff52e30b309f538586f9f5b9c9cf454f3845fc9af4881/certifi-2026.2.25-py3-none-any.whl", hash = "sha256:027692e4402ad994f1c42e52a4997a9763c646b73e4096e4d5d6db8af1d6f0fa", size = 153684, upload-time = "2026-02-25T02:54:15.766Z" },
+]
+
+[[package]]
+name = "h11"
+version = "0.16.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/01/ee/02a2c011bdab74c6fb3c75474d40b3052059d95df7e73351460c8588d963/h11-0.16.0.tar.gz", hash = "sha256:4e35b956cf45792e4caa5885e69fba00bdbc6ffafbfa020300e549b208ee5ff1", size = 101250, upload-time = "2025-04-24T03:35:25.427Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/04/4b/29cac41a4d98d144bf5f6d33995617b185d14b22401f75ca86f384e87ff1/h11-0.16.0-py3-none-any.whl", hash = "sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86", size = 37515, upload-time = "2025-04-24T03:35:24.344Z" },
+]
+
+[[package]]
+name = "httpcore"
+version = "1.0.9"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "certifi" },
+    { name = "h11" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/06/94/82699a10bca87a5556c9c59b5963f2d039dbd239f25bc2a63907a05a14cb/httpcore-1.0.9.tar.gz", hash = "sha256:6e34463af53fd2ab5d807f399a9b45ea31c3dfa2276f15a2c3f00afff6e176e8", size = 85484, upload-time = "2025-04-24T22:06:22.219Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7e/f5/f66802a942d491edb555dd61e3a9961140fd64c90bce1eafd741609d334d/httpcore-1.0.9-py3-none-any.whl", hash = "sha256:2d400746a40668fc9dec9810239072b40b4484b640a8c38fd654a024c7a1bf55", size = 78784, upload-time = "2025-04-24T22:06:20.566Z" },
+]
+
+[[package]]
+name = "httpx"
+version = "0.28.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+    { name = "certifi" },
+    { name = "httpcore" },
+    { name = "idna" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b1/df/48c586a5fe32a0f01324ee087459e112ebb7224f646c0b5023f5e79e9956/httpx-0.28.1.tar.gz", hash = "sha256:75e98c5f16b0f35b567856f597f06ff2270a374470a5c2392242528e3e3e42fc", size = 141406, upload-time = "2024-12-06T15:37:23.222Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2a/39/e50c7c3a983047577ee07d2a9e53faf5a69493943ec3f6a384bdc792deb2/httpx-0.28.1-py3-none-any.whl", hash = "sha256:d909fcccc110f8c7faf814ca82a9a4d816bc5a6dbfea25d6591d6985b8ba59ad", size = 73517, upload-time = "2024-12-06T15:37:21.509Z" },
+]
+
+[[package]]
+name = "idna"
+version = "3.11"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/6f/6d/0703ccc57f3a7233505399edb88de3cbd678da106337b9fcde432b65ed60/idna-3.11.tar.gz", hash = "sha256:795dafcc9c04ed0c1fb032c2aa73654d8e8c5023a7df64a53f39190ada629902", size = 194582, upload-time = "2025-10-12T14:55:20.501Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0e/61/66938bbb5fc52dbdf84594873d5b51fb1f7c7794e9c0f5bd885f30bc507b/idna-3.11-py3-none-any.whl", hash = "sha256:771a87f49d9defaf64091e6e6fe9c18d4833f140bd19464795bc32d966ca37ea", size = 71008, upload-time = "2025-10-12T14:55:18.883Z" },
+]
+
+[[package]]
+name = "owui-cli"
+version = "0.2.0"
+source = { editable = "." }
+dependencies = [
+    { name = "httpx" },
+]
+
+[package.metadata]
+requires-dist = [{ name = "httpx", specifier = ">=0.27" }]
+
+[[package]]
+name = "typing-extensions"
+version = "4.15.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/72/94/1a15dd82efb362ac84269196e94cf00f187f7ed21c242792a923cdb1c61f/typing_extensions-4.15.0.tar.gz", hash = "sha256:0cea48d173cc12fa28ecabc3b837ea3cf6f38c6d1136f85cbaaf598984861466", size = 109391, upload-time = "2025-08-25T13:49:26.313Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl", hash = "sha256:f0fa19c6845758ab08074a0cfa8b7aecb71c999ca73d62883bc25cc018c4e548", size = 44614, upload-time = "2025-08-25T13:49:24.86Z" },
+]

owui_cli-0.3.0/src/owui_cli/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.3.0"