virtualitics-cli 2.0.0

A command line interface for initializing, packaging, and deploying Custom Apps to the Virtualitics AI Platform from a local development environment.

Virtualitics AI Platform CLI

A command line interface for initializing, packaging, and deploying Custom Apps to the Virtualitics AI Platform (VAIP) from a local development environment.

Installation

pip install virtualitics-cli

Requires Python >= 3.14.

Quick Start

vaip config                          # Configure connection to a VAIP instance
vaip init -n my_app -d "My app" -y   # Scaffold a new VAIP app
cd my_app
vaip build                           # Build a wheel
vaip deploy                          # Deploy to the VAIP instance

Versioning

This project follows PEP 440 and is versioned independently from the Virtualitics AI Platform. Patch versions are released weekly (e.g., 2.0.0 → 2.0.1 → 2.0.2). Minor and major versions are bumped for feature releases and breaking changes respectively.

Compatible with VAIP 1.60+.

What's New in 2.0

• Redesigned vaip init — Scaffolds a working two-step app (CSV upload → results dashboard with table and chart), ready to build and deploy immediately
• New vaip validate command — Pre-flight checks for pyproject.toml, package structure, Python syntax, and App/Flow definitions before building
• Structured JSON output — Global --json flag on all commands for scripting and CI/CD integration
• Fully non-interactive vaip config — Provide all flags (-N, -H, -T, -U) to skip prompts; use --yes to accept stored defaults
• Independent versioning — CLI versions are no longer coupled to VAIP platform versions
• Weekly automated releases with dependency updates and changelog generation

Usage

$ vaip [OPTIONS] COMMAND [ARGS]...

Options:

• --version
• --verbose / --no-verbose: [default: no-verbose]
• --json: Emit JSON output for programmatic/agent consumption
• --install-completion: Install completion for the current shell.
• --show-completion: Show completion for the current shell, to copy it or customize the installation.
• --help: Show this message and exit.

Commands

vaip config

Create or update a configuration file for connecting to a VAIP instance. Requires a friendly name, host URL, API token, and username. Supports multiple named contexts.

$ vaip config [OPTIONS]

• -N, --name TEXT: Friendly name for the VAIP instance (e.g., predict-dev) [required]
• -H, --host TEXT: Backend hostname (e.g., https://predict-api-dev.virtualitics.com) [required]
• -T, --token TEXT: API token for authentication
• -U, --username TEXT: Username associated with API token
• -y, --yes: Accept default token/username without prompting

vaip use-context

Switch the active context for deployment.

$ vaip use-context CONTEXT_NAME

vaip show-context

Display the current configuration file.

$ vaip show-context

vaip delete-context

Delete a specific context from the configuration file.

$ vaip delete-context CONTEXT_NAME

vaip edit-context

Modify a specific context in the configuration file.

$ vaip edit-context CONTEXT_NAME

vaip init

Scaffold a new VAIP app with a working two-step example (CSV upload + results dashboard). All parameters can be provided as flags for fully non-interactive usage.

$ vaip init [OPTIONS]

• -n, --project-name TEXT: Project name, snake_case only [required, prompted if omitted]
• -d, --description TEXT: App description [required, prompted if omitted]
• -v, --version TEXT: App version [default: 0.1.0]
• -a, --authors TEXT: Author name [default: git user.name]
• -y, --yes: Skip confirmation prompt

vaip validate

Validate a VAIP app project before building. Checks pyproject.toml, package structure, Python syntax, and App/Flow definition.

$ vaip validate

vaip status

Check connection to the configured VAIP instance and list installed modules.

$ vaip status

vaip build

Build a Python wheel file from the pyproject.toml in the current directory.

$ vaip build

vaip deploy

Deploy the VAIP App wheel to the configured VAIP instance.

$ vaip deploy [OPTIONS]

• -f, --file TEXT: Path to the wheel file (defaults to ./dist/*.whl)

vaip destroy

Delete a VAIP module and all its apps from the instance.

$ vaip destroy [OPTIONS]

• -n, --project-name TEXT: Project name to delete [required]
• -y, --yes: Confirm deletion [required]

vaip publish

Publish a VAIP App to other users in your organization. (Not currently implemented.)

$ vaip publish

---

Changelog

Unreleased

Features

• Add vaip validate command, make config non-interactive, fix template
  • Add vaip validate pre-flight check: pyproject.toml, package structure, Python syntax, and App/Flow definition with --json support
  • Make vaip config fully non-interactive when -N/-H/-T/-U all provided
  • Add --yes/-y flag to config to accept stored defaults without prompting
  • Extract _resolve_credentials() to reduce config complexity
  • Error cleanly in --json mode instead of hanging on stdin prompts
  • Fix generated README template referencing removed --yes build flag
  • 17 new tests (95 total), coverage at 94%
• Auto-generate changelog for PyPI from git history
  • Add scripts/generate_changelog.py that extracts commits between tags, filters internal references (Jira tickets, internal URLs, emails), and groups by conventional commit type
  • Weekly rollover generates CHANGELOG.md and commits it
  • Build workflow appends changelog to PyPI readme before packaging
  • Update README_PYPI.md for 2.0 changes (new init flags, no build confirmation, --json flag)
• Add --json flag, remove build confirmation, fix exit codes
  • Global --json flag emits structured JSON for agent/programmatic use
  • Remove unnecessary confirmation prompt from build command
  • Standardize exit codes: explicit code=0 on success, code=1 on error
  • Extract _error_exit() and _resolve_wheel() helpers to reduce complexity
  • Update tests for new behavior and add JSON output tests
• Replace init with template-based scaffold Generates a working two-step VAIP app (CSV upload + results dashboard). All inputs available as CLI flags for non-interactive/agentic usage. Templates loaded via importlib.resources from bundled .template files.
• Add basic_app scaffold templates Six template files for generating a working two-step VAIP app with CSV upload and results visualization.

Fixes

• Upgrade pygments and requests to resolve CVEs
  • pygments 2.19.2 → 2.20.0 (-4539)
  • requests 2.32.5 → 2.33.1 (-25645)
• Isolate flaky test_use_context_no_config_file from filesystem state The test relied on real filesystem state, causing it to pass locally (where a config file exists) but fail on CI (where none exists).
• Escape special characters in template variable substitution Prevents broken Python/TOML syntax when description or authors contain double quotes or backslashes.
• Suppress S607 lint warning for git subprocess call
• Isolate test_config_w_input from filesystem state The test relied on real filesystem state and failed when a config file already existed with a 'predict-dev' context. Uses tmp_path/monkeypatch for isolation, matching the pattern of the other config tests.

Documentation

• Update What's New in 2.0 and sync README command docs Expand release notes to cover scaffold redesign, validate command, JSON output, and non-interactive config. Update stale init/build docs in internal README to match current CLI behavior.
• Add versioning and what's new sections to READMEs Documents the independent versioning scheme (PEP 440, weekly patch releases) and VAIP 1.60+ compatibility.

Tests

• Replace init tests for new scaffold behavior Tests cover file generation, variable substitution, non-interactive mode, defaults, existing directory handling, and Python syntax validity.

Build

• Include template files in wheel distribution

CI/CD

• Add weekly rollover workflow Runs Monday 06:00 UTC. Publishes the outgoing release to PyPI, creates a new patch release branch, bumps the version in pyproject.toml, updates dependencies via uv lock --upgrade, and retargets open PRs.
• Add workflow_call trigger with auto_publish support Allows the weekly rollover workflow to call build-and-publish with auto_publish=true, bypassing the manual approval gate for automated weekly releases.

Maintenance

• Bump version to 2.0.0 and add production classifier Decouples CLI versioning from VAIP platform versions. The CLI now follows its own PEP 440 versioning with weekly patch releases.

1.54.1

Other

• Handle HTTP timeouts and non-JSON responses gracefully (#21)
  • Catch requests.exceptions.Timeout in deploy, destroy, and publish with a helpful message suggesting the operation may still be processing
  • Add print_response() helper that gracefully handles non-JSON server responses (HTML error pages, plain text) instead of crashing
  • Check r.ok for xx status codes before attempting to parse response
  • Add error handling to publish (previously had no try/except at all)
  • Add 7 new tests: deploy timeout, deploy server error, deploy non-JSON success, destroy timeout, publish timeout, publish connection error, publish server error
• Remove stale TODOs, auto-convert hyphens in destroy, improve 404 message (#20)
  • Remove 8 stale TODO comments (pipx, blueprint docs, setuptools-scm, vaip-init detection, authors list)
  • Auto-convert hyphens to underscores in destroy project_name so users can copy the name directly from pyproject.toml
  • Improve destroy 404 error to mention the project name may not exist
  • Add test for hyphen-to-underscore conversion
• [SECURITY] - Update dependencies to resolve CVEs. (#17)
• Update version to 1.38.0

1.37.0

Other

• Update deps (#16)