virtualitics-cli 2.0.1

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
• Bundled Claude Code skill (2.0.1+) — Run vaip skill install to give Claude Code the ability to drive vaip for you

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

vaip skill install

Install the bundled Claude Code skill so an AI agent (e.g. Claude Code) can drive vaip end-to-end via a structured contract. The skill ships with the wheel and gets copied to ~/.claude/skills/vaip/SKILL.md on install.

$ vaip skill install [OPTIONS]

• -d, --dest PATH: Override install path (defaults to ~/.claude/skills/vaip/SKILL.md)
• -f, --force: Overwrite an existing SKILL.md if present

Once installed, Claude Code's Skill tool sees the vaip skill and can scaffold, validate, build, deploy, and manage VAIP apps using the canonical --json envelope and granular exit codes.

---

Changelog

Unreleased

CI/CD

• Replace weekly cron with manual rollover, add GH App token + auto release notes (#23)
  • Drop cron schedule; manual workflow_dispatch only (releases are infrequent)
  • Drop publish-outgoing job; PyPI publish stays separate via build-and-publish.yml
  • Add actions/create-github-app-token@v2 for default-branch flip perms
  • Add gh release create --generate-notes --latest for outgoing version
  • Make tag/release/branch creation idempotent for safe re-runs
  • Rename file weekly-rollover.yml -> release-rollover.yml since cron is gone

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)