Search archived VSS video

When to Use

• Search archived VSS video that is already registered in a configured deployment, by natural-language, similarity, attribute, object-ID, or lexical tag query.

Not for:

• A fresh visual question about a supplied local clip, vss-ask-video.
• Long-form summarization of a recording, vss-summarize-video.
• Deploying or changing a profile, /vss-build-vision-ai.
• Ingesting or deleting a source, use the deployment's source-management workflow.

Answer from the configured deployment through the installed vss CLI. Do not fall back to raw REST when a CLI command fails.

Hard rule, use the vss CLI for retrieval. vss configure has already pointed the CLI at the deployment, so every search action goes through vss search run and nothing reaches the deployment any other way.

Four things follow:

• use the vss on PATH (see Prerequisites); never docker exec, kubectl exec, a pod shell, or a hand-built /api/v1/search call;
• a named source is resolved with vss vios list before search, never inferred from a display name, and never substituted when missing;
• capture stdout and the exit status separately, never put the command behind if !, which hides the real exit code, and never discard usable exit-6 results;
• a failing command is a finding: report the exit code rather than routing around it, repairing the deployment, or retrying with broadened scope.

Prerequisites

• A running VSS search profile with vss configure already run against its origin. Refresh configuration after first ingestion, once source provisioning has established readiness; lazy raw indexes enable frame enrichment for attribute/fusion.
• The vss CLI on PATH. The OpenClaw and Hermes harness images ship it; anywhere else, install it from the same checkout as this skill so the CLI and the skill match: uv tool install <checkout>/libs/vss/cli.