Metadata-Version: 2.4
Name: virtualitics-cli
Version: 2.0.1
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
- **Bundled Claude Code skill** (2.0.1+) — Run `vaip skill install` to give Claude Code the ability to drive `vaip` for you

## 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
```

### `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.

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