topazlabscli

topazlabscli is an npm-distributed CLI and portable Agent Skill for sending video-enhancement jobs to an authorized Windows workstation running Topaz Video AI. It uses the workstation's existing SSH service, Topaz installation, GPU, models, and license. Nothing in this package installs, redistributes, licenses, or unlocks Topaz software.

Requirements

• Client: Node.js 20+, OpenSSH ssh and sftp.
• Worker: Windows, OpenSSH Server, Topaz Video AI with its bundled FFmpeg/FFprobe, a logged-in licensed user, and downloaded model files.
• Network access is configured separately. Each endpoint is ordinary user configuration; the package does not contain or manage VPN settings.

Install

npm install --global @petercjl/topazlabscli
topazlabscli skill install --agent all

The CLI checks npm for a newer stable release before operational commands, at most once every six hours. It first uses the registry already configured for npm and automatically tries https://registry.npmmirror.com/ if that registry is unavailable. The successful registry is used to download the exact discovered version as a complete tarball before the installed version is touched, without changing the user's .npmrc. When an update is available the CLI upgrades itself from that local tarball, refreshes installed Agent Skills, and then resumes the original command. It discovers npm through the running Node installation, preserves SealSeek's managed global prefix/cache, and discovers Windows OpenSSH through the standard system location, so it also works in Agent runtimes with a restricted PATH. A temporary registry outage does not block video processing. topazlabscli update forces an immediate manual update.

On Windows, SealSeek Skills are installed into %USERPROFILE%\.sealseek\workspace\skills when that workspace is present. The CLI automatically uses a managed copy because SealSeek rejects junctions that resolve outside the workspace Skill root; subsequent CLI updates refresh the copy from the npm package. The copy includes a local runtime manifest so the Agent can invoke the canonical package even when its PATH is restricted. SEALSEEK_SKILLS_HOME remains available as an explicit override.

Configure a target

Use one or more SSH endpoints in priority order. A LAN-only user configures only the LAN entry.

topazlabscli target add gpu-workstation `
  --endpoint lan=gpu-workstation `
  --user Administrator `
  --identity "$HOME\.ssh\gpu_workstation_ed25519" `
  --workspace "E:\topazlab_workspace" `
  --default

An authorized roaming user can add a second endpoint that resolves through their own VPN configuration:

topazlabscli target add gpu-workstation `
  --endpoint lan=gpu-workstation `
  --endpoint vpn=gpu-workstation-vpn `
  --user Administrator `
  --identity "$HOME\.ssh\gpu_workstation_ed25519" `
  --workspace "E:\topazlab_workspace" `
  --default

The CLI tries endpoints in the order provided. It never starts or changes a VPN.

Set up and check the worker

topazlabscli connection check --json
topazlabscli worker install --json
topazlabscli doctor --json
topazlabscli model status --json

The CLI automatically upgrades the remote worker when the bundled worker version changes. process and job wait keep the queue runner attached to the active SSH command, while a global mutex and one queue consumer serialize jobs from multiple clients. This avoids Windows Agent runtimes terminating a detached SSH child. An abandoned running record is converted to a terminal WORKER_LOST failure instead of waiting forever.

Process a video

topazlabscli process .\input.mp4 --json

Without --output, the CLI writes input-topaz-1080p.mp4 beside the source video. 1080p remains the default. Request an aspect-preserving QHD/2K output with a 1440-pixel short edge using:

topazlabscli process .\input.mp4 --resolution 2k --json

The default 2K output name is input-topaz-2k.mp4. Aliases 1440, 1440p, and qhd are also accepted. An explicit --output remains available for automation.

Asynchronous form:

topazlabscli job submit .\input.mp4 --resolution 2k --json
topazlabscli job status JOB_ID --json
topazlabscli job wait JOB_ID --json
topazlabscli job download JOB_ID --output .\output-1080p.mp4 --json

The default path includes two bounded presets: seedance-human-1080p and seedance-human-1440p (QHD/2K). Both use Proteus v4 (prob-4), preserve source FPS and aspect ratio, and use NVIDIA H.264 encoding. Both also use the versioned proteus-auto-v1 tuning policy: Topaz estimates the six Proteus controls from a 20-frame window, the CLI adds no manual relative offsets, and 20% of the original detail is recovered. The resolved tuning policy is written into each job status for auditability.

Raw Proteus parameter injection is intentionally not exposed. New tuning profiles require representative A/B tests and a package release so Agents cannot invent unverified filter values.

The client reads MP4 track dimensions before upload so the worker does not depend on launching Topaz's bundled FFprobe through a remote shell.

Advanced tuning preview

Advanced tuning is an explicit, non-default branch. It uploads the source once, extracts three representative source ranges, renders the default Auto result and one bounded candidate, and returns source, candidate, side-by-side video, and contact-sheet evidence before the candidate is applied to the full video.

topazlabscli tuning profiles --json
topazlabscli tuning analyze .\input.mp4 --output-dir .\input-analysis --json
topazlabscli tuning preview ANALYSIS_ID --profile human-balanced --output-dir .\input-preview --json
topazlabscli tuning apply ANALYSIS_ID --profile human-balanced --output .\input-topaz-advanced.mp4 --json

The packaged proteus-advanced-v1 catalog currently provides human-balanced, compression-repair, motion-safe, and soft-source. Each remains relative to Proteus Auto and is restricted to narrower package safety bounds than the native Topaz range. The worker rejects unknown profiles and the CLI never accepts raw Proteus values. The preview comparison is ordered source, default Auto, then candidate from left to right.

Configuration

Configuration is stored outside the package:

• Windows: %APPDATA%\topazlabscli\config.json
• macOS/Linux: ${XDG_CONFIG_HOME:-~/.config}/topazlabscli/config.json
• Override for testing or automation: TOPAZLABSCLI_CONFIG

Update registry selection is CLI-local. settings set update-registry <url> sets a preferred registry, and settings set update-registry auto restores automatic selection. TOPAZLABSCLI_UPDATE_REGISTRY can provide one or more comma-separated preferred registries for managed environments.

Do not publish configuration files, keys, internal addresses, media, Topaz model files, or authentication data.