vws-cli

A CLI for Vuforia Web Services.

Installation

With pip

Requires Python 3.14+.

$ pip install VWS-CLI

With Homebrew (macOS, Linux, WSL)

Requires Homebrew.

$ brew tap VWS-Python/vws
$ brew install vws-cli

With Nix

Requires Nix.

$ nix --extra-experimental-features 'nix-command flakes' develop "github:VWS-Python/vws-cli"

To avoid passing --extra-experimental-features every time, enable flakes permanently.

Or add to your flake inputs:

{
  inputs.vws-cli.url = "github:VWS-Python/vws-cli";
}

With Docker

$ docker run --rm "ghcr.io/vws-python/vws-cli" --help

To use vuforia-cloud-reco:

$ docker run --rm --entrypoint vuforia-cloud-reco "ghcr.io/vws-python/vws-cli" --help

To use vumark:

$ docker run --rm --entrypoint vumark "ghcr.io/vws-python/vws-cli" --help

With winget (Windows)

Requires winget.

$ winget install --id VWSPython.vws-cli --source winget --exact
$ winget install --id VWSPython.vuforia-cloud-reco --source winget --exact

Pre-built Linux (x86) binaries

$ curl --fail -L "https://github.com/VWS-Python/vws-cli/releases/download/2026.02.23/vws-linux" -o /usr/local/bin/vws &&
    chmod +x /usr/local/bin/vws
$ curl --fail -L "https://github.com/VWS-Python/vws-cli/releases/download/2026.02.23/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/VWS-Python/vws-cli/releases/download/2026.02.23/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

Pre-built macOS (ARM) binaries

$ curl --fail -L "https://github.com/VWS-Python/vws-cli/releases/download/2026.02.23/vws-macos" -o /usr/local/bin/vws &&
    chmod +x /usr/local/bin/vws
$ curl --fail -L "https://github.com/VWS-Python/vws-cli/releases/download/2026.02.23/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/VWS-Python/vws-cli/releases/download/2026.02.23/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:

$ 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

Use <TAB> to complete commands and options.

$ vws get-`TAB`
get-database-summary-report        (Get a database summary report.)
get-duplicate-targets  (Get a list of potential duplicate targets.)
get-target-record                            (Get a target record.)
get-target-summary-report            (Get a target summary report.)

Add this to ~/.bashrc:

$ eval "$(_VWS_COMPLETE=bash_source vws)"

Add this to ~/.zshrc:

$ eval "$(_VWS_COMPLETE=zsh_source vws)"

Run the following command:

$ _VWS_COMPLETE=fish_source vws > ~/.config/fish/completions/vws.fish

After modifying the shell configuration files, you need to start a new shell in order for the changes to be loaded.

Usage example

$ vws add-target \
    --server-access-key "$SERVER_ACCESS_KEY" \
    --server-secret-key "$SERVER_SECRET_KEY" \
    --name my_image_name \
    --width 2 \
    --image ~/Documents/my_image.png \
    --application-metadata "$(echo 'my_metadata' | base64)" \
    --active-flag true
03b99df0-78cf-4b01-b929-f1860d4f8ed1
$ vws --help
...
$ vuforia-cloud-reco my_image.jpg \
    --max-num-results 5 \
    --include-target-data none
- target_id: b60f60121d37418eb1de123c381b2af9
- target_id: e3a6e1a216ad4df3aaae1f6dd309c800
$

Model Target datasets

Model Target dataset commands use OAuth2 credentials for the Model Target Web API, rather than server keys. Vuforia generates a dataset in the background, so create the dataset, wait for it, and then download it.

$ vws create-model-target-dataset \
    --client-id "$MODEL_TARGET_CLIENT_ID" \
    --client-secret "$MODEL_TARGET_CLIENT_SECRET" \
    --name my_dataset_name \
    --target-sdk 10.29 \
    --model-name my_model_name \
    --cad-data-file ~/Documents/my_model.obj \
    --cad-data-format obj
1f0f2b7c1f0f4b0a9a1c4b6b0a5b0f2b
$ vws wait-for-model-target-dataset-generated \
    --client-id "$MODEL_TARGET_CLIENT_ID" \
    --client-secret "$MODEL_TARGET_CLIENT_SECRET" \
    --dataset-uuid 1f0f2b7c1f0f4b0a9a1c4b6b0a5b0f2b
completed_at: '2026-08-14 12:00:00+00:00'
created_at: '2026-08-14 11:59:00+00:00'
dataset_uuid: 1f0f2b7c1f0f4b0a9a1c4b6b0a5b0f2b
error: null
eta: null
status: done
warning: null
$ vws download-model-target-dataset \
    --client-id "$MODEL_TARGET_CLIENT_ID" \
    --client-secret "$MODEL_TARGET_CLIENT_SECRET" \
    --dataset-uuid 1f0f2b7c1f0f4b0a9a1c4b6b0a5b0f2b \
    --output ~/Documents/my_dataset.zip
$ vws delete-model-target-dataset \
    --client-id "$MODEL_TARGET_CLIENT_ID" \
    --client-secret "$MODEL_TARGET_CLIENT_SECRET" \
    --dataset-uuid 1f0f2b7c1f0f4b0a9a1c4b6b0a5b0f2b
$

Use --dataset-type advanced with each of these commands for an advanced dataset. To give more than one model, or to give guide views, describe the models in a JSON file and give it with --models-file:

{
  "models": [
    {
      "name": "my_model_name",
      "cadDataUrl": "https://example.com/my_model.zip",
      "cadDataFormat": "OBJ",
      "views": [
        {
          "name": "front",
          "guideViewPosition": {
            "rotation": [0, 0, 0, 1],
            "translation": [0, 0, -1.5]
          }
        }
      ]
    }
  ]
}

Reference