Add vws generate-vumark command

.github/workflows/release.yml

@@ -200,6 +200,8 @@ jobs:
             spec: bin/vuforia-cloud-reco.py
           - name: vws-linux
             spec: bin/vuforia-web-services.py
+          - name: vumark-linux
+            spec: bin/vumark.py
 
     permissions:
       contents: write
@@ -348,12 +350,24 @@ jobs:
           upload_exe_with_name: vws-windows
           clean_checkout: false
 
+      - name: Create Windows binary for VuMark generation
+        uses: sayyid5416/pyinstaller@v1
+        with:
+          python_ver: '3.13'
+          pyinstaller_ver: ==6.12.0
+          spec: bin/vumark.py
+          requirements: requirements.txt
+          options: --onefile, --name "vumark-windows"
+          upload_exe_with_name: vumark-windows
+          clean_checkout: false
+
       - name: Upload Windows binaries to release
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |-
           gh release upload ${{ needs.build.outputs.new_tag }} dist/vws-windows.exe --clobber
           gh release upload ${{ needs.build.outputs.new_tag }} dist/vuforia-cloud-reco-windows.exe --clobber
+          gh release upload ${{ needs.build.outputs.new_tag }} dist/vumark-windows.exe --clobber
 
   build-macos:
     name: Build macOS binaries
@@ -408,12 +422,24 @@ jobs:
           upload_exe_with_name: vws-macos
           clean_checkout: false
 
+      - name: Create macOS binary for VuMark generation
+        uses: sayyid5416/pyinstaller@v1
+        with:
+          python_ver: '3.13'
+          pyinstaller_ver: ==6.12.0
+          spec: bin/vumark.py
+          requirements: requirements.txt
+          options: --onefile, --name "vumark-macos"
+          upload_exe_with_name: vumark-macos
+          clean_checkout: false
+
       - name: Upload macOS binaries to release
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |-
           gh release upload ${{ needs.build.outputs.new_tag }} dist/vws-macos --clobber
           gh release upload ${{ needs.build.outputs.new_tag }} dist/vuforia-cloud-reco-macos --clobber
+          gh release upload ${{ needs.build.outputs.new_tag }} dist/vumark-macos --clobber
 
   publish-to-winget:
     name: Publish to WinGet
@@ -423,6 +449,9 @@ jobs:
       contents: read
 
     steps:
+      # The first PR for a new package ID must be created manually on
+      # microsoft/winget-pkgs. We intentionally do not add vumark here yet.
+      # Tracked in https://github.com/VWS-Python/vws-cli/issues/1984.
       - uses: vedantmgoyal9/winget-releaser@v2
         with:
           identifier: VWSPython.vws-cli

README.rst

@@ -69,6 +69,12 @@ To use ``vuforia-cloud-reco``:
 
    $ docker run --rm --entrypoint vuforia-cloud-reco "ghcr.io/vws-python/vws-cli" --help
 
+To use ``vumark``:
+
+.. code-block:: console
+
+   $ docker run --rm --entrypoint vumark "ghcr.io/vws-python/vws-cli" --help
+
 With winget (Windows)
 ^^^^^^^^^^^^^^^^^^^^^
 
@@ -92,6 +98,11 @@ Pre-built Windows binaries
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Download the Windows executables from the `latest release`_ and place them in a directory on your ``PATH``.
+The filenames are:
+
+* ``vws-windows.exe``
+* ``vuforia-cloud-reco-windows.exe``
+* ``vumark-windows.exe``
 
 .. _latest release: https://github.com/VWS-Python/vws-cli/releases/latest
 

bin/vumark.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+
+"""Run VuMark generation CLI."""
+
+from vws_cli.vumark import generate_vumark
+
+generate_vumark()

docs/source/commands.rst

@@ -8,3 +8,6 @@ Commands
 .. click:: vws_cli.query:vuforia_cloud_reco
   :prog: vuforia-cloud-reco
   :show-nested:
+
+.. click:: vws_cli.vumark:generate_vumark
+  :prog: vumark

docs/source/install.rst

@@ -61,6 +61,13 @@ To use ``vuforia-cloud-reco``:
 
    $ docker run --rm --entrypoint vuforia-cloud-reco "|docker-image|" --help
 
+To use ``vumark``:
+
+.. code-block:: console
+   :substitutions:
+
+   $ docker run --rm --entrypoint vumark "|docker-image|" --help
+
 With winget (Windows)
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -83,11 +90,18 @@ Pre-built Linux (x86) binaries
        chmod +x /usr/local/bin/vws
    $ curl --fail -L "https://github.com/|github-owner|/|github-repository|/releases/download/|release|/vuforia-cloud-reco-linux" -o /usr/local/bin/vuforia-cloud-reco &&
        chmod +x /usr/local/bin/vuforia-cloud-reco
+   $ curl --fail -L "https://github.com/|github-owner|/|github-repository|/releases/download/|release|/vumark-linux" -o /usr/local/bin/vumark &&
+       chmod +x /usr/local/bin/vumark
 
 Pre-built Windows binaries
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Download the Windows executables from the `latest release`_ and place them in a directory on your ``PATH``.
+The filenames are:
+
+* ``vws-windows.exe``
+* ``vuforia-cloud-reco-windows.exe``
+* ``vumark-windows.exe``
 
 .. _latest release: https://github.com/VWS-Python/vws-cli/releases/latest
 
@@ -101,13 +115,16 @@ Pre-built macOS (ARM) binaries
        chmod +x /usr/local/bin/vws
    $ curl --fail -L "https://github.com/|github-owner|/|github-repository|/releases/download/|release|/vuforia-cloud-reco-macos" -o /usr/local/bin/vuforia-cloud-reco &&
        chmod +x /usr/local/bin/vuforia-cloud-reco
+   $ curl --fail -L "https://github.com/|github-owner|/|github-repository|/releases/download/|release|/vumark-macos" -o /usr/local/bin/vumark &&
+       chmod +x /usr/local/bin/vumark
 
 You may need to remove the quarantine attribute to allow the binaries to run:
 
 .. code-block:: console
 
    $ xattr -d com.apple.quarantine /usr/local/bin/vws
    $ xattr -d com.apple.quarantine /usr/local/bin/vuforia-cloud-reco
+   $ xattr -d com.apple.quarantine /usr/local/bin/vumark
 
 Shell completion
 ~~~~~~~~~~~~~~~~

docs/source/release-process.rst

@@ -8,7 +8,9 @@ Outcomes
 * A new package on PyPI.
 * A new Homebrew recipe available to install.
 * A new Docker image on GitHub Container Registry.
-* New Winget packages available to install.
+* New binary assets attached to the GitHub release.
+* New Winget packages available to install for ``vws`` and
+  ``vuforia-cloud-reco``.
 
 Perform a Release
 ~~~~~~~~~~~~~~~~~
@@ -23,3 +25,11 @@ Perform a Release
       $ gh workflow run release.yml --repo "|github-owner|/|github-repository|"
 
 .. _Install GitHub CLI: https://cli.github.com/
+
+WinGet for ``vumark``
+~~~~~~~~~~~~~~~~~~~~~
+
+The first WinGet PR for a new package ID must be created manually.
+For ``vumark``, do this after the first release that contains
+``vumark-windows.exe``, then automation can be added for subsequent releases.
+This is tracked in `issue #1984 <https://github.com/VWS-Python/vws-cli/issues/1984>`_.

pyproject.toml

@@ -82,7 +82,7 @@ optional-dependencies.dev = [
     "ty==0.0.18",
     "types-pyyaml==6.0.12.20250915",
     "vulture==2.14",
-    "vws-python-mock==2026.2.18.2",
+    "vws-python-mock==2026.2.21",
     "vws-test-fixtures==2023.3.5",
     "yamlfix==1.19.1",
     "zizmor==1.22.0",
@@ -94,6 +94,7 @@ optional-dependencies.release = [
 urls.Documentation = "https://vws-python.github.io/vws-cli/"
 urls.Source = "https://github.com/VWS-Python/vws-cli"
 scripts.vuforia-cloud-reco = "vws_cli.query:vuforia_cloud_reco"
+scripts.vumark = "vws_cli.vumark:generate_vumark"
 scripts.vws = "vws_cli:vws_group"
 
 [tool.setuptools]

spelling_private_dict.txt

@@ -20,6 +20,8 @@ macOS
 metadata
 noqa
 num
+pdf
+png
 pragma
 pre
 pyperclip
@@ -31,10 +33,12 @@ reportMissingTypeStubs
 reportUnknownArgumentType
 reportUnknownMemberType
 reportUnknownVariableType
+svg
 typeshed
 ubuntu
 versioned
 vuforia
+vumark
 vwq
 vws
 winget

src/vws_cli/commands.py

@@ -4,7 +4,7 @@
 import dataclasses
 import io
 import sys
-from collections.abc import Callable, Iterator, Mapping
+from collections.abc import Iterator, Mapping
 from pathlib import Path
 
 import click
@@ -52,6 +52,7 @@
     connection_timeout_seconds_option,
     read_timeout_seconds_option,
 )
+from vws_cli.options.vws import base_vws_url_option
 
 
 @beartype
@@ -116,25 +117,11 @@ def _handle_vws_exceptions() -> Iterator[None]:
     sys.exit(1)
 
 
-@beartype
-def _base_vws_url_option(command: Callable[..., None]) -> Callable[..., None]:
-    """An option decorator for choosing the base VWS URL."""
-    click_option_function = click.option(
-        "--base-vws-url",
-        type=click.STRING,
-        default="https://vws.vuforia.com",
-        help="The base URL for the VWS API.",
-        show_default=True,
-    )
-
-    return click_option_function(command)
-
-
 @click.command(name="get-target-record")
 @server_access_key_option
 @server_secret_key_option
 @target_id_option
-@_base_vws_url_option
+@base_vws_url_option
 @connection_timeout_seconds_option
 @read_timeout_seconds_option
 @_handle_vws_exceptions()
@@ -173,7 +160,7 @@ def get_target_record(
 @server_access_key_option
 @server_secret_key_option
 @_handle_vws_exceptions()
-@_base_vws_url_option
+@base_vws_url_option
 @connection_timeout_seconds_option
 @read_timeout_seconds_option
 @beartype
@@ -210,7 +197,7 @@ def list_targets(
 @server_secret_key_option
 @target_id_option
 @_handle_vws_exceptions()
-@_base_vws_url_option
+@base_vws_url_option
 @connection_timeout_seconds_option
 @read_timeout_seconds_option
 @beartype
@@ -248,7 +235,7 @@ def get_duplicate_targets(
 @server_access_key_option
 @server_secret_key_option
 @_handle_vws_exceptions()
-@_base_vws_url_option
+@base_vws_url_option
 @connection_timeout_seconds_option
 @read_timeout_seconds_option
 @beartype
@@ -285,7 +272,7 @@ def get_database_summary_report(
 @server_secret_key_option
 @target_id_option
 @_handle_vws_exceptions()
-@_base_vws_url_option
+@base_vws_url_option
 @connection_timeout_seconds_option
 @read_timeout_seconds_option
 @beartype
@@ -326,7 +313,7 @@ def get_target_summary_report(
 @server_secret_key_option
 @target_id_option
 @_handle_vws_exceptions()
-@_base_vws_url_option
+@base_vws_url_option
 @connection_timeout_seconds_option
 @read_timeout_seconds_option
 @beartype
@@ -367,7 +354,7 @@ def delete_target(
 @target_image_option(required=True)
 @active_flag_option(allow_none=False)
 @_handle_vws_exceptions()
-@_base_vws_url_option
+@base_vws_url_option
 @connection_timeout_seconds_option
 @read_timeout_seconds_option
 @beartype
@@ -429,7 +416,7 @@ def add_target(
 @active_flag_option(allow_none=True)
 @target_id_option
 @_handle_vws_exceptions()
-@_base_vws_url_option
+@base_vws_url_option
 @connection_timeout_seconds_option
 @read_timeout_seconds_option
 @beartype
@@ -518,7 +505,7 @@ def update_target(
 @server_access_key_option
 @server_secret_key_option
 @target_id_option
-@_base_vws_url_option
+@base_vws_url_option
 @connection_timeout_seconds_option
 @read_timeout_seconds_option
 @_handle_vws_exceptions()

src/vws_cli/options/vws.py

@@ -0,0 +1,21 @@
+"""``click`` options for VWS API options."""
+
+from collections.abc import Callable
+from typing import Any
+
+import click
+from beartype import beartype
+
+
+@beartype
+def base_vws_url_option(
+    command: Callable[..., Any],
+) -> Callable[..., Any]:
+    """An option decorator for choosing the base VWS URL."""
+    return click.option(
+        "--base-vws-url",
+        type=click.STRING,
+        default="https://vws.vuforia.com",
+        help="The base URL for the VWS API.",
+        show_default=True,
+    )(command)