Metadata-Version: 2.4
Name: virtualitics-cli
Version: 2.0.0
Summary: A command line interface for initializing, packaging, and deploying Custom Apps to the Virtualitics AI Platform from a local development environment.
Author-email: Virtualitics Engineering <engineering@virtualitics.com>
License: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.14
Requires-Dist: art>=6.1
Requires-Dist: build>=1.2.1
Requires-Dist: requests>=2.31.0
Requires-Dist: typer>=0.19.2
Provides-Extra: dev
Requires-Dist: ruff>=0.9.0; extra == 'dev'
Provides-Extra: optional
Requires-Dist: virtualitics-sdk>=1.26.0; extra == 'optional'
Provides-Extra: test
Requires-Dist: pip-audit>=2.7.0; extra == 'test'
Requires-Dist: pytest-cov>=5.0.0; extra == 'test'
Requires-Dist: pytest>=8.1.1; extra == 'test'
Description-Content-Type: text/markdown

# 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

```console
pip install virtualitics-cli
```

Requires Python >= 3.14.

## Quick Start

```console
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](https://peps.python.org/pep-0440/) 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

```console
$ 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.

```console
$ 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.

```console
$ vaip use-context CONTEXT_NAME
```

### `vaip show-context`

Display the current configuration file.

```console
$ vaip show-context
```

### `vaip delete-context`

Delete a specific context from the configuration file.

```console
$ vaip delete-context CONTEXT_NAME
```

### `vaip edit-context`

Modify a specific context in the configuration file.

```console
$ 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.

```console
$ 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.

```console
$ vaip validate
```

### `vaip status`

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

```console
$ vaip status
```

### `vaip build`

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

```console
$ vaip build
```

### `vaip deploy`

Deploy the VAIP App wheel to the configured VAIP instance.

```console
$ 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.

```console
$ 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.)*

```console
$ 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)
