vHaaS CLI

The vHaaS command line tool lets you interact with the vHaaS platform directly from your shell or Python scripts — for session booking in CI/CD pipelines, administrative tasks, and full API access.

---

Installation

Coming Soon

The vhaas pip package is not yet publicly available on PyPI. Installation instructions will be updated here once the package is released.

pip install vhaas   # coming soon

Once available, verify the installation with:

vhaas --version

---

Syntax

vhaas <command> <subcommand> [options]

1. vhaas — invocation of the CLI
2. <command> — top-level command: a use-case workflow or an API version (v3, v2)
3. <subcommand> — resource type and action, can be nested
4. [options] — flags with - or --

---

Environment Variables

Set these once to avoid passing --host and --token on every command:

Variable	Default	Description
VHAAS_HOST	https://vhaas.vector.cloud/	Base URL of the vHaaS API.
VHAAS_TOKEN	—	Access token for authentication. See Access Tokens.

---

Commands

Commands are divided into two categories:

• Use-case commands — high-level workflow helpers (session booking, maintenance scheduling)
• API commands — full API access, auto-generated from the OpenAPI spec, grouped by version (v3, v2)

---

Session Commands

The primary commands for CI/CD workflows: booking and releasing assembly sessions.

Top-level command overview

Usage: vhaas [OPTIONS] COMMAND [ARGS]...

  Command line tool to interact with the vHaaS API.

Options:
  --version   Show the version and exit.
  -h, --help  Show this message and exit.

Commands:
  book-maintenance        Book a maintenance window over a fixed schedule.
  create-session-request  Create a session request and wait for booking confirmation.
  delete-maintenance      Delete a (recurring) maintenance window.
  maintenance             Maintenance related commands.
  release-session         Release an assembly session as soon as possible.
  v3                      API v3 commands.
  v2                      API v2 commands (legacy).

create-session-request

Creates a new session request and waits until the session is either successfully booked or the request times out.

create-session-request

vhaas create-session-request --duration 30 --assembly-ref "ASSEMBLY-0"

Options

Option	Default	Description
--duration	—	Duration of the session in minutes.
--timeout	10	Timeout for the session request in minutes.
--assembly-ref	—	Assembly reference. Can be specified multiple times to check multiple assemblies.
--request-profile	—	Assembly profile JSON. If set, all other request profile options are ignored.
--provider-url	—	URL of the GitLab runner provider. If set, the GitLab runner is enabled.
--virtual-machine-label	—	Label of the virtual machine.
--host	https://vhaas.vector.cloud/	API host URL. Uses $VHAAS_HOST if set.
--token	—	API access token. Uses $VHAAS_TOKEN if set.

release-session

Releases an assembly session as soon as possible. The required cleanup duration is calculated automatically.

release-session

vhaas release-session --session-id "27c21e35-bded-49bd-89a1-8e792942601c"

Options

Option	Default	Description
--session-id	—	ID of the session to release.
--host	https://vhaas.vector.cloud/	API host URL. Uses $VHAAS_HOST if set.
--token	—	API access token. Uses $VHAAS_TOKEN if set.

---

Maintenance Commands

Commands for booking and managing recurring maintenance windows.

book-maintenance

Book a maintenance window on a fixed schedule.

book-maintenance

vhaas book-maintenance \
  --start-date "2025-02-17" \
  --start-time "10:00" \
  --duration 30 \
  --end-recurrent-date "2025-02-20" \
  --description "important maintenance" \
  --assembly-ref "ASSEMBLY-0" \
  --interval "daily"

Options

Option	Default	Description
--start-date	—	Start date (YYYY-MM-DD).
--start-time	—	Time of the maintenance (HH:MM).
--duration	—	Duration in minutes.
--end-recurrent-date	—	Optional end date for recurrence (YYYY-MM-DD).
--description	—	Description of the maintenance.
--assembly-ref	—	Assembly reference. Defaults to all assemblies.
--interval	—	Interval type: daily, weekly, monthly, one-time.
--skip	—	Number of intervals to skip.
--host	https://vhaas.vector.cloud/	API host URL. Uses $VHAAS_HOST if set.
--token	—	API access token. Uses $VHAAS_TOKEN if set.

delete-maintenance

Delete a (recurring) maintenance window by its context grouping ID.

delete-maintenance

vhaas delete-maintenance --context-grouping-id "3b81efc4cdda4b02bf9d49482c62fd30"

Options

Option	Default	Description
--context-grouping-id	—	The context grouping ID to delete (found in the context description).
--host	https://vhaas.vector.cloud/	API host URL. Uses $VHAAS_HOST if set.
--token	—	API access token. Uses $VHAAS_TOKEN if set.

maintenance create-vm

Creates a VM and assigns a technical user from Vault.

maintenance create-vm

vhaas maintenance create-vm \
  --vault-token $VAULT_TOKEN \
  --vm-hostname "my-hil-host.example.com" \
  --cluster-ref "CLUSTER-1"

Options

Option	Default	Description
--vault-addr	https://vault.example.com	Address of the Vault instance.
--vault-token	—	Token for the Vault instance.
--vault-mount	—	Vault mount point.
--vault-path	—	Path to the Vault secret.
--vault-path-pattern	—	Vault path pattern to select a random secret.
--vm-hostname	—	Hostname of the new VM.
--vm-labels	—	List of labels for the new VM (optional).
--vm-properties	—	Dictionary in JSON format (optional).
--cluster-ref	—	Reference to an existing cluster.
--verbose-secrets	—	Show password in plain text.
--host	https://vhaas.vector.cloud/	API host URL. Uses $VHAAS_HOST if set.
--token	—	API access token. Uses $VHAAS_TOKEN if set.

---

API Commands (v3)

The v3 subcommand exposes all API v3 endpoints as CLI commands, generated from the OpenAPI spec. Resources are organized under their organization context.

Get help

vhaas v3 --help

v3 resource groups

Usage: vhaas v3 [OPTIONS] COMMAND [ARGS]...

  API v3 commands.

Options:
  -h, --help  Show this message and exit.

Commands:
  announcement-banners       Announcement banner commands.
  assembly-session-contexts  Assembly session context commands.
  assembly-session-transfers Assembly session transfer commands.
  assembly-sessions          Assembly session commands.
  assemblies                 Assembly commands.
  banners                    Banner commands.
  clusters                   Cluster commands.
  groups                     Group commands.
  hardware                   Hardware catalog commands.
  jobs                       Job commands.
  metrics                    Metrics commands.
  organizations              Organization commands.
  self                       Current user commands.
  service-tokens             Service token commands.
  users                      User commands.
  virtual-machines           Virtual machine commands.

All v3 commands that operate on organization-scoped resources require --organization-id:

vhaas v3 assemblies get-assemblies --organization-id "ORG-UUID"
vhaas v3 assembly-sessions create-assembly-session \
  --organization-id "ORG-UUID" \
  --assembly-session-request '{"assembly_ref": "ASSEMBLY-0", "start_time": "...", "end_time": "..."}'

For interactive exploration, the full v3 API is available in the Swagger UI at: https://vhaas.vector.cloud/api/v3/docs

Examples

Get assemblies (v3)

get-assemblies

$ vhaas v3 assemblies get-assemblies --organization-id "ORG-UUID"

{
  "items": [
    {
      "assembly_ref": "ASSEMBLY-0",
      "assembly_name": "Spielwiese",
      "status_type": "available",
      "is_operational": true,
      "cluster_ref": "CLUSTER-1"
    }
  ],
  "total": 1,
  "page": 1,
  "size": 50
}

Book a session (v3)

create-assembly-session

$ vhaas v3 assembly-sessions create-assembly-session \
    --organization-id "ORG-UUID" \
    --assembly-session-request '{
      "assembly_ref": "ASSEMBLY-0",
      "start_time": "2026-07-01T08:00:00Z",
      "end_time": "2026-07-01T09:00:00Z"
    }'

---

API Commands (v2 — Legacy)

The v2 subcommand provides access to the legacy flat-structure API. Existing integrations using v2 continue to work.

vhaas v2 --help

v2 resource groups

Usage: vhaas v2 [OPTIONS] COMMAND [ARGS]...

  API v2 commands.

Options:
  -h, --help  Show this message and exit.

Commands:
  access-tokens                 API access-tokens commands.
  assemblies                    API assemblies commands.
  assembly-group-relationships  API assembly-group-relationships commands.
  assembly-session-contexts     API assembly-session-contexts commands.
  assembly-session-transfers    API assembly-session-transfers commands.
  assembly-sessions             API assembly-sessions commands.
  banners                       API banners commands.
  clusters                      API clusters commands.
  default                       API default commands.
  groups                        API groups commands.
  health                        API health commands.
  jobs                          API jobs commands.
  monitoring                    API monitoring commands.
  organizations                 API organizations commands.
  users                         API users commands.
  virtual-machines              API virtual-machines commands.

Example (v2)

get-assembly (v2)

$ vhaas v2 assemblies get-assembly --assembly-ref "ASSEMBLY-0"

{
  "assembly_ref": "ASSEMBLY-0",
  "assembly_profile": {
    "assembly_ref": "ASSEMBLY-0",
    "assembly_name": "Spielwiese",
    "cluster_ref": "dummy-cluster"
  },
  "status_type": "available",
  "is_operational": true
}

---

Python Usage

The vhaas package can also be imported directly in Python scripts. The following example uses the v3 API client to book and inspect an assembly session.

Python — session booking with v3 client

import json
import os
from datetime import datetime, timedelta, timezone

from pydantic.json import pydantic_encoder
from vhaas.openapi_client_v3 import ApiClient, Configuration
from vhaas.openapi_client_v3.api import AssemblySessionsApi, AssembliesApi
from vhaas.openapi_client_v3.models import AssemblySessionRequest

VHAAS_URL = "https://vhaas.vector.cloud"  # no trailing slash
VHAAS_TOKEN = os.environ.get("VHAAS_TOKEN", "")
ORG_ID = os.environ.get("VHAAS_ORG_ID", "")


def main() -> None:
    config = Configuration(host=VHAAS_URL)
    client = ApiClient(configuration=config)
    client.default_headers["private-token"] = VHAAS_TOKEN

    sessions_api = AssemblySessionsApi(api_client=client)
    assemblies_api = AssembliesApi(api_client=client)

    # Book an assembly session
    start_time = datetime.now(timezone.utc)
    session = sessions_api.create_assembly_session(
        organization_id=ORG_ID,
        assembly_session_request=AssemblySessionRequest(
            assembly_ref="ASSEMBLY-101",
            start_time=start_time,
            end_time=start_time + timedelta(minutes=30),
        ),
    )
    print("Booked session:", json.dumps(session, indent=2, default=pydantic_encoder))

    # Get current status
    session_status = sessions_api.get_assembly_session(
        organization_id=ORG_ID,
        session_id=session.session_id,
    )
    print("Session status:", session_status.status_type)

    # Get assembly details
    assembly = assemblies_api.get_assembly(
        organization_id=ORG_ID,
        assembly_ref=session.assembly_ref,
    )
    print("Assembly:", json.dumps(assembly.assembly_profile, indent=2, default=pydantic_encoder))


if __name__ == "__main__":
    main()