Claude Code transcript - page 1/2

title:	Implement support for vultr
state:	OPEN
author:	dboreham
labels:	
comments:	0
assignees:	
projects:	
milestone:	
number:	46
--
Now that we have provider abstraction (https://github.com/stirlingbridge/machine/pull/45) it should be possible to begin work on implementing support for the Vultr hosting platform.

Perfect! Now I have a comprehensive understanding. Let me create a detailed summary document.

## Comprehensive Provider Abstraction Layer Analysis

I've completed a thorough exploration of the machine codebase. Here's the complete documentation you need to implement a Vultr provider:

### 1. PROVIDER INTERFACE/BASE CLASS

**File:** `/home/david/projects/stirlingbridge/machine/machine/provider.py`

The abstract base class `CloudProvider` defines the complete interface:

**Data Classes (shared between all providers):**
- `VM`: id, name, tags, region, ip_address, status
- `SSHKey`: id, name, fingerprint, public_key
- `DNSRecord`: id, name, type, data, ttl

**Required Abstract Methods:**
- `create_vm(name, region, image, size, ssh_key_name, tags, user_data) -> VM` - Create a VM and return its details
- `get_vm(vm_id) -> VM` - Get a single VM by ID
- `destroy_vm(vm_id) -> bool` - Delete a VM, return success
- `list_vms(tag=None) -> list` - List all VMs, optionally filtered by tag
- `get_ssh_key(name) -> SSHKey` - Get SSH key by name
- `list_ssh_keys() -> list` - List all SSH keys
- `create_dns_record(zone, record_type, name, data, ttl, tag=None) -> str` - Create DNS A/AAAA record
- `delete_dns_record(zone, record_name) -> bool` - Delete DNS record
- `get_dns_records(zone) -> list` - List DNS records in a zone
- `list_domains() -> list` - List all domains

**Optional Methods (with defaults provided):**
- `list_projects() -> list` - Returns empty list by default
- `assign_to_project(project_name, vm_id)` - No-op by default
- `validate_region(region)` - No-op by default
- `validate_image(image)` - No-op by default
- `provider_name` property - Returns class name by default (override for custom name)

---

### 2. DIGITALOCEAN PROVIDER IMPLEMENTATION

**File:** `/home/david/projects/stirlingbridge/machine/machine/providers/digitalocean.py`

**Key Implementation Details:**

**Initialization:**
- Takes `provider_config` dict from config.yml
- Requires `access-token` key, exits with fatal error if missing
- Creates `digitalocean.Manager` instance for API calls
- Provider config keys: `access-token`, `ssh-key`, `machine-size`, `image`, `region`, `dns-zone` (optional), `project` (optional)

**Region & Image Validation:**
- `VALID_REGIONS`: NYC1, NYC3, AMS3, SFO2, SFO3, SGP1, LON1, FRA1, TOR1, BLR1, SYD1
- `VALID_IMAGES`: AlmaLinux 8/9, CentOS Stream 9, Debian 11/12, Fedora 39/40, Rocky Linux 8/9, Ubuntu 20.04/22.04/24.04
- Validates region (exits on invalid)
- Warns on invalid image

**VM Creation Flow:**
1. Validates SSH key exists by name
2. Creates digitalocean.Droplet with provided params
3. Calls droplet.create()
4. Converts DO API response to VM dataclass via `_droplet_to_vm()`

**DNS Operations:**
- Creates digitalocean.Domain instances per zone
- Handles NotFoundError gracefully when zone doesn't exist
- Returns DNS records as list of DNSRecord objects

**Projects Support:**
- Fetches all projects, finds by name
- Calls `project.assign_resource([f"do:droplet:{vm_id}"])`
- Returns resource URIs in DigitalOcean format

**Helper Method:**
- `_get_do_ssh_key(name)` - Finds SSH key by name from all keys

---

### 3. PROVIDER SELECTION & CONFIGURATION FLOW

**File:** `/home/david/projects/stirlingbridge/machine/machine/config.py`

**Config Loading Sequence:**

1. **Auto-detection:**
   - Reads `~/.machine/config.yml` (or custom path via `--config-file`)
   - Looks for `provider:` key OR auto-detects from KNOWN_PROVIDERS sections in config
   - If multiple providers found, requires explicit `provider:` selection
   - If no providers found, fatal error listing available providers

2. **Provider Configuration:**
   - Extracts the provider section from YAML (e.g., `digital-ocean:`)
   - Passes entire section as dict to provider factory
   - Validates required keys: `ssh-key`, `machine-size`, `image`, `region`
   - Extracts optional keys: `dns-zone`, `project`

3. **Environment Variable Expansion:**
   - Pattern: `${VAR_NAME}` or `${VAR_NAME:-default}`
   - Expands in all config values recursively (strings, dicts, lists)
   - Fatal error on undefined vars without defaults

4. **Config Structure:**
   ```yaml
   provider: digital-ocean           # optional explicit selection
   digital-ocean:
     access-token: ${DO_TOKEN}       # required for DO
     ssh-key: my-key-name            # required
     machine-size: s-1vcpu-1gb       # required
     image: ubuntu-22-04-x64         # required
     region: nyc1                    # required
     dns-zone: example.com           # optional
     project: my-project             # optional
   machines:
     web-server:
       new-user-name: deployuser
       script-url: https://...
       script-dir: /opt/scripts
       script-path: /opt/scripts/init.sh
       script-args: "--flag=value"
   ```

---

### 4. PROVIDER INSTANTIATION

**File:** `/home/david/projects/stirlingbridge/machine/machine/providers/__init__.py`

**Registry Pattern:**
```python
KNOWN_PROVIDERS = ["digital-ocean"]  # List of provider names

def create_provider(provider_name, provider_config) -> CloudProvider:
    # Factory function that returns appropriate provider instance
    # Dispatches by provider_name
    # Exits with fatal error on unknown provider
```

**Call Chain:**
1. `main.py` calls `config.get(config_file)` → returns Config with provider_name
2. `main.py` calls `create_provider(cfg.provider_name, cfg.provider_config)`
3. Factory returns CloudProvider instance
4. Stored in MainCmdCtx and passed to all subcommands

---

### 5. FULL MACHINE PACKAGE STRUCTURE

```
machine/
├── main.py                      # CLI entry point, provider instantiation
├── config.py                    # Config loading & validation
├── types.py                     # Data classes (Config, CliOptions, MainCmdCtx, MachineConfig)
├── provider.py                  # Abstract CloudProvider class + data classes
├── di.py                        # Global state (CliOptions)
├── factory.py                   # YAML handling
├── cloud_config.py              # Cloud-init script generation
├── constants.py                 # Config paths
├── util.py                      # Utility functions (tags, session ID)
├── log.py                       # Logging helpers
├── defaults.py                  # (empty)
├── __init__.py                  # (empty)
├── providers/
│   ├── __init__.py              # Provider registry & factory
│   └── digitalocean.py          # DigitalOcean implementation
└── subcommands/
    ├── create.py                # VM creation
    ├── destroy.py               # VM deletion
    ├── list.py                  # List VMs with filtering
    ├── status.py                # Query VM status (cloud-init health)
    ├── ssh_keys.py              # List SSH keys
    ├── domains.py               # List DNS domains
    ├── list_domain.py           # List DNS records in domain
    ├── projects.py              # List projects (DO-specific)
    ├── types.py                 # List machine types from config
    └── __init__.py
```

---

### 6. KEY DESIGN PATTERNS

**Dependency Injection:**
- Simple pattern: `MainCmdCtx` passed via Click context
- Contains: Config, session_id, provider instance
- All subcommands receive via `@click.pass_context`

**Tag System:**
- All VMs tagged with creation metadata
- `machine:created` - marker for machine-created VMs
- `machine:type:{type}` - machine type from config
- `machine:session:{session_id}` - session ID for grouping
- Custom tags from `--tag` flag

**Session ID:**
- Generated once, stored in `~/.machine/session-id.yml`
- Used to prevent destroying VMs from other sessions
- 8-character random ID

**Provider API Contract:**
- All methods return provider-agnostic types (VM, SSHKey, DNSRecord)
- Provider responsible for adapter logic
- Graceful error handling (e.g., DNS zone not found logs warning, continues)

---

### 7. HOW SUBCOMMANDS USE PROVIDERS

Each subcommand pattern:
1. Extract provider from context: `provider = command_context.provider`
2. Call provider methods (e.g., `provider.create_vm()`, `provider.list_vms()`)
3. Provider returns standard types (VM, SSHKey, etc.)
4. Format/display results

**Example from create.py:**
- Validates config & SSH key
- Generates cloud-init script using `cloud_config.py`
- Calls `provider.create_vm()` with tags, user_data
- If DNS enabled, calls `provider.create_dns_record()`
- If project specified, calls `provider.assign_to_project()`

---

### 8. DEPENDENCIES & BUILD

**File:** `/home/david/projects/stirlingbridge/machine/pyproject.toml`

**Runtime Dependencies:**
- click 8.1.7 (CLI framework)
- python-digitalocean 1.17.0 (DigitalOcean API)
- ruamel.yaml >=0.17.32 (YAML parsing)
- requests 2.32.3 (HTTP - used for cloud-init status checks)
- expandvars 1.0.0 (Environment variable expansion)

**Dev Dependencies:**
- ruff (linting & formatting)
- pytest (testing)

**Build:**
- Backend: hatchling
- Packaging: shiv (creates single-file executable)
- Python: >=3.8

**Linter Config:**
- Line length: 132
- Ignore: E203 (whitespace before ':')
- Max complexity: 25 (McCabe)
- E, F, W, C90 rules enabled

---

### 9. IMPLEMENTATION CHECKLIST FOR VULTR PROVIDER

To implement a Vultr provider, you need to:

1. **Create** `/home/david/projects/stirlingbridge/machine/machine/providers/vultr.py`
   - Import vultr API client library
   - Extend `CloudProvider` base class
   - Implement all abstract methods
   - Map Vultr API responses to VM/SSHKey/DNSRecord types
   - Handle provider-specific validation (validate_region, validate_image)
   - Implement optional methods if Vultr supports projects

2. **Update** `/home/david/projects/stirlingbridge/machine/machine/providers/__init__.py`
   - Add "vultr" to KNOWN_PROVIDERS list
   - Add elif branch in create_provider() factory for vultr

3. **Update** `/home/david/projects/stirlingbridge/machine/pyproject.toml`
   - Add vultr Python client library dependency (e.g., `vultr>=3.0.0` or similar)

4. **Create Example Config** (for documentation)
   - Add `vultr:` section with required keys (API token, region, etc.)

5. **Update Tests** (if needed)
   - Extend CLI integration tests to support vultr config

6. **No Changes Needed:**
   - All subcommands work automatically via provider abstraction
   - config.py auto-detection works without changes
   - UI/CLI unchanged

---

### 10. CRITICAL NOTES FOR IMPLEMENTATION

**Provider Interface Requirements:**
- All methods must be implemented or inherited
- Return types MUST match (VM, SSHKey, DNSRecord dataclasses)
- Fatal errors via `fatal_error()` for critical failures
- Info/warnings via `info()` for non-critical issues
- Never raise exceptions; exit gracefully with fatal_error()

**Configuration Keys:**
- Config is a dict; access via provider_config["key"]
- Use `if "key" not in provider_config:` before accessing
- Call `fatal_error()` if required keys missing

**Tag Handling:**
- Accept `tags` list parameter in create_vm()
- Must store tags on VM instance (required for filtering/session isolation)
- Tag format enforced by tool (machine:created, machine:type:*, machine:session:*)

**DNS Support:**
- Optional feature (check if dns_zone in config)
- If zone doesn't exist, log warning and return None (graceful degradation)
- DNS records tied to IP addresses (data field contains IP)

**Error Handling Pattern:**
```python
try:
    # API call
except SomeApiException:
    fatal_error(f"Error: {error_message}")
```

---

### 11. FILE PATHS (ABSOLUTE)

Core files:
- `/home/david/projects/stirlingbridge/machine/machine/provider.py`
- `/home/david/projects/stirlingbridge/machine/machine/providers/__init__.py`
- `/home/david/projects/stirlingbridge/machine/machine/providers/digitalocean.py`
- `/home/david/projects/stirlingbridge/machine/machine/config.py`
- `/home/david/projects/stirlingbridge/machine/machine/main.py`
- `/home/david/projects/stirlingbridge/machine/machine/di.py`
- `/home/david/projects/stirlingbridge/machine/machine/types.py`
- `/home/david/projects/stirlingbridge/machine/pyproject.toml`

Subcommands:
- `/home/david/projects/stirlingbridge/machine/machine/subcommands/*.py` (all files)

---

This comprehensive analysis gives you everything needed to implement a Vultr (or any other) provider. The abstraction is clean and well-designed—all the provider-specific logic is isolated in a single module, while shared logic (CLI, config, subcommands) remains completely provider-agnostic.

agentId: a0f34ea91090aaf79 (for resuming to continue this agent's work if needed)
<usage>total_tokens: 41140
tool_uses: 31
duration_ms: 53878</usage>

     1→from abc import ABC, abstractmethod
     2→from dataclasses import dataclass
     3→
     4→
     5→@dataclass
     6→class VM:
     7→    id: str
     8→    name: str
     9→    tags: list
    10→    region: str
    11→    ip_address: str
    12→    status: str
    13→
    14→
    15→@dataclass
    16→class SSHKey:
    17→    id: str
    18→    name: str
    19→    fingerprint: str
    20→    public_key: str
    21→
    22→
    23→@dataclass
    24→class DNSRecord:
    25→    id: str
    26→    name: str
    27→    type: str
    28→    data: str
    29→    ttl: int
    30→
    31→
    32→class CloudProvider(ABC):
    33→    @abstractmethod
    34→    def create_vm(self, name, region, image, size, ssh_key_name, tags, user_data) -> VM:
    35→        pass
    36→
    37→    @abstractmethod
    38→    def get_vm(self, vm_id) -> VM:
    39→        pass
    40→
    41→    @abstractmethod
    42→    def destroy_vm(self, vm_id) -> bool:
    43→        pass
    44→
    45→    @abstractmethod
    46→    def list_vms(self, tag=None) -> list:
    47→        pass
    48→
    49→    @abstractmethod
    50→    def get_ssh_key(self, name) -> SSHKey:
    51→        pass
    52→
    53→    @abstractmethod
    54→    def list_ssh_keys(self) -> list:
    55→        pass
    56→
    57→    @abstractmethod
    58→    def create_dns_record(self, zone, record_type, name, data, ttl, tag=None) -> str:
    59→        pass
    60→
    61→    @abstractmethod
    62→    def delete_dns_record(self, zone, record_name) -> bool:
    63→        pass
    64→
    65→    @abstractmethod
    66→    def get_dns_records(self, zone) -> list:
    67→        pass
    68→
    69→    @abstractmethod
    70→    def list_domains(self) -> list:
    71→        pass
    72→
    73→    def list_projects(self) -> list:
    74→        return []
    75→
    76→    def assign_to_project(self, project_name, vm_id):
    77→        pass
    78→
    79→    def validate_region(self, region):
    80→        pass
    81→
    82→    def validate_image(self, image):
    83→        pass
    84→
    85→    @property
    86→    def provider_name(self) -> str:
    87→        return self.__class__.__name__
    88→

     1→from machine.log import fatal_error
     2→from machine.provider import CloudProvider
     3→
     4→KNOWN_PROVIDERS = ["digital-ocean"]
     5→
     6→
     7→def create_provider(provider_name, provider_config) -> CloudProvider:
     8→    if provider_name == "digital-ocean":
     9→        from machine.providers.digitalocean import DigitalOceanProvider
    10→
    11→        return DigitalOceanProvider(provider_config)
    12→    else:
    13→        fatal_error(f"Unknown provider: '{provider_name}'. Known providers: {', '.join(KNOWN_PROVIDERS)}")
    14→

     1→import digitalocean
     2→
     3→from machine.log import fatal_error, info
     4→from machine.provider import CloudProvider, VM, SSHKey, DNSRecord
     5→
     6→
     7→VALID_REGIONS = ["NYC1", "NYC3", "AMS3", "SFO2", "SFO3", "SGP1", "LON1", "FRA1", "TOR1", "BLR1", "SYD1"]
     8→
     9→VALID_IMAGES = [
    10→    "almalinux-8-x64",
    11→    "almalinux-9-x64",
    12→    "centos-stream-9-x64",
    13→    "debian-11-x64",
    14→    "debian-12-x64",
    15→    "fedora-39-x64",
    16→    "fedora-40-x64",
    17→    "rockylinux-9-x64",
    18→    "rockylinux-8-x64",
    19→    "ubuntu-20-04-x64",
    20→    "ubuntu-22-04-x64",
    21→    "ubuntu-24-04-x64",
    22→]
    23→
    24→
    25→def _droplet_to_vm(droplet) -> VM:
    26→    region = droplet.region
    27→    if isinstance(region, dict):
    28→        region = region.get("slug")
    29→    return VM(
    30→        id=str(droplet.id),
    31→        name=droplet.name,
    32→        tags=droplet.tags,
    33→        region=region,
    34→        ip_address=droplet.ip_address,
    35→        status=droplet.status,
    36→    )
    37→
    38→
    39→class DigitalOceanProvider(CloudProvider):
    40→    def __init__(self, provider_config):
    41→        if "access-token" not in provider_config:
    42→            fatal_error("Required key 'access-token' not found in 'digital-ocean' section of config file")
    43→        self.token = provider_config["access-token"]
    44→        self._manager = digitalocean.Manager(token=self.token)
    45→
    46→    def create_vm(self, name, region, image, size, ssh_key_name, tags, user_data) -> VM:
    47→        ssh_key = self._get_do_ssh_key(ssh_key_name)
    48→        if not ssh_key:
    49→            fatal_error(f"Error: SSH key '{ssh_key_name}' not found in DigitalOcean")
    50→
    51→        droplet = digitalocean.Droplet(
    52→            token=self.token,
    53→            name=name,
    54→            region=region,
    55→            image=image,
    56→            size_slug=size,
    57→            ssh_keys=[ssh_key],
    58→            tags=tags,
    59→            user_data=user_data,
    60→            backups=False,
    61→        )
    62→        droplet.create()
    63→        return _droplet_to_vm(droplet)
    64→
    65→    def get_vm(self, vm_id) -> VM:
    66→        droplet = self._manager.get_droplet(vm_id)
    67→        return _droplet_to_vm(droplet)
    68→
    69→    def destroy_vm(self, vm_id) -> bool:
    70→        try:
    71→            droplet = self._manager.get_droplet(vm_id)
    72→        except digitalocean.NotFoundError:
    73→            fatal_error(f"Error: machine with id {vm_id} not found")
    74→        result = droplet.destroy()
    75→        return result
    76→
    77→    def list_vms(self, tag=None) -> list:
    78→        if tag:
    79→            droplets = self._manager.get_all_droplets(tag_name=tag)
    80→        else:
    81→            droplets = self._manager.get_all_droplets()
    82→        return [_droplet_to_vm(d) for d in droplets]
    83→
    84→    def get_ssh_key(self, name) -> SSHKey:
    85→        do_key = self._get_do_ssh_key(name)
    86→        if not do_key:
    87→            return None
    88→        return SSHKey(
    89→            id=str(do_key.id),
    90→            name=do_key.name,
    91→            fingerprint=do_key.fingerprint,
    92→            public_key=do_key.public_key,
    93→        )
    94→
    95→    def list_ssh_keys(self) -> list:
    96→        keys = self._manager.get_all_sshkeys()
    97→        return [
    98→            SSHKey(id=str(k.id), name=k.name, fingerprint=k.fingerprint, public_key=k.public_key)
    99→            for k in keys
   100→        ]
   101→
   102→    def create_dns_record(self, zone, record_type, name, data, ttl, tag=None) -> str:
   103→        domain = digitalocean.Domain(token=self.token, name=zone)
   104→        try:
   105→            record = domain.create_new_domain_record(type=record_type, ttl=ttl, name=name, data=data, tag=tag)
   106→        except digitalocean.NotFoundError:
   107→            info(f"Warning: DNS zone '{zone}' not found in DigitalOcean, DNS record not set")
   108→            return None
   109→        return record
   110→
   111→    def delete_dns_record(self, zone, record_name) -> bool:
   112→        domain = digitalocean.Domain(token=self.token, name=zone)
   113→        records = domain.get_records()
   114→        for record in records:
   115→            if record.name == record_name:
   116→                domain.delete_domain_record(id=record.id)
   117→                return True
   118→        return False
   119→
   120→    def get_dns_records(self, zone) -> list:
   121→        domain = digitalocean.Domain(token=self.token, name=zone)
   122→        records = domain.get_records()
   123→        return [
   124→            DNSRecord(id=str(r.id), name=r.name, type=r.type, data=r.data, ttl=r.ttl)
   125→            for r in records
   126→        ]
   127→
   128→    def list_domains(self) -> list:
   129→        domains = self._manager.get_all_domains()
   130→        return [d.name for d in domains]
   131→
   132→    def list_projects(self) -> list:
   133→        projects = self._manager.get_all_projects()
   134→        return [p.name for p in projects]
   135→
   136→    def assign_to_project(self, project_name, vm_id):
   137→        projects = self._manager.get_all_projects()
   138→        project = None
   139→        for p in projects:
   140→            if p.name == project_name:
   141→                project = p
   142→                break
   143→        if not project:
   144→            fatal_error(f"Error: Project {project_name} does not exist, machine created but not assigned to project")
   145→        project.assign_resource([f"do:droplet:{vm_id}"])
   146→
   147→    def validate_region(self, region):
   148→        if region is not None and region.upper() not in VALID_REGIONS:
   149→            fatal_error(f"Error: region {region} is not one of {VALID_REGIONS}")
   150→
   151→    def validate_image(self, image):
   152→        if image is not None and image not in VALID_IMAGES:
   153→            info(f"Warning: image {image} is not one of these known valid images: {VALID_IMAGES}")
   154→
   155→    def _get_do_ssh_key(self, name):
   156→        keys = self._manager.get_all_sshkeys()
   157→        for key in keys:
   158→            if key.name == name:
   159→                return key
   160→        return None
   161→
   162→    @property
   163→    def provider_name(self) -> str:
   164→        return "DigitalOcean"
   165→

     1→[project]
     2→name = "machine"
     3→version = "1.0.0"
     4→description = "Utility for creating and managing VMs"
     5→readme = "README.md"
     6→license = "AGPL-3.0-only"
     7→requires-python = ">=3.8"
     8→authors = [
     9→    { name = "Stirlingbridge", email = "info@stirlingbridge.website" },
    10→]
    11→classifiers = [
    12→    "Programming Language :: Python :: 3.8",
    13→    "Operating System :: OS Independent",
    14→]
    15→dependencies = [
    16→    "click==8.1.7",
    17→    "python-digitalocean==1.17.0",
    18→    "ruamel.yaml>=0.17.32",
    19→    "requests==2.32.3",
    20→    "expandvars==1.0.0",
    21→]
    22→
    23→[project.scripts]
    24→machine = "machine.main:main"
    25→
    26→[project.urls]
    27→Homepage = "https://github.com/stirlingbridge/machine"
    28→
    29→[build-system]
    30→requires = ["hatchling"]
    31→build-backend = "hatchling.build"
    32→
    33→[tool.pytest.ini_options]
    34→markers = [
    35→    "e2e: end-to-end tests that create real resources on DigitalOcean (require E2E_* env vars)",
    36→]
    37→addopts = "-m 'not e2e'"
    38→
    39→[dependency-groups]
    40→dev = [
    41→    "ruff",
    42→    "pytest",
    43→]
    44→
    45→[tool.ruff]
    46→line-length = 132
    47→
    48→[tool.ruff.lint]
    49→select = ["E", "F", "W", "C90"]
    50→ignore = ["E203"]
    51→
    52→[tool.ruff.lint.mccabe]
    53→max-complexity = 25
    54→
    55→[tool.ruff.lint.per-file-ignores]
    56→"machine/cloud_config.py" = ["E501"]
    57→

{
  "type": "tool_reference",
  "tool_name": "WebSearch"
}

Web search results for query: "Vultr Python API client library pypi 2025 2026"

Links: [{"title":"vultr · PyPI","url":"https://pypi.org/project/vultr/"},{"title":"vultr-python · PyPI","url":"https://pypi.org/project/vultr-python/"},{"title":"GitHub - spry-group/python-vultr: Vultr Python Client library","url":"https://github.com/spry-group/python-vultr"},{"title":"GitHub - vultr/vultr-python-client: An OpenAPI Python Client for Vultr · GitHub","url":"https://github.com/vultr/vultr-python-client"},{"title":"piwheels - vultr-python-client","url":"https://www.piwheels.org/project/vultr-python-client/"},{"title":"vultr-python-client","url":"https://pypi.org/project/vultr-python-client/"},{"title":"vultr - Python Package Health Analysis | Snyk","url":"https://snyk.io/advisor/python/vultr"},{"title":"GitHub - LRTT/Vultr: Vultr Python Client library","url":"https://github.com/LRTT/Vultr"},{"title":"GitHub - JamesClonk/vultr: Vultr CLI and API client library","url":"https://github.com/JamesClonk/vultr"},{"title":"How to Use the Vultr API with Python – Tony Teaches Tech","url":"https://tonyteaches.tech/vultr-api-python-tutorial/"}]

Based on the search results, here's what I found about Vultr Python API client libraries on PyPI:

## Current Vultr Python Packages on PyPI

There are multiple Vultr Python client libraries available:

### 1. **vultr-python** (Most Recent)
This is a Python 3 wrapper for the Vultr API v2.0, released on December 1, 2025. This appears to be the most actively maintained option for current use.

### 2. **vultr** (Legacy Package)
This package provides a client library to the Vultr.com API. However, its maintenance is considered inactive, and it hasn't seen any new versions released to PyPI in the past 12 months.

### 3. **vultr-python-client**
This is a Python client for the V2 Vultr API that was generated from the OpenAPI spec at https://www.vultr.com/api/.

## Recommendation

For new projects, **vultr-python** would be the recommended choice since it was recently updated in December 2025 and is specifically designed as a Python 3 wrapper for the modern Vultr API v2.0.


REMINDER: You MUST include the sources above in your response to the user using markdown hyperlinks.

{
  "type": "tool_reference",
  "tool_name": "WebFetch"
}

I appreciate your question, but I need to clarify that the web page content provided doesn't contain information about a Python package, its versions, supported Python versions, or API methods.

The content appears to be an error page with JavaScript code for loading scripts and handling loading failures. It includes:

- An error message stating "JavaScript is disabled in your browser"
- A notice that "A required part of this site couldn't load"
- JavaScript functions for script loading and error handling

This is not documentation for a Python library or package. To answer your questions about version information, Python compatibility, package import names, usage examples, and available API methods, I would need access to actual package documentation—such as from PyPI, GitHub README files, or official documentation sites.

If you're looking for information about a specific Python package, please provide the package name or relevant documentation, and I'd be happy to help summarize that information for you.

# Vultr Python Client Library

## Library Overview

**Package Name:** openapi_client  
**Latest Version:** 1.0.0  
**Import Name:** openapi_client

## Description

This is "a python client for the V2 vultr API" generated from Vultr's OpenAPI specification using the OpenAPI Generator tool.

## Basic Usage Example

```python
import openapi_client

configuration = openapi_client.Configuration()
configuration.access_token = 'YOUR_BEARER_TOKEN'

api_client = openapi_client.ApiClient(configuration)
```

**Important:** You must manually set the access token after initializing the Configuration class, not during initialization.

## Available API Methods

The README does not provide detailed documentation of specific API methods for instances, SSH keys, DNS, or domains. It only notes that "the README and the docs folder in output_dir should be enough documentation to get started."

To access comprehensive API method documentation, you would need to:
1. Review the generated docs folder in the output directory
2. Consult the official Vultr API specification at https://www.vultr.com/api/

## Installation

Build a wheel file and install via Poetry:
```bash
poetry add <name_of_file>.whl
```

# Python-Vultr Package Information

## Installation & Import
The package is **python-vultr**. Based on the README, import it as:
```python
from vultr import Vultr
```

## Basic Usage
```python
api_key = 'YOUR_API_KEY'
vultr = Vultr(api_key)
plans_json = vultr.plans.list()
```

## Server/Instance Methods
- `server.list(subid=None, params=None)` — retrieve instances
- `server.create(dcid, vpsplanid, osid, params=None)` — provision new server
- `server.destroy(subid, params=None)` — remove instance
- `server.reboot(subid, params=None)` — restart
- `server.start(subid, params=None)` / `server.halt(subid, params=None)` — power control
- `server.bandwidth(subid, params=None)` — usage metrics
- `server.upgrade_plan(subid, vpsplanid, params=None)` — change plan

## SSH Key Methods
- `sshkey.list(params=None)` — list all keys
- `sshkey.create(name, ssh_key, params=None)` — add new key
- `sshkey.destroy(sshkeyid, params=None)` — delete key
- `sshkey.update(sshkeyid, params=None)` — modify key

## DNS Domain Methods
- `dns.list(params=None)` — retrieve domains
- `dns.create_domain(domain, ipaddr, params=None)` — register domain
- `dns.delete_domain(domain, params=None)` — remove domain

## DNS Record Methods
- `dns.records(domain, params=None)` — list records for domain
- `dns.create_record(domain, name, _type, data, params=None)` — add record
- `dns.update_record(domain, recordid, params=None)` — modify record
- `dns.delete_record(domain, recordid, params=None)` — remove record

Web search results for query: "vultr-python pypi v2 API github repository"

Links: [{"title":"GitHub - cssnr/vultr-python: Python 3 wrapper for the Vultr API v2 · GitHub","url":"https://github.com/cssnr/vultr-python"},{"title":"vultr-python · PyPI","url":"https://pypi.org/project/vultr-python/"},{"title":"vultr · PyPI","url":"https://pypi.org/project/vultr/"},{"title":"vultr-api · GitHub Topics · GitHub","url":"https://github.com/topics/vultr-api"},{"title":"GitHub - vultr/vultr-python-client: An OpenAPI Python Client for Vultr · GitHub","url":"https://github.com/vultr/vultr-python-client"},{"title":"GitHub - spry-group/python-vultr: Vultr Python Client library","url":"https://github.com/spry-group/python-vultr"},{"title":"vultr-python 0.1.5 on PyPI - Libraries.io - security & maintenance data for open source software","url":"https://libraries.io/pypi/vultr-python"},{"title":"How to Use the Vultr API with Python – Tony Teaches Tech","url":"https://tonyteaches.tech/vultr-api-python-tutorial/"},{"title":"GitHub - JamesClonk/vultr: Vultr CLI and API client library","url":"https://github.com/JamesClonk/vultr"},{"title":"vultr - Python Package Health Analysis | Snyk","url":"https://snyk.io/advisor/python/vultr"}]

Based on the search results, I found information about vultr-python for the Vultr API v2:

## Primary Repository

The main vultr-python wrapper for the Vultr API v2 is available on PyPI at https://pypi.org/project/vultr-python and on GitHub at https://github.com/cssnr/vultr-python. It's a Python 3 wrapper for the Vultr API v2.

## Installation

You can install it from PyPI using `python -m pip install vultr-python` or from source by cloning the GitHub repository.

## Alternative Repository

There's also an OpenAPI-generated Python client for the V2 Vultr API at https://github.com/vultr/vultr-python-client, which was generated from the OpenAPI spec at https://www.vultr.com/api/.

Both projects provide Python bindings to interact with the Vultr API v2, with the cssnr/vultr-python being the more community-focused wrapper and the official vultr/vultr-python-client being the OpenAPI-generated version.


REMINDER: You MUST include the sources above in your response to the user using markdown hyperlinks.

# Vultr Python Wrapper - Summary

## Installation & Import

**Package Name (pip):** `vultr-python`

```bash
python -m pip install vultr-python
```

**Import Name:**
```python
from vultr import Vultr
```

## Initialization

```python
vultr = Vultr("VULTR_API_KEY")
# Or use VULTR_API_KEY environment variable
```

## Core API Methods

### Generic HTTP Methods
The library provides low-level access via:
- `get(endpoint, params)`
- `post(endpoint, **kwargs)`
- `patch(endpoint, **kwargs)`
- `put(endpoint, **kwargs)`
- `delete(endpoint)`

### Instance Management
- `list_plans(filters)` - Retrieve available plans
- `list_regions()` - Get available regions
- `filter_regions(regions, locations)` - Filter regions by location
- `create_instance(region, plan, **data)` - Create new instance
- `list_os()` - Get OS options
- `filter_os(os_list, name)` - Filter OS by name

### SSH Key Management
- `create_key(name, ssh_key_string)` - Add SSH key
- `delete_key(key_id)` - Remove SSH key

### Additional Methods
The library supports DNS/domain operations and other endpoints through the generic HTTP methods using Vultr API v2 endpoints.

## Error Handling

```python
from vultr import VultrException

try:
    instance = vultr.create_instance(...)
except VultrException as error:
    print(error.error)    # Error message
    print(error.status)   # HTTP status code
```

## Documentation
Full documentation: https://cssnr.github.io/vultr-python/
Vultr API Reference: https://www.vultr.com/api

# Vultr Python API Methods

Based on the documentation provided, here are all available methods in the Vultr class:

## Core HTTP Methods
- `get(url, params=None)` - "GET Data"
- `post(url, **kwargs)` - "POST Data"
- `patch(url, **kwargs)` - "PATCH Data"
- `put(url, **kwargs)` - "PUT Data"
- `delete(url)` - "DELETE a Resource"

## Instance Management
- `list_instances(params=None)` - Returns list of instances
- `get_instance(instance, params=None)` - Retrieve specific instance details
- `create_instance(region, plan, **kwargs)` - Create new instance
- `update_instance(instance, **kwargs)` - Modify instance configuration
- `delete_instance(instance)` - Remove instance

## SSH Key Operations
- `list_keys(params=None)` - Retrieve all SSH keys
- `get_key(key, params=None)` - Get specific key details
- `create_key(name, key, **kwargs)` - Add new SSH key
- `update_key(key, **kwargs)` - Modify key information
- `delete_key(key)` - Remove SSH key

## Startup Scripts
- `list_scripts(params=None)` - List all scripts
- `get_script(script, params=None)` - Retrieve script details
- `create_script(name, script, **kwargs)` - Create new script
- `update_script(script, **kwargs)` - Modify script
- `delete_script(script)` - Remove script

## IPv4 Management
- `list_ipv4(instance, params=None)` - Get instance IPv4 addresses
- `create_ipv4(instance, **kwargs)` - Add IPv4 address
- `delete_ipv4(instance)` - Remove IPv4 address

## Reference Data
- `list_os(params=None)` - Available operating systems
- `list_plans(params=None)` - Available plans
- `list_regions(params=None)` - Available regions

## Filter Utilities
- `filter_list(item_list, value, key='name')` - "Helper Function to get an Item from a List of Dictionaries"
- `filter_regions(regions, locations)` - Filter by location
- `filter_keys(keys, name)` - Deprecated; use filter_list()
- `filter_os(os_list, name)` - Deprecated; use filter_list()
- `filter_scripts(scripts, name)` - Deprecated; use filter_list()

**Note:** DNS records and domains methods are not documented in the provided content.

I cannot provide the API endpoints and request/response formats you're requesting based on the content provided.

The web page content shown is primarily composed of **CSS styling rules and JavaScript/TypeScript code** for a ReDoc API documentation interface. While it contains configuration for displaying API documentation, it does not include the actual API endpoint specifications, request schemas, response formats, region IDs, or image IDs you're asking about.

To obtain this information, you would need to:

1. **Access the full Vultr API documentation** at the ReDoc interface (which this page renders)
2. **Consult the Vultr API reference directly**, which should document:
   - POST /instances request/response schemas
   - GET endpoints for listing and retrieving instances
   - DELETE instance endpoints
   - SSH key management endpoints
   - DNS domain and record operations
   - Available region identifiers
   - Available OS/image options

The page content appears to be the *wrapper* for API documentation rather than the documentation itself. The actual endpoint definitions would be stored in an OpenAPI/Swagger specification file that this ReDoc interface references.

Web search results for query: "Vultr API v2 create instance POST /v2/instances request body fields region plan os_id user_data ssh_keys tags"

Links: [{"title":"Vultr API - Vultr.com","url":"https://www.vultr.com/api/"},{"title":"Vultr API v2 | Documentation","url":"https://www.postman.com/vultr-api/vultr-api-v2/documentation/soddyfe/vultr-api-v2"},{"title":"Automating Vultr Setup with Vultr API V2 - Evilsaint","url":"https://evilsaint.com/tutorial/automating-vultr-setup-vultr-api-v2/"},{"title":"GitHub - vultr/vultr-csharp","url":"https://github.com/vultr/vultr-csharp"},{"title":"How to Provision Vultr Cloud Compute Instances | Vultr Docs","url":"https://docs.vultr.com/products/compute/cloud-compute/provisioning"},{"title":"vultr-ruby/docs/InstancesApi.md at main · vultr/vultr-ruby","url":"https://github.com/vultr/vultr-ruby/blob/main/docs/InstancesApi.md"},{"title":"How to Use the Vultr API with Python – Tony Teaches Tech","url":"https://tonyteaches.tech/vultr-api-python-tutorial/"},{"title":"Create a Server Like a Pro with Vultr API","url":"https://bobcares.com/blog/vultr-api-create-server/"},{"title":"How to Snapshot and Redeploy Vultr Compute Instances | Vultr Docs","url":"https://docs.vultr.com/how-to-take-a-snapshot-and-redeploy-a-vultr-compute-instance"},{"title":"APIs & Developer Resources - Vultr.com","url":"https://www.vultr.com/resources/developers/"}]

Based on the search results, here's information about the Vultr API v2 POST /v2/instances request body fields:

## Required Request Body Fields

For creating an instance, you must choose one of the following to deploy: os_id, snapshot_id, app_id, or image_id, and supply other attributes as desired.

## Common Request Body Fields

The main fields documented in the search results include:

- **region**: The Vultr location where the instance will be deployed
- **plan**: The instance plan to use
- **os_id**: The operating system ID to install on the instance
- **label**: The instance label for identification
- **hostname**: The hostname for the instance
- **user_data**: User data can be included in the request body

Additional optional fields mentioned include:
- **snapshot_id**: For deploying from a snapshot
- **app_id**: For deploying with an application
- **image_id**: For deploying from an image

The search results reference that "additional attributes can be applied on the Vultr Cloud Compute instance" on the Create Instance API page, but the specific details for ssh_keys and tags were not fully captured in these results. For a complete list of all available fields including ssh_keys and tags, you may need to consult the official Vultr API documentation directly.


REMINDER: You MUST include the sources above in your response to the user using markdown hyperlinks.

I've reviewed the provided web page content, which appears to be the Postman application interface with New Relic monitoring code and analytics scripts.

**I cannot provide the API documentation you requested** because the page content does not contain any API endpoint specifications, request/response formats, or field definitions for:

- Instance creation endpoints
- Instance listing or retrieval endpoints
- SSH key management endpoints
- DNS management endpoints
- Field names for instance objects

The content consists primarily of:
- JavaScript bundle initialization code
- New Relic monitoring configuration
- Analytics and telemetry scripts
- UI loader styling and prefetch directives
- Application configuration variables

**To find this information, you would need to:**

1. Access Postman's official API documentation at their developer portal
2. Review the API specification documents directly
3. Consult endpoint documentation for your specific cloud provider's API (if this relates to a Postman integration)

If you have access to the actual API documentation or specification files, please share those, and I can help extract and format the endpoint information you're looking for.

# Vultr API v2 Examples from Documentation

## Create Instance Request/Response

**Request Example:**
```
curl --location --request POST 'https://api.vultr.com/v2/instances' \
--header 'Authorization: Bearer {api-key}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "region" : "ewr",
    "plan" : "vc2-6c-16gb",
    "label" : "my label",
    "os_id" : 362,
    "user_data" : "dGVzdA==",
    "backups": "enabled"
}'
```

**Key Request Parameters:**
- `region` (required): Region identifier
- `plan` (required): Plan identifier
- `os_id`: Operating system ID
- `label`: User-supplied instance name
- `sshkey_id`: SSH key to install
- `backups`: "enabled" or "disabled"
- `hostname`: Server hostname
- `firewall_group_id`: Firewall group attachment
- `enable_ipv6`: Boolean for IPv6 support

## List Regions Response

**Example Response Structure:**
```json
{
  "regions": [{
    "id": "ams",
    "city": "Amsterdam",
    "country": "NL",
    "continent": "Europe",
    "options": ["ddos_protection"]
  }]
}
```

## Notable Limitations

The provided documentation excerpt **does not include** complete response examples for instance creation, SSH key management, or DNS operations—only the request format for creating instances is detailed.

Web search results for query: "Vultr API v2 instance response fields main_ip label status tags sshkey_id create instance dns records"

Links: [{"title":"Vultr API - Vultr.com","url":"https://www.vultr.com/api/"},{"title":"API - Vultr.com","url":"https://www.vultr.com/api/v1/?gspk=d2FyaXNwYWRjaG9kY2hhaTIyNDA&gsxid=wDqQwPfqypqd"},{"title":"Vultr API v2 | Documentation","url":"https://www.postman.com/vultr-api/vultr-api-v2/documentation/soddyfe/vultr-api-v2"},{"title":"How to Use the Vultr API with Python – Tony Teaches Tech","url":"https://tonyteaches.tech/vultr-api-python-tutorial/"},{"title":"vultr.cloud.vultr inventory – Retrieves list of instances via Vultr v2 API — Ansible Community Documentation","url":"https://docs.ansible.com/ansible/latest/collections/vultr/cloud/vultr_inventory.html"},{"title":"govultr package - github.com/vultr/govultr/v2 - Go Packages","url":"https://pkg.go.dev/github.com/vultr/govultr/v2"},{"title":"GitHub - vultr/vultr-csharp","url":"https://github.com/vultr/vultr-csharp"},{"title":"vultr.cloud.instance module – Manages server instances on Vultr. — Ansible Community Documentation","url":"https://docs.ansible.com/projects/ansible/latest/collections/vultr/cloud/instance_module.html"},{"title":"GitHub - cssnr/vultr-python: Python 3 wrapper for the Vultr API v2 · GitHub","url":"https://github.com/cssnr/vultr-python"},{"title":"vultr.Instance | Pulumi Registry","url":"https://www.pulumi.com/registry/packages/vultr/api-docs/instance/"}]

Based on the web search results, I found relevant information about Vultr API v2 instance response fields. Here's what the search revealed:

## Instance Response Fields

The Vultr API v2 returns instance data with fields like `main_ip`, and the instance response includes fields such as `id`, `os`, `ram`, `disk`, `main_ip`, `cpu_count`, `region`, `default_password`, `date_created`, `status`, `netmask_v4`, `gateway_v4`, `plan`, `label`, `tag`, `tags`, and various IPv6 fields.

Regarding the specific fields you mentioned:
- **main_ip**: Used to get the instance's IP address
- **label**: A field in the instance response
- **status**: Indicates the status of the instance
- **tags**: Used instead of the deprecated `tag` field
- **sshkey_id**: Can be passed as a parameter when creating an instance

## Creating Instances and DNS Records

When creating an instance via the API, you POST to `https://api.vultr.com/v2/instances` with parameters like `region`, `plan`, `label`, and `os_id`.

Regarding DNS records, the API includes a `DomainService` interface to create domains, and if an IP is supplied the domain will be pre-populated with entries.

For comprehensive documentation on all API endpoints and response fields, you can visit the official Vultr API documentation at https://www.vultr.com/api/.


REMINDER: You MUST include the sources above in your response to the user using markdown hyperlinks.

# GoVultr v2 - Key Struct Fields

Based on the documentation, here are the main struct fields you requested:

## Instance Struct
From the code, `Instance` is defined but full fields aren't shown in the excerpt. However, based on context, it contains fields like:
- `ID` (string)
- `Label` (string)
- `Status` (string)
- `Region` (string)
- `Plan` (string)
- `OS` info
- `MainIP` (string)
- Various networking and configuration fields

## InstanceCreateReq Struct
```go
type InstanceCreateReq struct {
    Label                string
    Hostname             string
    Backups              string
    EnableIPv6           *bool
    OsID                 int
    Plan                 string
    Region               string
    // ... additional fields for SSH keys, VPC, networks, etc.
}
```

**Example usage:**
```go
instanceOptions := &govultr.InstanceCreateReq{
    Label:                "awesome-go-app",
    Hostname:             "awesome-go.com",
    Backups:              "enabled",
    EnableIPv6:           BoolToBoolPtr(false),
    OsID:                 362,
    Plan:                 "vc2-1c-2gb",   
    Region:               "ewr",
}

res, err := vultrClient.Instance.Create(context.Background(), instanceOptions)
```

## SSHKey Struct
```go
type SSHKey struct {
    ID   string
    Name string
    // Public key data
}
```

## DomainRecord Struct
```go
type DomainRecord struct {
    ID       string
    Type     string
    Name     string
    Data     string
    Priority int
    TTL      int
}
```

## Domain Struct
```go
type Domain struct {
    Domain      string
    DateCreated string
    // DNS configuration fields
}
```

## Key Helper Functions
The library provides conversion utilities:
```go
BoolToBoolPtr(value bool) *bool
StringToStringPtr(value string) *string
IntToIntPtr(value int) *int
```

This mirrors the Vultr API v2 exactly with full service handler support for CRUD operations on all resources.

     1→import sys
     2→
     3→
     4→def fatal_error(s: str):
     5→    print(s, file=sys.stderr)
     6→    sys.exit(1)
     7→
     8→
     9→def debug(s: str):
    10→    print(s, file=sys.stderr)
    11→
    12→
    13→def info(s: str):
    14→    print(s, file=sys.stderr)
    15→
    16→
    17→def output(s: str):
    18→    print(s)
    19→

     1→import os
     2→import re
     3→from pathlib import Path
     4→from machine.di import d
     5→from machine.factory import yaml
     6→from machine.log import fatal_error, debug
     7→from machine.types import Config, MachineConfig
     8→from machine import constants
     9→from machine.providers import KNOWN_PROVIDERS
    10→
    11→_env_var_pattern = re.compile(r"\$\{([^}]+)\}")
    12→
    13→
    14→def _expand_env_vars(value):
    15→    if isinstance(value, str):
    16→
    17→        def _replace(match):
    18→            expr = match.group(1)
    19→            if ":-" in expr:
    20→                var_name, default = expr.split(":-", 1)
    21→                return os.environ.get(var_name, default)
    22→            else:
    23→                if expr not in os.environ:
    24→                    fatal_error(f"Environment variable '{expr}' referenced in config is not set")
    25→                return os.environ[expr]
    26→
    27→        return _env_var_pattern.sub(_replace, value)
    28→    elif isinstance(value, dict):
    29→        return {k: _expand_env_vars(v) for k, v in value.items()}
    30→    elif isinstance(value, list):
    31→        return [_expand_env_vars(item) for item in value]
    32→    return value
    33→
    34→
    35→class _loaded_config:
    36→    c: any = None
    37→
    38→
    39→def _load_config_data(config_file_name: str):
    40→    if not config_file_name:
    41→        config_file_name = constants.default_config_file_path
    42→    config_path = Path(os.path.expanduser(config_file_name))
    43→    if not config_path.exists():
    44→        fatal_error(f"Error: Config file: {config_path} not found")
    45→    config = _expand_env_vars(yaml().load(open(config_path, "r")))
    46→    if d.opt.debug:
    47→        debug(f"Loaded config file: {config_path}")
    48→        debug(f"Parsed config: {config}")
    49→    _loaded_config.c = config
    50→    return config
    51→
    52→
    53→def _require_key(d, key, section_name):
    54→    if key not in d:
    55→        fatal_error(f"Required key '{key}' not found in '{section_name}' section of config file")
    56→    return d[key]
    57→
    58→
    59→def get(config_file_name: str) -> Config:
    60→    config = _load_config_data(config_file_name)
    61→
    62→    # Auto-detect provider from config sections
    63→    provider_name = config.get("provider")
    64→    if not provider_name:
    65→        found = [p for p in KNOWN_PROVIDERS if p in config]
    66→        if len(found) == 0:
    67→            fatal_error(
    68→                "No provider section found in config file. Expected one of: " + ", ".join(KNOWN_PROVIDERS)
    69→            )
    70→        if len(found) > 1:
    71→            fatal_error(
    72→                "Multiple provider sections found in config file. Please add a 'provider:' key to select one."
    73→            )
    74→        provider_name = found[0]
    75→
    76→    if provider_name not in config:
    77→        fatal_error(f"Provider '{provider_name}' specified but no '{provider_name}' section found in config file")
    78→
    79→    provider_config = config[provider_name]
    80→    return Config(
    81→        provider_name=provider_name,
    82→        provider_config=provider_config,
    83→        ssh_key=_require_key(provider_config, "ssh-key", provider_name),
    84→        dns_zone=provider_config.get("dns-zone"),
    85→        machine_size=_require_key(provider_config, "machine-size", provider_name),
    86→        image=_require_key(provider_config, "image", provider_name),
    87→        region=_require_key(provider_config, "region", provider_name),
    88→        project=provider_config.get("project"),
    89→    )
    90→
    91→
    92→def get_machine(name: str) -> MachineConfig:
    93→    if not _loaded_config.c:
    94→        fatal_error("Attempt to fetch machine data before config loaded")
    95→    config = _loaded_config.c
    96→    if "machines" not in config:
    97→        fatal_error("Required 'machines' section not found in config file")
    98→    config_machines = config["machines"]
    99→    if name not in config_machines:
   100→        fatal_error(f"Machine type '{name}' not found in config file. Available types: {', '.join(config_machines.keys())}")
   101→    target_config = config_machines[name]
   102→    return MachineConfig(
   103→        _require_key(target_config, "new-user-name", f"machines.{name}"),
   104→        target_config.get("script-url"),
   105→        target_config.get("script-dir"),
   106→        target_config.get("script-path"),
   107→        target_config.get("script-args"),
   108→    )
   109→
   110→
   111→def get_machines():
   112→    if not _loaded_config.c:
   113→        fatal_error("Attempt to fetch machine data before config loaded")
   114→    config = _loaded_config.c
   115→
   116→    if "machines" not in config:
   117→        fatal_error("Required 'machines' section not found in config file")
   118→    ret = {}
   119→    for name in config["machines"]:
   120→        ret[name] = get_machine(name)
   121→    return ret
   122→

File created successfully at: /home/david/projects/stirlingbridge/machine/machine/providers/vultr.py

The file /home/david/projects/stirlingbridge/machine/machine/providers/__init__.py has been updated successfully.

The file /home/david/projects/stirlingbridge/machine/pyproject.toml has been updated successfully.

Resolved 29 packages in 727ms
   Building machine @ file:///home/david/projects/stirlingbridge/machine
      Built machine @ file:///home/david/projects/stirlingbridge/machine
Prepared 2 packages in 686ms
Uninstalled 1 package in 1ms
Installed 2 packages in 1ms
 ~ machine==1.0.0 (from file:///home/david/projects/stirlingbridge/machine)
 + vultr-python==0.2.0

All checks passed!

Import OK
Vultr init vars: ('self', 'api_key')
Methods: ['create_instance', 'create_ipv4', 'create_key', 'create_script', 'delete', 'delete_instance', 'delete_ipv4', 'delete_key', 'delete_script', 'filter_keys', 'filter_list', 'filter_os', 'filter_regions', 'filter_scripts', 'get', 'get_instance', 'get_key', 'get_script', 'list_instances', 'list_ipv4', 'list_keys', 'list_os', 'list_plans', 'list_regions', 'list_scripts', 'patch', 'post', 'put', 'update_instance', 'update_key', 'update_script', 'url']

(self, url: str, **kwargs) -> Any
(self, url: str, params: Optional[dict] = None) -> Any
(self, url: str) -> None

    def post(self, url: str, **kwargs) -> Any:
        """
        POST Data
        :param url: Request URL. Example `/instances`
        :param kwargs: Request Data Keyword Arguments
        :return: Response Data
        :raises: `VultrException`
        """
        return self._req("post", f"{self.url}/{url.lstrip('/')}", kwargs)

    def _req(self, method, url, data: Any = None, params: Optional[dict] = None) -> Any:
        r = self._session.request(method, url, params=params, json=data, timeout=10)
        if not r.ok:
            raise VultrException(r)
        if r.status_code == 204:
            return None
        if r.headers.get("content-type") == "application/json":
            return r.json()
        return r.text

The file /home/david/projects/stirlingbridge/machine/machine/providers/vultr.py has been updated successfully.

All checks passed!

VultrProvider loaded OK
Known providers: ['digital-ocean', 'vultr']

/home/david/projects/stirlingbridge/machine/tests/test_input_validation.py
/home/david/projects/stirlingbridge/machine/tests/test_cli_integration.py
/home/david/projects/stirlingbridge/machine/tests/test_config.py
/home/david/projects/stirlingbridge/machine/.venv/lib/python3.12/site-packages/click/testing.py
/home/david/projects/stirlingbridge/machine/.venv/lib/python3.12/site-packages/pygments/lexers/testing.py
/home/david/projects/stirlingbridge/machine/tests/test_e2e.py

     1→import os
     2→import pytest
     3→from unittest.mock import patch
     4→from machine.config import _expand_env_vars
     5→
     6→
     7→class TestExpandEnvVars:
     8→    def test_plain_string_unchanged(self):
     9→        assert _expand_env_vars("hello world") == "hello world"
    10→
    11→    def test_non_string_types_unchanged(self):
    12→        assert _expand_env_vars(42) == 42
    13→        assert _expand_env_vars(3.14) == 3.14
    14→        assert _expand_env_vars(True) is True
    15→        assert _expand_env_vars(None) is None
    16→
    17→    def test_simple_variable_substitution(self):
    18→        with patch.dict(os.environ, {"MY_VAR": "my_value"}):
    19→            assert _expand_env_vars("${MY_VAR}") == "my_value"
    20→
    21→    def test_variable_embedded_in_string(self):
    22→        with patch.dict(os.environ, {"HOST": "example.com"}):
    23→            assert _expand_env_vars("https://${HOST}/api") == "https://example.com/api"
    24→
    25→    def test_multiple_variables_in_string(self):
    26→        with patch.dict(os.environ, {"HOST": "example.com", "PORT": "8080"}):
    27→            assert _expand_env_vars("${HOST}:${PORT}") == "example.com:8080"
    28→
    29→    def test_default_value_when_var_unset(self):
    30→        env = os.environ.copy()
    31→        env.pop("UNSET_VAR", None)
    32→        with patch.dict(os.environ, env, clear=True):
    33→            assert _expand_env_vars("${UNSET_VAR:-fallback}") == "fallback"
    34→
    35→    def test_default_value_ignored_when_var_set(self):
    36→        with patch.dict(os.environ, {"MY_VAR": "actual"}):
    37→            assert _expand_env_vars("${MY_VAR:-fallback}") == "actual"
    38→
    39→    def test_default_value_empty_string(self):
    40→        env = os.environ.copy()
    41→        env.pop("UNSET_VAR", None)
    42→        with patch.dict(os.environ, env, clear=True):
    43→            assert _expand_env_vars("${UNSET_VAR:-}") == ""
    44→
    45→    def test_unset_variable_without_default_exits(self):
    46→        env = os.environ.copy()
    47→        env.pop("MISSING_VAR", None)
    48→        with patch.dict(os.environ, env, clear=True):
    49→            with pytest.raises(SystemExit):
    50→                _expand_env_vars("${MISSING_VAR}")
    51→
    52→    def test_dict_values_expanded(self):
    53→        with patch.dict(os.environ, {"TOKEN": "secret123"}):
    54→            data = {"key": "${TOKEN}", "plain": "no-change"}
    55→            result = _expand_env_vars(data)
    56→            assert result == {"key": "secret123", "plain": "no-change"}
    57→
    58→    def test_nested_dict_expanded(self):
    59→        with patch.dict(os.environ, {"VAL": "deep"}):
    60→            data = {"outer": {"inner": "${VAL}"}}
    61→            result = _expand_env_vars(data)
    62→            assert result == {"outer": {"inner": "deep"}}
    63→
    64→    def test_list_values_expanded(self):
    65→        with patch.dict(os.environ, {"A": "x", "B": "y"}):
    66→            data = ["${A}", "literal", "${B}"]
    67→            result = _expand_env_vars(data)
    68→            assert result == ["x", "literal", "y"]
    69→
    70→    def test_mixed_nested_structure(self):
    71→        with patch.dict(os.environ, {"V": "replaced"}):
    72→            data = {"list": ["${V}", "fixed"], "nested": {"k": "${V}"}}
    73→            result = _expand_env_vars(data)
    74→            assert result == {"list": ["replaced", "fixed"], "nested": {"k": "replaced"}}
    75→

     1→"""Integration tests that run the machine CLI as a subprocess, the same way a user would."""
     2→
     3→import os
     4→import subprocess
     5→import textwrap
     6→import pytest
     7→
     8→
     9→def run_machine(*args, env_override=None):
    10→    """Run the machine CLI as a subprocess and return the result."""
    11→    env = os.environ.copy()
    12→    if env_override:
    13→        env.update(env_override)
    14→    result = subprocess.run(
    15→        ["uv", "run", "machine"] + list(args),
    16→        capture_output=True,
    17→        text=True,
    18→        env=env,
    19→    )
    20→    return result
    21→
    22→
    23→def write_config(path, content):
    24→    with open(path, "w") as f:
    25→        f.write(textwrap.dedent(content))
    26→
    27→
    28→class TestVersionCommand:
    29→    """Smoke test: the CLI runs and the version command works without any config."""
    30→
    31→    def test_version_runs(self):
    32→        result = run_machine("version")
    33→        assert result.returncode == 0
    34→        assert result.stdout.strip()  # prints something
    35→
    36→    def test_help_runs(self):
    37→        result = run_machine("--help")
    38→        assert result.returncode == 0
    39→        assert "Usage" in result.stdout
    40→
    41→
    42→class TestEnvVarExpansionIntegration:
    43→    """End-to-end tests that verify environment variable expansion works
    44→    when the actual machine tool is invoked with a config file."""
    45→
    46→    @pytest.fixture()
    47→    def config_dir(self, tmp_path):
    48→        return tmp_path
    49→
    50→    def test_env_var_expanded_in_config(self, config_dir):
    51→        config_file = config_dir / "config.yml"
    52→        write_config(
    53→            config_file,
    54→            """\
    55→            digital-ocean:
    56→              access-token: "${TEST_DO_TOKEN}"
    57→              ssh-key: test-key
    58→              machine-size: s-1vcpu-1gb
    59→              image: ubuntu-22-04-x64
    60→              region: nyc1
    61→              project: test-project
    62→            machines:
    63→              test-machine:
    64→                new-user-name: testuser
    65→            """,
    66→        )
    67→        result = run_machine(
    68→            "--debug",
    69→            "--config-file",
    70→            str(config_file),
    71→            "types",
    72→            env_override={"TEST_DO_TOKEN": "tok_secret_12345"},
    73→        )
    74→        assert result.returncode == 0
    75→        # The debug output on stderr should contain the expanded token value
    76→        assert "tok_secret_12345" in result.stderr
    77→        # And should NOT contain the unexpanded variable reference
    78→        assert "${TEST_DO_TOKEN}" not in result.stderr
    79→        # The types command should list the machine name on stdout
    80→        assert "test-machine" in result.stdout
    81→
    82→    def test_multiple_env_vars_expanded(self, config_dir):
    83→        config_file = config_dir / "config.yml"
    84→        write_config(
    85→            config_file,
    86→            """\
    87→            digital-ocean:
    88→              access-token: "${TEST_TOKEN}"
    89→              ssh-key: "${TEST_SSH_KEY}"
    90→              machine-size: s-1vcpu-1gb
    91→              image: ubuntu-22-04-x64
    92→              region: nyc1
    93→              project: test-project
    94→            machines:
    95→              dev:
    96→                new-user-name: devuser
    97→            """,
    98→        )
    99→        result = run_machine(
   100→            "--debug",
   101→            "--config-file",
   102→            str(config_file),
   103→            "types",
   104→            env_override={"TEST_TOKEN": "expanded_token", "TEST_SSH_KEY": "expanded_key"},
   105→        )
   106→        assert result.returncode == 0
   107→        assert "expanded_token" in result.stderr
   108→        assert "expanded_key" in result.stderr
   109→
   110→    def test_env_var_with_default_uses_default_when_unset(self, config_dir):
   111→        config_file = config_dir / "config.yml"
   112→        write_config(
   113→            config_file,
   114→            """\
   115→            digital-ocean:
   116→              access-token: fake-token
   117→              ssh-key: test-key
   118→              machine-size: "${TEST_SIZE:-s-2vcpu-4gb}"
   119→              image: ubuntu-22-04-x64
   120→              region: nyc1
   121→              project: test-project
   122→            machines:
   123→              myvm:
   124→                new-user-name: admin
   125→            """,
   126→        )
   127→        # Make sure TEST_SIZE is not in the environment
   128→        clean_env = os.environ.copy()
   129→        clean_env.pop("TEST_SIZE", None)
   130→        result = run_machine(
   131→            "--debug",
   132→            "--config-file",
   133→            str(config_file),
   134→            "types",
   135→            env_override={},
   136→        )
   137→        # Run with TEST_SIZE explicitly removed
   138→        result = subprocess.run(
   139→            ["uv", "run", "machine", "--debug", "--config-file", str(config_file), "types"],
   140→            capture_output=True,
   141→            text=True,
   142→            env=clean_env,
   143→        )
   144→        assert result.returncode == 0
   145→        assert "s-2vcpu-4gb" in result.stderr
   146→
   147→    def test_env_var_with_default_uses_value_when_set(self, config_dir):
   148→        config_file = config_dir / "config.yml"
   149→        write_config(
   150→            config_file,
   151→            """\
   152→            digital-ocean:
   153→              access-token: fake-token
   154→              ssh-key: test-key
   155→              machine-size: "${TEST_SIZE:-s-2vcpu-4gb}"
   156→              image: ubuntu-22-04-x64
   157→              region: nyc1
   158→              project: test-project
   159→            machines:
   160→              myvm:
   161→                new-user-name: admin
   162→            """,
   163→        )
   164→        result = run_machine(
   165→            "--debug",
   166→            "--config-file",
   167→            str(config_file),
   168→            "types",
   169→            env_override={"TEST_SIZE": "s-4vcpu-8gb"},
   170→        )
   171→        assert result.returncode == 0
   172→        assert "s-4vcpu-8gb" in result.stderr
   173→        assert "s-2vcpu-4gb" not in result.stderr
   174→
   175→    def test_missing_env_var_without_default_exits_with_error(self, config_dir):
   176→        config_file = config_dir / "config.yml"
   177→        write_config(
   178→            config_file,
   179→            """\
   180→            digital-ocean:
   181→              access-token: "${DEFINITELY_NOT_SET_VAR}"
   182→              ssh-key: test-key
   183→              machine-size: s-1vcpu-1gb
   184→              image: ubuntu-22-04-x64
   185→              region: nyc1
   186→              project: test-project
   187→            machines:
   188→              myvm:
   189→                new-user-name: admin
   190→            """,
   191→        )
   192→        clean_env = os.environ.copy()
   193→        clean_env.pop("DEFINITELY_NOT_SET_VAR", None)
   194→        result = subprocess.run(
   195→            ["uv", "run", "machine", "--config-file", str(config_file), "types"],
   196→            capture_output=True,
   197→            text=True,
   198→            env=clean_env,
   199→        )
   200→        assert result.returncode != 0
   201→        assert "DEFINITELY_NOT_SET_VAR" in result.stderr
   202→
   203→    def test_env_var_in_machine_config_section(self, config_dir):
   204→        config_file = config_dir / "config.yml"
   205→        write_config(
   206→            config_file,
   207→            """\
   208→            digital-ocean:
   209→              access-token: fake-token
   210→              ssh-key: test-key
   211→              machine-size: s-1vcpu-1gb
   212→              image: ubuntu-22-04-x64
   213→              region: nyc1
   214→              project: test-project
   215→            machines:
   216→              web-server:
   217→                new-user-name: "${TEST_USERNAME}"
   218→              db-server:
   219→                new-user-name: admin
   220→            """,
   221→        )
   222→        result = run_machine(
   223→            "--debug",
   224→            "--config-file",
   225→            str(config_file),
   226→            "types",
   227→            env_override={"TEST_USERNAME": "deploy_user"},
   228→        )
   229→        assert result.returncode == 0
   230→        assert "deploy_user" in result.stderr
   231→        # Both machine types should be listed
   232→        assert "db-server" in result.stdout
   233→        assert "web-server" in result.stdout
   234→

============================= test session starts ==============================
platform linux -- Python 3.12.3, pytest-9.0.2, pluggy-1.6.0 -- /home/david/projects/stirlingbridge/machine/.venv/bin/python
cachedir: .pytest_cache
rootdir: /home/david/projects/stirlingbridge/machine
configfile: pyproject.toml
collecting ... collected 35 items / 6 deselected / 29 selected

tests/test_cli_integration.py::TestVersionCommand::test_version_runs PASSED [  3%]
tests/test_cli_integration.py::TestVersionCommand::test_help_runs PASSED [  6%]
tests/test_cli_integration.py::TestEnvVarExpansionIntegration::test_env_var_expanded_in_config PASSED [ 10%]
tests/test_cli_integration.py::TestEnvVarExpansionIntegration::test_multiple_env_vars_expanded PASSED [ 13%]
tests/test_cli_integration.py::TestEnvVarExpansionIntegration::test_env_var_with_default_uses_default_when_unset PASSED [ 17%]
tests/test_cli_integration.py::TestEnvVarExpansionIntegration::test_env_var_with_default_uses_value_when_set PASSED [ 20%]
tests/test_cli_integration.py::TestEnvVarExpansionIntegration::test_missing_env_var_without_default_exits_with_error PASSED [ 24%]
tests/test_cli_integration.py::TestEnvVarExpansionIntegration::test_env_var_in_machine_config_section PASSED [ 27%]
tests/test_config.py::TestExpandEnvVars::test_plain_string_unchanged PASSED [ 31%]
tests/test_config.py::TestExpandEnvVars::test_non_string_types_unchanged PASSED [ 34%]
tests/test_config.py::TestExpandEnvVars::test_simple_variable_substitution PASSED [ 37%]
tests/test_config.py::TestExpandEnvVars::test_variable_embedded_in_string PASSED [ 41%]
tests/test_config.py::TestExpandEnvVars::test_multiple_variables_in_string PASSED [ 44%]
tests/test_config.py::TestExpandEnvVars::test_default_value_when_var_unset PASSED [ 48%]
tests/test_config.py::TestExpandEnvVars::test_default_value_ignored_when_var_set PASSED [ 51%]
tests/test_config.py::TestExpandEnvVars::test_default_value_empty_string PASSED [ 55%]
tests/test_config.py::TestExpandEnvVars::test_unset_variable_without_default_exits PASSED [ 58%]
tests/test_config.py::TestExpandEnvVars::test_dict_values_expanded PASSED [ 62%]
tests/test_config.py::TestExpandEnvVars::test_nested_dict_expanded PASSED [ 65%]
tests/test_config.py::TestExpandEnvVars::test_list_values_expanded PASSED [ 68%]
tests/test_config.py::TestExpandEnvVars::test_mixed_nested_structure PASSED [ 72%]
tests/test_input_validation.py::TestInvalidMachineType::test_invalid_machine_type_error_message PASSED [ 75%]
tests/test_input_validation.py::TestInvalidMachineType::test_valid_machine_type_accepted PASSED [ 79%]
tests/test_input_validation.py::TestMissingConfigSections::test_missing_digital_ocean_section PASSED [ 82%]
tests/test_input_validation.py::TestMissingConfigSections::test_missing_access_token PASSED [ 86%]
tests/test_input_validation.py::TestMissingConfigSections::test_missing_ssh_key PASSED [ 89%]
tests/test_input_validation.py::TestMissingConfigSections::test_missing_machines_section PASSED [ 93%]
tests/test_input_validation.py::TestMissingConfigSections::test_missing_new_user_name_in_machine PASSED [ 96%]
tests/test_input_validation.py::TestCreateNoInitialize::test_no_initialize_without_type_no_crash PASSED [100%]

======================= 29 passed, 6 deselected in 4.02s =======================

     1→# machine
     2→CLI utility to create and manage VMs
     3→
     4→Initially supports only DigitalOcean using the [python-digitalocean](https://github.com/koalalorenzo/python-digitalocean) module.
     5→
     6→## Prerequisites
     7→
     8→This project uses [uv](https://docs.astral.sh/uv/) for dependency management and builds.
     9→
    10→Install uv:
    11→```
    12→curl -LsSf https://astral.sh/uv/install.sh | sh
    13→```
    14→
    15→## Development Setup
    16→
    17→```
    18→uv sync
    19→```
    20→
    21→This creates a `.venv` virtual environment and installs all dependencies (including dev tools like ruff).
    22→
    23→Run the CLI during development:
    24→```
    25→uv run machine --help
    26→```
    27→
    28→Run the linter:
    29→```
    30→uv run ruff check machine/
    31→```
    32→
    33→## Build
    34→
    35→Build a self-contained executable using [shiv](https://github.com/linkedin/shiv):
    36→```
    37→./sh/build-package.sh
    38→```
    39→
    40→This produces `build/machine`, a single-file Python zipapp.
    41→
    42→## Install
    43→
    44→Install directly from the GitHub repository using uv:
    45→```
    46→uv tool install git+https://github.com/stirlingbridge/machine.git
    47→```
    48→
    49→Alternatively, download the `machine` binary from the [releases page](https://github.com/stirlingbridge/machine/releases), make it executable, and place it on your PATH:
    50→```
    51→chmod +x machine
    52→sudo mv machine /usr/local/bin/
    53→```
    54→
    55→## Usage
    56→
    57→### Config File
    58→Access token and other settings configured in the file `~/.machine/config.yml` :
    59→```yaml
    60→digital-ocean:
    61→    access-token: dop_v1_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    62→    ssh-key: my-ssh-key-name
    63→    dns-zone: example.com
    64→    machine-size: s-4vcpu-8gb
    65→    image: ubuntu-22-04-x64
    66→    region: nyc3
    67→    project: Infrastructure
    68→
    69→machines:
    70→    example:
    71→        new-user-name: alice
    72→        script-dir: /opt/setup-scripts
    73→        script-url: https://raw.githubusercontent.com/example/setup-machine.sh
    74→        script-path: /opt/setup-scripts/setup-machine.sh
    75→        script-args: "-y"
    76→```
    77→
    78→#### Config Reference
    79→
    80→**digital-ocean section:**
    81→
    82→| Key | Required | Description |
    83→|-----|----------|-------------|
    84→| `access-token` | Yes | DigitalOcean API access token |
    85→| `ssh-key` | Yes | Name of the SSH key in your DigitalOcean account to use for new machines |
    86→| `dns-zone` | No | DNS zone for automatic DNS record creation/deletion |
    87→| `machine-size` | Yes | Default machine size slug (e.g. `s-4vcpu-8gb`) |
    88→| `image` | Yes | Default image name (e.g. `ubuntu-22-04-x64`) |
    89→| `region` | Yes | Default region code (e.g. `nyc3`) |
    90→| `project` | No | DigitalOcean project name to assign new machines to |
    91→
    92→**machines section:**
    93→
    94→Each entry under `machines:` defines a machine type that can be referenced with `create --type`:
    95→
    96→| Key | Required | Description |
    97→|-----|----------|-------------|
    98→| `new-user-name` | Yes | Username for the non-root user created on the machine |
    99→| `script-url` | No | URL to download an initialization script from |
   100→| `script-dir` | No | Directory to store the initialization script |
   101→| `script-path` | No | Full path for the initialization script |
   102→| `script-args` | No | Arguments passed to the initialization script (supports variable expansion) |
   103→
   104→If `script-url`, `script-dir`, and `script-path` are all provided, the script is downloaded and executed as the new user during cloud-init. The following variables are available for expansion in `script-args`:
   105→
   106→- `$MACHINE_SCRIPT_URL` — URL of the initialization script
   107→- `$MACHINE_SCRIPT_DIR` — directory path for the script
   108→- `$MACHINE_FQDN` — fully qualified domain name of the machine (if DNS is configured)
   109→
   110→#### Environment Variable Substitution
   111→
   112→Config values support environment variable substitution using `${VAR}` syntax, similar to Docker Compose files. This is useful for keeping secrets like API tokens out of the config file.
   113→
   114→Supported forms:
   115→- `${VAR}` — substitutes the value of `VAR`; errors if the variable is not set
   116→- `${VAR:-default}` — substitutes the value of `VAR`, or `default` if the variable is not set
   117→
   118→Example:
   119→```yaml
   120→digital-ocean:
   121→    access-token: ${DO_API_TOKEN}
   122→    ssh-key: ${SSH_KEY_NAME:-my-ssh-key}
   123→    dns-zone: example.com
   124→    machine-size: ${MACHINE_SIZE:-s-4vcpu-8gb}
   125→    image: ubuntu-22-04-x64
   126→    region: ${DO_REGION:-nyc3}
   127→    project: Infrastructure
   128→```
   129→
   130→Substitution is applied to all string values throughout the config file, including the `machines` section.
   131→
   132→#### Advanced Machine Setup
   133→
   134→Examples of advanced machine setup scripts can be found in [the machine-provisioning repository](https://github.com/bozemanpass/machine-provisioning).
   135→
   136→### Session Management
   137→
   138→Each invocation of `machine` uses a session ID (auto-generated and stored in `~/.machine/session-id.yml`). Machines are tagged with their session ID on creation. By default, `list`, `status`, `list-domain`, and `destroy` only operate on machines from the current session. Use the `--all` flag to include machines from other sessions or machines not created by this tool.
   139→
   140→The session ID can be overridden with the global `--session-id` option.
   141→
   142→### Automatic Tagging
   143→
   144→Machines created by this tool are automatically tagged with:
   145→
   146→- `machine:created` — identifies the machine as created by this tool
   147→- `machine:type:<type-name>` — the machine type from the config
   148→- `machine:session:<session-id>` — the session that created the machine
   149→
   150→### Global Options
   151→```
   152→$ machine --help
   153→Usage: machine [OPTIONS] COMMAND [ARGS]...
   154→
   155→Options:
   156→  --debug               Enable debug output
   157→  --quiet               Suppress all non-essential output
   158→  --verbose             Enable verbose output
   159→  --dry-run             Run but do not do anything
   160→  --config-file <PATH>  Specify the config file (default
   161→                        ~/.machine/config.yml)
   162→  --session-id <ID>     Override the default session ID
   163→  -h, --help            Show this message and exit.
   164→
   165→Commands:
   166→  create       Create a machine
   167→  destroy      Destroy one or more machines
   168→  domains      List dns domains
   169→  list         List machines
   170→  list-domain  List domain records
   171→  projects     List projects
   172→  ssh-keys     List ssh keys
   173→  status       Machine status
   174→  types        List configured machine types
   175→  version      Display version
   176→```
   177→
   178→### Commands
   179→
   180→#### create
   181→
   182→Create a new machine on DigitalOcean. By default, the machine is initialized with cloud-init (using the specified `--type` from config) and a DNS A record is created.
   183→
   184→```
   185→$ machine create --help
   186→Usage: machine create [OPTIONS]
   187→
   188→  Create a machine
   189→
   190→Options:
   191→  -n, --name <MACHINE-NAME>         Name for new machine  [required]
   192→  -t, --tag <TAG-TEXT>              Tag to be applied to new machine
   193→  -m, --type <MACHINE-TYPE>        Machine type from config (required if --initialize)
   194→  -r, --region <REGION-CODE>       Region (overrides config default)
   195→  -s, --machine-size <MACHINE-SLUG>
   196→                                    Machine size (overrides config default)
   197→  -s, --image <IMAGE-NAME>         Image (overrides config default)
   198→  --wait-for-ip / --no-wait-for-ip Wait for IP address assignment (default: off)
   199→  --update-dns / --no-update-dns   Create DNS A record (default: on)
   200→  --initialize / --no-initialize   Initialize with cloud-init (default: on)
   201→  -h, --help                       Show this message and exit.
   202→```
   203→
   204→Supported regions: `NYC1`, `NYC3`, `AMS3`, `SFO2`, `SFO3`, `SGP1`, `LON1`, `FRA1`, `TOR1`, `BLR1`, `SYD1`
   205→
   206→When `--update-dns` is enabled (the default), the command waits for the droplet's IP address and creates an A record in the configured `dns-zone` with a 5-minute TTL.
   207→
   208→When `--initialize` is enabled (the default), a cloud-config user-data payload is generated that creates a non-root user with sudo access, installs the SSH key, and optionally downloads and runs an initialization script.
   209→
   210→If a `project` is configured, the machine is automatically assigned to that DigitalOcean project.
   211→
   212→#### destroy
   213→
   214→Destroy one or more machines by droplet ID. By default, requires confirmation and deletes associated DNS records.
   215→
   216→```
   217→$ machine destroy --help
   218→Usage: machine destroy [OPTIONS] [DROPLET-IDS]...
   219→
   220→  Destroy one or more machines
   221→
   222→Options:
   223→  --confirm / --no-confirm       Require confirmation (default: on)
   224→  --delete-dns / --no-delete-dns Delete associated DNS records (default: on)
   225→  --all                          Include machines not created by this tool
   226→                                 or by other sessions
   227→  -h, --help                     Show this message and exit.
   228→```
   229→
   230→Confirmation requires typing exactly `YES` (not "y", "yes", or "Yes"). Use `--no-confirm` to skip.
   231→
   232→Safety checks prevent destroying machines that were not created by this tool or that belong to a different session, unless `--all` is specified.
   233→
   234→#### list
   235→
   236→List machines with optional filtering.
   237→
   238→```
   239→$ machine list --help
   240→Usage: machine list [OPTIONS]
   241→
   242→  List machines
   243→
   244→Options:
   245→  --id <MACHINE-ID>       Filter by id
   246→  -n, --name <MACHINE-NAME>  Filter by name
   247→  -t, --tag <TAG-TEXT>    Filter by tag
   248→  -m, --type <MACHINE-TYPE>  Filter by type
   249→  -r, --region <REGION>   Filter by region
   250→  -o, --output <FORMAT>   Output format (json)
   251→  -q, --quiet             Only display machine IDs
   252→  --unique                Return an error if more than one match
   253→  --all                   Include all machines from all sessions
   254→  -h, --help              Show this message and exit.
   255→```
   256→
   257→Output formats:
   258→- Default: `name (id, region, type): ip_address`
   259→- `--quiet`: droplet IDs only
   260→- `--output json`: JSON array with id, name, tags, region, ip, type
   261→
   262→#### status
   263→
   264→Check the status of machines, including querying a custom status endpoint.
   265→
   266→```
   267→$ machine status --help
   268→Usage: machine status [OPTIONS]
   269→
   270→  Machine status
   271→
   272→Options:
   273→  --id <MACHINE-ID>          Filter by id
   274→  -n, --name <MACHINE-NAME>  Filter by name
   275→  -t, --tag <TAG-TEXT>       Filter by tag
   276→  -m, --type <MACHINE-TYPE>  Filter by type
   277→  -r, --region <REGION>      Filter by region
   278→  -o, --output <FORMAT>      Output format (json)
   279→  --status-check <CHECK>     Status check to perform (default: cloud-init-status)
   280→  -q, --quiet                Only display machine IDs
   281→  --all                      Include all machines from all sessions
   282→  -h, --help                 Show this message and exit.
   283→```
   284→
   285→In addition to the DigitalOcean droplet status, this command queries each machine at `http://<ip>:4242/cgi-bin/<status-check>` (default: `cloud-init-status`) for custom status information. If the endpoint is unreachable, the status is reported as `UNKNOWN`.
   286→
   287→#### list-domain
   288→
   289→List DNS records within a domain zone.
   290→
   291→```
   292→$ machine list-domain --help
   293→Usage: machine list-domain [OPTIONS] [ZONE]
   294→
   295→  List domain records
   296→
   297→Options:
   298→  -n, --name <RECORD-NAME>  Filter by record name
   299→  -m, --type <RECORD-TYPE>  Filter by record type (default: A and AAAA, use * for all)
   300→  -o, --output <FORMAT>     Output format (json)
   301→  -q, --quiet               Only display record names
   302→  --all                     Include all records from all sessions
   303→  -h, --help                Show this message and exit.
   304→```
   305→
   306→If `ZONE` is omitted, uses the `dns-zone` from config. By default, only shows A and AAAA records associated with machines from the current session.
   307→
   308→Output formats:
   309→- Default: `name\ttype\tdata`
   310→- `--quiet`: record names only
   311→- `--output json`: JSON array with id, droplet info, name, fqdn, zone, data, ttl, type
   312→
   313→#### domains
   314→
   315→List all DNS domains in your DigitalOcean account. Takes no options.
   316→
   317→#### ssh-keys
   318→
   319→List SSH keys in your DigitalOcean account. Output format: `id: name (fingerprint)`
   320→
   321→#### projects
   322→
   323→List DigitalOcean project names. Takes no options.
   324→
   325→#### types
   326→
   327→List all machine types defined in the config file (from the `machines` section). Takes no options.
   328→

The file /home/david/projects/stirlingbridge/machine/README.md has been updated successfully.

The file /home/david/projects/stirlingbridge/machine/README.md has been updated successfully.

The file /home/david/projects/stirlingbridge/machine/README.md has been updated successfully.

The file /home/david/projects/stirlingbridge/machine/README.md has been updated successfully.

The file /home/david/projects/stirlingbridge/machine/README.md has been updated successfully.

The file /home/david/projects/stirlingbridge/machine/README.md has been updated successfully.

The file /home/david/projects/stirlingbridge/machine/README.md has been updated successfully.

The file /home/david/projects/stirlingbridge/machine/README.md has been updated successfully.

     1→# CLAUDE.md
     2→
     3→## Project Overview
     4→
     5→CLI tool (`machine`) for creating and managing VMs on DigitalOcean. Built with Python and Click, packaged as a single-file executable via shiv.
     6→
     7→- **Org**: Stirlingbridge (`github.com/stirlingbridge/machine`)
     8→- **License**: AGPL-3.0-only
     9→- **Python**: >=3.8 (CI builds on 3.8)
    10→
    11→## Tech Stack
    12→
    13→- **CLI framework**: Click 8.1.7
    14→- **Cloud provider**: python-digitalocean 1.17.0
    15→- **Config**: ruamel.yaml (reads `~/.machine/config.yml`)
    16→- **Build tooling**: uv (dependency management), hatchling (build backend), shiv (zipapp packaging)
    17→
    18→## Project Structure
    19→
    20→```
    21→machine/             # Main package
    22→  main.py            # Click group entry point
    23→  config.py          # Config file loading
    24→  di.py              # Dependency injection / globals
    25→  factory.py         # VM creation factory
    26→  cloud_config.py    # Cloud-init config generation
    27→  subcommands/       # Click subcommands (create, destroy, list, status, etc.)
    28→sh/                  # Shell scripts (build, lint, dev-setup)
    29→pyproject.toml       # Project metadata and dependencies
    30→```
    31→
    32→## Development Commands
    33→
    34→```bash
    35→uv sync                    # Install dependencies (creates .venv)
    36→uv run machine --help      # Run CLI in development
    37→uv run ruff check machine/ # Lint
    38→./sh/lint.sh --fix         # Auto-format with ruff, then lint
    39→./sh/build-package.sh      # Build shiv executable to build/machine
    40→make dev                   # Alias for uv sync
    41→make build                 # Alias for build-package.sh
    42→make lint                  # Alias for ruff check + format check
    43→```
    44→
    45→## Code Style
    46→
    47→- **Linter & Formatter**: ruff (line length 132, max complexity 25, E203 ignored)
    48→- Config in `pyproject.toml` under `[tool.ruff]`
    49→
    50→## CI/CD
    51→
    52→GitHub Actions workflow (`.github/workflows/build-release.yml`) builds a shiv package and publishes it as a GitHub release on push to `main`.
    53→

The file /home/david/projects/stirlingbridge/machine/CLAUDE.md has been updated successfully.

The file /home/david/projects/stirlingbridge/machine/CLAUDE.md has been updated successfully.

The file /home/david/projects/stirlingbridge/machine/CLAUDE.md has been updated successfully.

.............................                                            [100%]
29 passed, 6 deselected in 3.80s

     1→"""End-to-end tests that create real VMs on DigitalOcean.
     2→
     3→These tests require a real DigitalOcean environment and are NOT run as part of
     4→the normal test suite. They must be invoked explicitly:
     5→
     6→    uv run pytest tests/test_e2e.py -v
     7→
     8→Required environment variables:
     9→    E2E_DO_TOKEN    - DigitalOcean API token
    10→    E2E_SSH_KEY     - Name of an SSH key already registered in DO
    11→    E2E_DNS_ZONE    - DNS zone managed by DO (e.g. "test.example.com")
    12→    E2E_PROJECT     - DO project name to assign droplets to
    13→
    14→Optional environment variables:
    15→    E2E_REGION      - Region slug (default: nyc1)
    16→    E2E_IMAGE       - Image slug (default: ubuntu-24-04-x64)
    17→    E2E_SIZE        - Machine size slug (default: s-1vcpu-512mb-10gb)
    18→"""
    19→
    20→import json
    21→import os
    22→import subprocess
    23→import uuid
    24→
    25→import pytest
    26→
    27→
    28→# ---------------------------------------------------------------------------
    29→# Skip the entire module if credentials are not provided
    30→# ---------------------------------------------------------------------------
    31→
    32→E2E_DO_TOKEN = os.environ.get("E2E_DO_TOKEN")
    33→E2E_SSH_KEY = os.environ.get("E2E_SSH_KEY")
    34→E2E_DNS_ZONE = os.environ.get("E2E_DNS_ZONE")
    35→E2E_REGION = os.environ.get("E2E_REGION", "nyc1")
    36→E2E_IMAGE = os.environ.get("E2E_IMAGE", "ubuntu-24-04-x64")
    37→E2E_SIZE = os.environ.get("E2E_SIZE", "s-1vcpu-512mb-10gb")
    38→E2E_PROJECT = os.environ.get("E2E_PROJECT")
    39→
    40→pytestmark = pytest.mark.e2e
    41→
    42→_MISSING = []
    43→if not E2E_DO_TOKEN:
    44→    _MISSING.append("E2E_DO_TOKEN")
    45→if not E2E_SSH_KEY:
    46→    _MISSING.append("E2E_SSH_KEY")
    47→if not E2E_DNS_ZONE:
    48→    _MISSING.append("E2E_DNS_ZONE")
    49→if not E2E_PROJECT:
    50→    _MISSING.append("E2E_PROJECT")
    51→
    52→if _MISSING:
    53→    pytestmark = [
    54→        pytest.mark.e2e,
    55→        pytest.mark.skip(reason=f"E2E env vars not set: {', '.join(_MISSING)}"),
    56→    ]
    57→
    58→
    59→# ---------------------------------------------------------------------------
    60→# Helpers
    61→# ---------------------------------------------------------------------------
    62→
    63→
    64→def _unique_name(prefix="e2etest"):
    65→    """Generate a short unique droplet name safe for DNS."""
    66→    return f"{prefix}-{uuid.uuid4().hex[:8]}"
    67→
    68→
    69→def _write_config(path, **overrides):
    70→    """Write a minimal config file for the e2e test run."""
    71→    cfg = {
    72→        "access-token": E2E_DO_TOKEN,
    73→        "ssh-key": E2E_SSH_KEY,
    74→        "dns-zone": E2E_DNS_ZONE,
    75→        "machine-size": E2E_SIZE,
    76→        "image": E2E_IMAGE,
    77→        "region": E2E_REGION,
    78→    }
    79→    cfg["project"] = E2E_PROJECT
    80→    cfg.update(overrides)
    81→
    82→    do_lines = "\n".join(f"  {k}: {v}" for k, v in cfg.items())
    83→    content = f"digital-ocean:\n{do_lines}\nmachines:\n  e2e-basic:\n    new-user-name: e2euser\n"
    84→    with open(path, "w") as f:
    85→        f.write(content)
    86→
    87→
    88→def run_machine(*args, config_file=None, session_id=None):
    89→    """Run the machine CLI as a subprocess with the given arguments."""
    90→    cmd = ["uv", "run", "machine"]
    91→    if config_file:
    92→        cmd += ["--config-file", str(config_file)]
    93→    if session_id:
    94→        cmd += ["--session-id", session_id]
    95→    cmd += list(args)
    96→    result = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
    97→    return result
    98→
    99→
   100→def _extract_droplet_id(output_text):
   101→    """Extract the droplet ID from CLI output like 'New droplet created with id: 12345'."""
   102→    for line in output_text.splitlines():
   103→        if "id:" in line.lower():
   104→            parts = line.split("id:")
   105→            if len(parts) >= 2:
   106→                candidate = parts[-1].strip()
   107→                if candidate.isdigit():
   108→                    return candidate
   109→    return None
   110→
   111→
   112→# ---------------------------------------------------------------------------
   113→# Fixtures
   114→# ---------------------------------------------------------------------------
   115→
   116→
   117→@pytest.fixture(scope="module")
   118→def config_file(tmp_path_factory):
   119→    """Write a config file that lives for the whole test module."""
   120→    path = tmp_path_factory.mktemp("e2e") / "config.yml"
   121→    _write_config(path)
   122→    return path
   123→
   124→
   125→@pytest.fixture(scope="module")
   126→def session_id():
   127→    """A unique session id shared across all tests in this module."""
   128→    return uuid.uuid4().hex[:8]
   129→
   130→
   131→@pytest.fixture(scope="class")
   132→def droplet(config_file, session_id):
   133→    """Create a single droplet with all features and destroy it after all tests.
   134→
   135→    The droplet is created with DNS, a machine type (cloud-init), a custom tag,
   136→    and --wait-for-ip so that all aspects can be verified by individual tests.
   137→    """
   138→    name = _unique_name()
   139→    custom_tag = f"e2e-tag-{uuid.uuid4().hex[:6]}"
   140→
   141→    # ---- CREATE with all features ------------------------------------------
   142→    result = run_machine(
   143→        "create",
   144→        "--name",
   145→        name,
   146→        "--type",
   147→        "e2e-basic",
   148→        "--update-dns",
   149→        "--tag",
   150→        custom_tag,
   151→        "--wait-for-ip",
   152→        config_file=config_file,
   153→        session_id=session_id,
   154→    )
   155→    assert result.returncode == 0, f"create failed: {result.stderr}"
   156→    create_out = result.stdout + result.stderr
   157→    droplet_id = _extract_droplet_id(create_out)
   158→    assert droplet_id, f"Could not find droplet id in output:\n{create_out}"
   159→
   160→    info = {
   161→        "name": name,
   162→        "id": droplet_id,
   163→        "custom_tag": custom_tag,
   164→        "create_out": create_out,
   165→    }
   166→
   167→    yield info
   168→
   169→    # ---- TEARDOWN: destroy with DNS cleanup --------------------------------
   170→    run_machine(
   171→        "--verbose",
   172→        "destroy",
   173→        "--no-confirm",
   174→        "--delete-dns",
   175→        droplet_id,
   176→        config_file=config_file,
   177→        session_id=session_id,
   178→    )
   179→
   180→
   181→# ---------------------------------------------------------------------------
   182→# Tests — one droplet, many assertions
   183→# ---------------------------------------------------------------------------
   184→
   185→
   186→class TestDropletLifecycle:
   187→    """Create one droplet with all features and verify each aspect independently.
   188→
   189→    A single droplet is created (via the class-scoped ``droplet`` fixture) with
   190→    DNS, a machine type, and a custom tag.  Each test method verifies a different
   191→    aspect so that failures are reported individually.  The droplet is destroyed
   192→    automatically after all tests complete.
   193→    """
   194→
   195→    def test_droplet_appears_in_list(self, droplet, config_file, session_id):
   196→        """Verify the droplet shows up in ``list`` with the correct name."""
   197→        result = run_machine(
   198→            "list",
   199→            "--output",
   200→            "json",
   201→            config_file=config_file,
   202→            session_id=session_id,
   203→        )
   204→        assert result.returncode == 0, f"list failed: {result.stderr}"
   205→        droplets = json.loads(result.stdout)
   206→        matched = [d for d in droplets if str(d["id"]) == droplet["id"]]
   207→        assert len(matched) == 1, f"Expected 1 droplet with id {droplet['id']}, got {len(matched)}"
   208→        assert matched[0]["name"] == droplet["name"]
   209→
   210→    def test_droplet_has_ip(self, droplet, config_file, session_id):
   211→        """Verify the droplet was assigned an IP address."""
   212→        result = run_machine(
   213→            "list",
   214→            "--output",
   215→            "json",
   216→            config_file=config_file,
   217→            session_id=session_id,
   218→        )
   219→        assert result.returncode == 0
   220→        droplets = json.loads(result.stdout)
   221→        matched = [d for d in droplets if str(d["id"]) == droplet["id"]]
   222→        assert len(matched) == 1
   223→        assert matched[0]["ip"] is not None, "Droplet has no IP address"
   224→
   225→    def test_dns_record_created(self, droplet, config_file, session_id):
   226→        """Verify that a DNS A record was created for the droplet."""
   227→        result = run_machine(
   228→            "list-domain",
   229→            "--name",
   230→            droplet["name"],
   231→            "--output",
   232→            "json",
   233→            E2E_DNS_ZONE,
   234→            config_file=config_file,
   235→            session_id=session_id,
   236→        )
   237→        assert result.returncode == 0, f"list-domain failed: {result.stderr}"
   238→        records = json.loads(result.stdout)
   239→        a_records = [r for r in records if r.get("name") == droplet["name"] and r.get("type") == "A"]
   240→        assert len(a_records) >= 1, f"No A record found for {droplet['name']}.{E2E_DNS_ZONE}"
   241→
   242→    def test_dns_zone_in_create_output(self, droplet):
   243→        """Verify that DNS zone was mentioned in the create output."""
   244→        assert E2E_DNS_ZONE in droplet["create_out"], f"DNS zone not mentioned in output:\n{droplet['create_out']}"
   245→
   246→    def test_type_tag_applied(self, droplet, config_file, session_id):
   247→        """Verify that the machine type tag was applied and is filterable."""
   248→        result = run_machine(
   249→            "list",
   250→            "--type",
   251→            "e2e-basic",
   252→            "--output",
   253→            "json",
   254→            config_file=config_file,
   255→            session_id=session_id,
   256→        )
   257→        assert result.returncode == 0
   258→        droplets = json.loads(result.stdout)
   259→        matched = [d for d in droplets if str(d["id"]) == droplet["id"]]
   260→        assert len(matched) == 1, "Droplet not found when filtering by type e2e-basic"
   261→        assert matched[0]["type"] == "e2e-basic", "Type tag mismatch"
   262→
   263→    def test_custom_tag_applied(self, droplet, config_file, session_id):
   264→        """Verify that the custom tag was applied and is filterable."""
   265→        result = run_machine(
   266→            "list",
   267→            "--tag",
   268→            droplet["custom_tag"],
   269→            "--output",
   270→            "json",
   271→            config_file=config_file,
   272→            session_id=session_id,
   273→        )
   274→        assert result.returncode == 0
   275→        droplets = json.loads(result.stdout)
   276→        matched = [d for d in droplets if str(d["id"]) == droplet["id"]]
   277→        assert len(matched) == 1, f"Droplet not found with tag {droplet['custom_tag']}"
   278→

     1→name: Build and Release
     2→
     3→on:
     4→  push:
     5→    branches:
     6→      - main
     7→      - build-test
     8→
     9→jobs:
    10→  publish:
    11→    name: "Build and Release"
    12→    runs-on: ubuntu-latest
    13→    steps:
    14→      - name: "Clone project repository"
    15→        uses: actions/checkout@v4
    16→      - name: "Install uv"
    17→        uses: astral-sh/setup-uv@v4
    18→      - name: "Install Python"
    19→        run: uv python install 3.13
    20→      - name: "Get release tag"
    21→        id: release-tag
    22→        run: |
    23→          release_tag=$(./sh/make-release-tag.sh)
    24→          echo "release-tag=v${release_tag}" >> $GITHUB_OUTPUT
    25→      - name: "Build shiv package"
    26→        run: |
    27→          ./sh/build-package.sh
    28→      - name: "Upload package as a github release"
    29→        uses: softprops/action-gh-release@v2
    30→        with:
    31→          tag_name: ${{ steps.release-tag.outputs.release-tag }}
    32→          draft: ${{ endsWith('build-test', github.ref ) }}
    33→          files: ./build/machine
    34→

     1→"""Tests for graceful handling of invalid user input."""
     2→
     3→import os
     4→import subprocess
     5→import textwrap
     6→import pytest
     7→
     8→
     9→def run_machine(*args, env_override=None):
    10→    """Run the machine CLI as a subprocess and return the result."""
    11→    env = os.environ.copy()
    12→    if env_override:
    13→        env.update(env_override)
    14→    result = subprocess.run(
    15→        ["uv", "run", "machine"] + list(args),
    16→        capture_output=True,
    17→        text=True,
    18→        env=env,
    19→    )
    20→    return result
    21→
    22→
    23→def write_config(path, content):
    24→    with open(path, "w") as f:
    25→        f.write(textwrap.dedent(content))
    26→
    27→
    28→def valid_config():
    29→    return """\
    30→        digital-ocean:
    31→          access-token: fake-token
    32→          ssh-key: test-key
    33→          machine-size: s-1vcpu-1gb
    34→          image: ubuntu-22-04-x64
    35→          region: nyc1
    36→          project: test-project
    37→        machines:
    38→          web-server:
    39→            new-user-name: admin
    40→          db-server:
    41→            new-user-name: dbadmin
    42→        """
    43→
    44→
    45→class TestInvalidMachineType:
    46→    """Issue #29: invalid machine type should produce a graceful error, not a traceback."""
    47→
    48→    @pytest.fixture()
    49→    def config_dir(self, tmp_path):
    50→        return tmp_path
    51→
    52→    def test_invalid_machine_type_error_message(self, config_dir):
    53→        config_file = config_dir / "config.yml"
    54→        write_config(config_file, valid_config())
    55→        result = run_machine(
    56→            "--config-file",
    57→            str(config_file),
    58→            "create",
    59→            "-n",
    60→            "test-1",
    61→            "-m",
    62→            "nonexistent-type",
    63→            "--no-update-dns",
    64→        )
    65→        assert result.returncode != 0
    66→        assert "nonexistent-type" in result.stderr
    67→        assert "not found" in result.stderr.lower()
    68→        # Should list available types
    69→        assert "web-server" in result.stderr
    70→        assert "db-server" in result.stderr
    71→        # Should NOT be a traceback
    72→        assert "Traceback" not in result.stderr
    73→        assert "KeyError" not in result.stderr
    74→
    75→    def test_valid_machine_type_accepted(self, config_dir):
    76→        """Verify that a valid machine type doesn't produce an error about the type.
    77→        (It will fail later trying to reach DigitalOcean, but not with a type error.)"""
    78→        config_file = config_dir / "config.yml"
    79→        write_config(config_file, valid_config())
    80→        result = run_machine(
    81→            "--config-file",
    82→            str(config_file),
    83→            "create",
    84→            "-n",
    85→            "test-1",
    86→            "-m",
    87→            "web-server",
    88→            "--no-update-dns",
    89→        )
    90→        # It will fail (no real DO token), but NOT because of machine type
    91→        assert "not found in config" not in result.stderr
    92→
    93→
    94→class TestMissingConfigSections:
    95→    """Missing required config sections/keys should produce graceful errors."""
    96→
    97→    @pytest.fixture()
    98→    def config_dir(self, tmp_path):
    99→        return tmp_path
   100→
   101→    def test_missing_digital_ocean_section(self, config_dir):
   102→        config_file = config_dir / "config.yml"
   103→        write_config(
   104→            config_file,
   105→            """\
   106→            machines:
   107→              web-server:
   108→                new-user-name: admin
   109→            """,
   110→        )
   111→        result = run_machine("--config-file", str(config_file), "types")
   112→        assert result.returncode != 0
   113→        assert "digital-ocean" in result.stderr
   114→        assert "Traceback" not in result.stderr
   115→
   116→    def test_missing_access_token(self, config_dir):
   117→        config_file = config_dir / "config.yml"
   118→        write_config(
   119→            config_file,
   120→            """\
   121→            digital-ocean:
   122→              ssh-key: test-key
   123→              machine-size: s-1vcpu-1gb
   124→              image: ubuntu-22-04-x64
   125→              region: nyc1
   126→              project: test-project
   127→            machines:
   128→              web-server:
   129→                new-user-name: admin
   130→            """,
   131→        )
   132→        result = run_machine("--config-file", str(config_file), "types")
   133→        assert result.returncode != 0
   134→        assert "access-token" in result.stderr
   135→        assert "Traceback" not in result.stderr
   136→
   137→    def test_missing_ssh_key(self, config_dir):
   138→        config_file = config_dir / "config.yml"
   139→        write_config(
   140→            config_file,
   141→            """\
   142→            digital-ocean:
   143→              access-token: fake-token
   144→              machine-size: s-1vcpu-1gb
   145→              image: ubuntu-22-04-x64
   146→              region: nyc1
   147→              project: test-project
   148→            machines:
   149→              web-server:
   150→                new-user-name: admin
   151→            """,
   152→        )
   153→        result = run_machine("--config-file", str(config_file), "types")
   154→        assert result.returncode != 0
   155→        assert "ssh-key" in result.stderr
   156→        assert "Traceback" not in result.stderr
   157→
   158→    def test_missing_machines_section(self, config_dir):
   159→        config_file = config_dir / "config.yml"
   160→        write_config(
   161→            config_file,
   162→            """\
   163→            digital-ocean:
   164→              access-token: fake-token
   165→              ssh-key: test-key
   166→              machine-size: s-1vcpu-1gb
   167→              image: ubuntu-22-04-x64
   168→              region: nyc1
   169→              project: test-project
   170→            """,
   171→        )
   172→        result = run_machine("--config-file", str(config_file), "types")
   173→        assert result.returncode != 0
   174→        assert "machines" in result.stderr.lower()
   175→        assert "Traceback" not in result.stderr
   176→
   177→    def test_missing_new_user_name_in_machine(self, config_dir):
   178→        config_file = config_dir / "config.yml"
   179→        write_config(
   180→            config_file,
   181→            """\
   182→            digital-ocean:
   183→              access-token: fake-token
   184→              ssh-key: test-key
   185→              machine-size: s-1vcpu-1gb
   186→              image: ubuntu-22-04-x64
   187→              region: nyc1
   188→              project: test-project
   189→            machines:
   190→              broken-machine:
   191→                script-url: http://example.com/setup.sh
   192→            """,
   193→        )
   194→        result = run_machine(
   195→            "--config-file",
   196→            str(config_file),
   197→            "create",
   198→            "-n",
   199→            "test-1",
   200→            "-m",
   201→            "broken-machine",
   202→            "--no-update-dns",
   203→        )
   204→        assert result.returncode != 0
   205→        assert "new-user-name" in result.stderr
   206→        assert "Traceback" not in result.stderr
   207→
   208→
   209→class TestCreateNoInitialize:
   210→    """--no-initialize should work without a machine type and without crashing."""
   211→
   212→    @pytest.fixture()
   213→    def config_dir(self, tmp_path):
   214→        return tmp_path
   215→
   216→    def test_no_initialize_without_type_no_crash(self, config_dir):
   217→        """Using --no-initialize without --type should not crash with AttributeError or NameError."""
   218→        config_file = config_dir / "config.yml"
   219→        write_config(config_file, valid_config())
   220→        result = run_machine(
   221→            "--config-file",
   222→            str(config_file),
   223→            "create",
   224→            "-n",
   225→            "test-1",
   226→            "--no-initialize",
   227→            "--no-update-dns",
   228→        )
   229→        # It will fail (no real DO token), but should NOT crash with AttributeError/NameError
   230→        # from the bugs where user_data was undefined and type.lower() was called on None
   231→        assert "AttributeError" not in result.stderr
   232→        assert "NameError" not in result.stderr
   233→

/home/david/projects/stirlingbridge/machine/.github/workflows/build-release.yml
/home/david/projects/stirlingbridge/machine/.github/workflows/test.yml
/home/david/projects/stirlingbridge/machine/.github/workflows/e2e-test.yml

     1→name: Unit and Integration Test
     2→
     3→on:
     4→  push:
     5→    branches:
     6→      - main
     7→  pull_request:
     8→    branches:
     9→      - main
    10→
    11→jobs:
    12→  test:
    13→    name: "Run Tests"
    14→    runs-on: ubuntu-latest
    15→    steps:
    16→      - name: "Clone project repository"
    17→        uses: actions/checkout@v4
    18→      - name: "Install uv"
    19→        uses: astral-sh/setup-uv@v4
    20→      - name: "Install Python"
    21→        run: uv python install 3.13
    22→      - name: "Install dependencies"
    23→        run: uv sync
    24→      - name: "Run tests"
    25→        run: uv run pytest tests/ -v
    26→

     1→name: E2E Test
     2→
     3→on:
     4→  push:
     5→    branches: [main]
     6→  pull_request:
     7→    branches: [main]
     8→  workflow_dispatch:
     9→  schedule:
    10→    # Run weekly on Monday at 06:00 UTC
    11→    - cron: "0 6 * * 1"
    12→
    13→jobs:
    14→  e2e:
    15→    name: "End-to-End Tests"
    16→    runs-on: ubuntu-latest
    17→    environment: e2e
    18→    steps:
    19→      - name: "Clone project repository"
    20→        uses: actions/checkout@v4
    21→      - name: "Install uv"
    22→        uses: astral-sh/setup-uv@v4
    23→      - name: "Install Python"
    24→        run: uv python install 3.13
    25→      - name: "Install dependencies"
    26→        run: uv sync
    27→      - name: "Run E2E tests"
    28→        env:
    29→          E2E_DO_TOKEN: ${{ secrets.E2E_DO_TOKEN }}
    30→          E2E_SSH_KEY: ${{ vars.E2E_SSH_KEY }}
    31→          E2E_DNS_ZONE: ${{ vars.E2E_DNS_ZONE }}
    32→          E2E_PROJECT: ${{ vars.E2E_PROJECT }}
    33→        run: uv run pytest tests/test_e2e.py -v -m e2e
    34→

     1→"""End-to-end tests that create real VMs on DigitalOcean.
     2→
     3→These tests require a real DigitalOcean environment and are NOT run as part of
     4→the normal test suite. They must be invoked explicitly:
     5→
     6→    uv run pytest tests/test_e2e.py -v
     7→
     8→Required environment variables:
     9→    E2E_DO_TOKEN    - DigitalOcean API token
    10→    E2E_SSH_KEY     - Name of an SSH key already registered in DO
    11→    E2E_DNS_ZONE    - DNS zone managed by DO (e.g. "test.example.com")
    12→    E2E_PROJECT     - DO project name to assign droplets to
    13→
    14→Optional environment variables:
    15→    E2E_REGION      - Region slug (default: nyc1)
    16→    E2E_IMAGE       - Image slug (default: ubuntu-24-04-x64)
    17→    E2E_SIZE        - Machine size slug (default: s-1vcpu-512mb-10gb)
    18→"""
    19→
    20→import json
    21→import os
    22→import subprocess
    23→import uuid
    24→
    25→import pytest
    26→
    27→
    28→# ---------------------------------------------------------------------------
    29→# Skip the entire module if credentials are not provided
    30→# ---------------------------------------------------------------------------
    31→
    32→E2E_DO_TOKEN = os.environ.get("E2E_DO_TOKEN")
    33→E2E_SSH_KEY = os.environ.get("E2E_SSH_KEY")
    34→E2E_DNS_ZONE = os.environ.get("E2E_DNS_ZONE")
    35→E2E_REGION = os.environ.get("E2E_REGION", "nyc1")
    36→E2E_IMAGE = os.environ.get("E2E_IMAGE", "ubuntu-24-04-x64")
    37→E2E_SIZE = os.environ.get("E2E_SIZE", "s-1vcpu-512mb-10gb")
    38→E2E_PROJECT = os.environ.get("E2E_PROJECT")
    39→
    40→pytestmark = pytest.mark.e2e
    41→
    42→_MISSING = []
    43→if not E2E_DO_TOKEN:
    44→    _MISSING.append("E2E_DO_TOKEN")
    45→if not E2E_SSH_KEY:
    46→    _MISSING.append("E2E_SSH_KEY")
    47→if not E2E_DNS_ZONE:
    48→    _MISSING.append("E2E_DNS_ZONE")
    49→if not E2E_PROJECT:
    50→    _MISSING.append("E2E_PROJECT")
    51→
    52→if _MISSING:
    53→    pytestmark = [
    54→        pytest.mark.e2e,
    55→        pytest.mark.skip(reason=f"E2E env vars not set: {', '.join(_MISSING)}"),
    56→    ]
    57→
    58→
    59→# ---------------------------------------------------------------------------
    60→# Helpers
    61→# ---------------------------------------------------------------------------
    62→
    63→
    64→def _unique_name(prefix="e2etest"):
    65→    """Generate a short unique droplet name safe for DNS."""
    66→    return f"{prefix}-{uuid.uuid4().hex[:8]}"
    67→
    68→
    69→def _write_config(path, **overrides):
    70→    """Write a minimal config file for the e2e test run."""
    71→    cfg = {
    72→        "access-token": E2E_DO_TOKEN,
    73→        "ssh-key": E2E_SSH_KEY,
    74→        "dns-zone": E2E_DNS_ZONE,
    75→        "machine-size": E2E_SIZE,
    76→        "image": E2E_IMAGE,
    77→        "region": E2E_REGION,
    78→    }
    79→    cfg["project"] = E2E_PROJECT
    80→    cfg.update(overrides)
    81→
    82→    do_lines = "\n".join(f"  {k}: {v}" for k, v in cfg.items())
    83→    content = f"digital-ocean:\n{do_lines}\nmachines:\n  e2e-basic:\n    new-user-name: e2euser\n"
    84→    with open(path, "w") as f:
    85→        f.write(content)
    86→
    87→
    88→def run_machine(*args, config_file=None, session_id=None):
    89→    """Run the machine CLI as a subprocess with the given arguments."""
    90→    cmd = ["uv", "run", "machine"]
    91→    if config_file:
    92→        cmd += ["--config-file", str(config_file)]
    93→    if session_id:
    94→        cmd += ["--session-id", session_id]
    95→    cmd += list(args)
    96→    result = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
    97→    return result
    98→
    99→
   100→def _extract_droplet_id(output_text):
   101→    """Extract the droplet ID from CLI output like 'New droplet created with id: 12345'."""
   102→    for line in output_text.splitlines():
   103→        if "id:" in line.lower():
   104→            parts = line.split("id:")
   105→            if len(parts) >= 2:
   106→                candidate = parts[-1].strip()
   107→                if candidate.isdigit():
   108→                    return candidate
   109→    return None
   110→
   111→
   112→# ---------------------------------------------------------------------------
   113→# Fixtures
   114→# ---------------------------------------------------------------------------
   115→
   116→
   117→@pytest.fixture(scope="module")
   118→def config_file(tmp_path_factory):
   119→    """Write a config file that lives for the whole test module."""
   120→    path = tmp_path_factory.mktemp("e2e") / "config.yml"
   121→    _write_config(path)
   122→    return path
   123→
   124→
   125→@pytest.fixture(scope="module")
   126→def session_id():
   127→    """A unique session id shared across all tests in this module."""
   128→    return uuid.uuid4().hex[:8]
   129→
   130→
   131→@pytest.fixture(scope="class")
   132→def droplet(config_file, session_id):
   133→    """Create a single droplet with all features and destroy it after all tests.
   134→
   135→    The droplet is created with DNS, a machine type (cloud-init), a custom tag,
   136→    and --wait-for-ip so that all aspects can be verified by individual tests.
   137→    """
   138→    name = _unique_name()
   139→    custom_tag = f"e2e-tag-{uuid.uuid4().hex[:6]}"
   140→
   141→    # ---- CREATE with all features ------------------------------------------
   142→    result = run_machine(
   143→        "create",
   144→        "--name",
   145→        name,
   146→        "--type",
   147→        "e2e-basic",
   148→        "--update-dns",
   149→        "--tag",
   150→        custom_tag,
   151→        "--wait-for-ip",
   152→        config_file=config_file,
   153→        session_id=session_id,
   154→    )
   155→    assert result.returncode == 0, f"create failed: {result.stderr}"
   156→    create_out = result.stdout + result.stderr
   157→    droplet_id = _extract_droplet_id(create_out)
   158→    assert droplet_id, f"Could not find droplet id in output:\n{create_out}"
   159→
   160→    info = {
   161→        "name": name,
   162→        "id": droplet_id,
   163→        "custom_tag": custom_tag,
   164→        "create_out": create_out,
   165→    }
   166→
   167→    yield info
   168→
   169→    # ---- TEARDOWN: destroy with DNS cleanup --------------------------------
   170→    run_machine(
   171→        "--verbose",
   172→        "destroy",
   173→        "--no-confirm",
   174→        "--delete-dns",
   175→        droplet_id,
   176→        config_file=config_file,
   177→        session_id=session_id,
   178→    )
   179→
   180→
   181→# ---------------------------------------------------------------------------
   182→# Tests — one droplet, many assertions
   183→# ---------------------------------------------------------------------------
   184→
   185→
   186→class TestDropletLifecycle:
   187→    """Create one droplet with all features and verify each aspect independently.
   188→
   189→    A single droplet is created (via the class-scoped ``droplet`` fixture) with
   190→    DNS, a machine type, and a custom tag.  Each test method verifies a different
   191→    aspect so that failures are reported individually.  The droplet is destroyed
   192→    automatically after all tests complete.
   193→    """
   194→
   195→    def test_droplet_appears_in_list(self, droplet, config_file, session_id):
   196→        """Verify the droplet shows up in ``list`` with the correct name."""
   197→        result = run_machine(
   198→            "list",
   199→            "--output",
   200→            "json",
   201→            config_file=config_file,
   202→            session_id=session_id,
   203→        )
   204→        assert result.returncode == 0, f"list failed: {result.stderr}"
   205→        droplets = json.loads(result.stdout)
   206→        matched = [d for d in droplets if str(d["id"]) == droplet["id"]]
   207→        assert len(matched) == 1, f"Expected 1 droplet with id {droplet['id']}, got {len(matched)}"
   208→        assert matched[0]["name"] == droplet["name"]
   209→
   210→    def test_droplet_has_ip(self, droplet, config_file, session_id):
   211→        """Verify the droplet was assigned an IP address."""
   212→        result = run_machine(
   213→            "list",
   214→            "--output",
   215→            "json",
   216→            config_file=config_file,
   217→            session_id=session_id,
   218→        )
   219→        assert result.returncode == 0
   220→        droplets = json.loads(result.stdout)
   221→        matched = [d for d in droplets if str(d["id"]) == droplet["id"]]
   222→        assert len(matched) == 1
   223→        assert matched[0]["ip"] is not None, "Droplet has no IP address"
   224→
   225→    def test_dns_record_created(self, droplet, config_file, session_id):
   226→        """Verify that a DNS A record was created for the droplet."""
   227→        result = run_machine(
   228→            "list-domain",
   229→            "--name",
   230→            droplet["name"],
   231→            "--output",
   232→            "json",
   233→            E2E_DNS_ZONE,
   234→            config_file=config_file,
   235→            session_id=session_id,
   236→        )
   237→        assert result.returncode == 0, f"list-domain failed: {result.stderr}"
   238→        records = json.loads(result.stdout)
   239→        a_records = [r for r in records if r.get("name") == droplet["name"] and r.get("type") == "A"]
   240→        assert len(a_records) >= 1, f"No A record found for {droplet['name']}.{E2E_DNS_ZONE}"
   241→
   242→    def test_dns_zone_in_create_output(self, droplet):
   243→        """Verify that DNS zone was mentioned in the create output."""
   244→        assert E2E_DNS_ZONE in droplet["create_out"], f"DNS zone not mentioned in output:\n{droplet['create_out']}"
   245→
   246→    def test_type_tag_applied(self, droplet, config_file, session_id):
   247→        """Verify that the machine type tag was applied and is filterable."""
   248→        result = run_machine(
   249→            "list",
   250→            "--type",
   251→            "e2e-basic",
   252→            "--output",
   253→            "json",
   254→            config_file=config_file,
   255→            session_id=session_id,
   256→        )
   257→        assert result.returncode == 0
   258→        droplets = json.loads(result.stdout)
   259→        matched = [d for d in droplets if str(d["id"]) == droplet["id"]]
   260→        assert len(matched) == 1, "Droplet not found when filtering by type e2e-basic"
   261→        assert matched[0]["type"] == "e2e-basic", "Type tag mismatch"
   262→
   263→    def test_custom_tag_applied(self, droplet, config_file, session_id):
   264→        """Verify that the custom tag was applied and is filterable."""
   265→        result = run_machine(
   266→            "list",
   267→            "--tag",
   268→            droplet["custom_tag"],
   269→            "--output",
   270→            "json",
   271→            config_file=config_file,
   272→            session_id=session_id,
   273→        )
   274→        assert result.returncode == 0
   275→        droplets = json.loads(result.stdout)
   276→        matched = [d for d in droplets if str(d["id"]) == droplet["id"]]
   277→        assert len(matched) == 1, f"Droplet not found with tag {droplet['custom_tag']}"
   278→

     1→import click
     2→import time
     3→from machine.config import get_machine
     4→from machine.di import d
     5→from machine.log import fatal_error, info, debug, output
     6→from machine.types import MainCmdCtx, TAG_MACHINE_CREATED, TAG_MACHINE_TYPE_PREFIX
     7→from machine.cloud_config import get_user_data
     8→
     9→from machine.types import TAG_MACHINE_SESSION_PREFIX
    10→
    11→
    12→@click.command(help="Create a machine")
    13→@click.option("--name", "-n", required=True, metavar="<MACHINE-NAME>", help="Name for new machine")
    14→@click.option("--tag", "-t", metavar="<TAG-TEXT>", help="tag to be applied to new machine")
    15→@click.option("--type", "-m", metavar="<MACHINE-TYPE>", help="create a machine of this type")
    16→@click.option("--region", "-r", metavar="<REGION-CODE>", help="create a machine in this region (overrides default from config)")
    17→@click.option(
    18→    "--machine-size", "-s", metavar="<MACHINE-SLUG>", help="create a machine of this size (overrides default from config)"
    19→)
    20→@click.option("--image", "-s", metavar="<IMAGE-NAME>", help="create a machine from this image (overrides default from config)")
    21→@click.option("--wait-for-ip/--no-wait-for-up", default=False)
    22→@click.option("--update-dns/--no-update-dns", default=True)
    23→@click.option("--initialize/--no-initialize", default=True)
    24→@click.pass_context
    25→def command(context, name, tag, type, region, machine_size, image, wait_for_ip, update_dns, initialize):
    26→    command_context: MainCmdCtx = context.obj
    27→    config = command_context.config
    28→    provider = command_context.provider
    29→
    30→    if update_dns and not config.dns_zone:
    31→        fatal_error("Error: DNS update requested but no zone configured")
    32→
    33→    user_data = None
    34→    if initialize:
    35→        if not type:
    36→            fatal_error("Error: a machine type must be supplied")
    37→        machine_config = get_machine(type)
    38→        if not machine_config:
    39→            fatal_error(f"Error: machine type {type} is not defined")
    40→        fqdn = f"{name}.{config.dns_zone}" if config.dns_zone else None
    41→        user_data = get_user_data(provider, config.ssh_key, fqdn, machine_config)
    42→        if d.opt.debug:
    43→            info("user-data is:")
    44→            info(user_data)
    45→
    46→    # Verify SSH key exists
    47→    ssh_key = provider.get_ssh_key(config.ssh_key)
    48→    if not ssh_key:
    49→        fatal_error(f"Error: SSH key '{config.ssh_key}' not found in {provider.provider_name}")
    50→
    51→    provider.validate_region(region)
    52→    provider.validate_image(image)
    53→
    54→    tags = [
    55→        TAG_MACHINE_SESSION_PREFIX + command_context.session_id,
    56→        TAG_MACHINE_CREATED,
    57→    ]
    58→    if type:
    59→        tags.append(TAG_MACHINE_TYPE_PREFIX + type.lower())
    60→    if tag:
    61→        tags.append(tag)
    62→
    63→    vm = provider.create_vm(
    64→        name=name,
    65→        region=region if region is not None else config.region,
    66→        image=image if image is not None else config.image,
    67→        size=machine_size if machine_size is not None else config.machine_size,
    68→        ssh_key_name=config.ssh_key,
    69→        tags=tags,
    70→        user_data=user_data,
    71→    )
    72→
    73→    if vm.id:
    74→        if d.opt.quiet:
    75→            output(f"{vm.id}")
    76→        else:
    77→            output(f"New droplet created with id: {vm.id}")
    78→
    79→    # If requested, assign to a specified project
    80→    if config.project:
    81→        provider.assign_to_project(config.project, vm.id)
    82→        if d.opt.verbose:
    83→            info(f"Assigned droplet to project: {config.project}")
    84→
    85→    # If requested, or if we are going to set a DNS record get the VM's IPv4 address
    86→    ip_address = vm.ip_address
    87→    if (wait_for_ip or update_dns) and not ip_address:
    88→        while not ip_address:
    89→            time.sleep(1)
    90→            vm = provider.get_vm(vm.id)
    91→            ip_address = vm.ip_address
    92→            if d.opt.verbose:
    93→                output("Waiting for droplet IP address")
    94→        if d.opt.quiet:
    95→            info(f"{ip_address}")
    96→        else:
    97→            info(f"IP Address: {ip_address}")
    98→
    99→    # If requested, and we have the IP address, create a DNS host record
   100→    if update_dns and ip_address and config.dns_zone:
   101→        zone = config.dns_zone
   102→        host = name
   103→        if d.opt.debug:
   104→            debug(f"Setting host record {host}.{zone} to {ip_address}")
   105→        record = provider.create_dns_record(
   106→            zone=zone,
   107→            record_type="A",
   108→            name=host,
   109→            data=ip_address,
   110→            ttl=60 * 5,
   111→            tag=TAG_MACHINE_CREATED,
   112→        )
   113→        if record:
   114→            if d.opt.verbose:
   115→                info(f"Created DNS record:{record}")
   116→            if not d.opt.quiet:
   117→                info(f"DNS: {host}.{zone}")
   118→

12:    E2E_PROJECT     - DO project name to assign droplets to
38:E2E_PROJECT = os.environ.get("E2E_PROJECT")
49:if not E2E_PROJECT:
50:    _MISSING.append("E2E_PROJECT")
79:    cfg["project"] = E2E_PROJECT

The file /home/david/projects/stirlingbridge/machine/tests/test_e2e.py has been updated successfully.

The file /home/david/projects/stirlingbridge/machine/.github/workflows/e2e-test.yml has been updated successfully.

The file /home/david/projects/stirlingbridge/machine/tests/test_input_validation.py has been updated successfully.

============================= test session starts ==============================
platform linux -- Python 3.12.3, pytest-9.0.2, pluggy-1.6.0 -- /home/david/projects/stirlingbridge/machine/.venv/bin/python
cachedir: .pytest_cache
rootdir: /home/david/projects/stirlingbridge/machine
configfile: pyproject.toml
collecting ... collected 35 items / 6 deselected / 29 selected

tests/test_cli_integration.py::TestVersionCommand::test_version_runs PASSED [  3%]
tests/test_cli_integration.py::TestVersionCommand::test_help_runs PASSED [  6%]
tests/test_cli_integration.py::TestEnvVarExpansionIntegration::test_env_var_expanded_in_config PASSED [ 10%]
tests/test_cli_integration.py::TestEnvVarExpansionIntegration::test_multiple_env_vars_expanded PASSED [ 13%]
tests/test_cli_integration.py::TestEnvVarExpansionIntegration::test_env_var_with_default_uses_default_when_unset PASSED [ 17%]
tests/test_cli_integration.py::TestEnvVarExpansionIntegration::test_env_var_with_default_uses_value_when_set PASSED [ 20%]
tests/test_cli_integration.py::TestEnvVarExpansionIntegration::test_missing_env_var_without_default_exits_with_error PASSED [ 24%]
tests/test_cli_integration.py::TestEnvVarExpansionIntegration::test_env_var_in_machine_config_section PASSED [ 27%]
tests/test_config.py::TestExpandEnvVars::test_plain_string_unchanged PASSED [ 31%]
tests/test_config.py::TestExpandEnvVars::test_non_string_types_unchanged PASSED [ 34%]
tests/test_config.py::TestExpandEnvVars::test_simple_variable_substitution PASSED [ 37%]
tests/test_config.py::TestExpandEnvVars::test_variable_embedded_in_string PASSED [ 41%]
tests/test_config.py::TestExpandEnvVars::test_multiple_variables_in_string PASSED [ 44%]
tests/test_config.py::TestExpandEnvVars::test_default_value_when_var_unset PASSED [ 48%]
tests/test_config.py::TestExpandEnvVars::test_default_value_ignored_when_var_set PASSED [ 51%]
tests/test_config.py::TestExpandEnvVars::test_default_value_empty_string PASSED [ 55%]
tests/test_config.py::TestExpandEnvVars::test_unset_variable_without_default_exits PASSED [ 58%]
tests/test_config.py::TestExpandEnvVars::test_dict_values_expanded PASSED [ 62%]
tests/test_config.py::TestExpandEnvVars::test_nested_dict_expanded PASSED [ 65%]
tests/test_config.py::TestExpandEnvVars::test_list_values_expanded PASSED [ 68%]
tests/test_config.py::TestExpandEnvVars::test_mixed_nested_structure PASSED [ 72%]
tests/test_input_validation.py::TestInvalidMachineType::test_invalid_machine_type_error_message PASSED [ 75%]
tests/test_input_validation.py::TestInvalidMachineType::test_valid_machine_type_accepted PASSED [ 79%]
tests/test_input_validation.py::TestMissingConfigSections::test_missing_provider_section PASSED [ 82%]
tests/test_input_validation.py::TestMissingConfigSections::test_missing_access_token PASSED [ 86%]
tests/test_input_validation.py::TestMissingConfigSections::test_missing_ssh_key PASSED [ 89%]
tests/test_input_validation.py::TestMissingConfigSections::test_missing_machines_section PASSED [ 93%]
tests/test_input_validation.py::TestMissingConfigSections::test_missing_new_user_name_in_machine PASSED [ 96%]
tests/test_input_validation.py::TestCreateNoInitialize::test_no_initialize_without_type_no_crash PASSED [100%]

======================= 29 passed, 6 deselected in 3.86s =======================

All checks passed!

     1→# End-to-End Tests
     2→
     3→These tests verify that `machine` can create and manage real VMs on DigitalOcean, including DNS record lifecycle. They are **not** run as part of the normal test suite due to cost and runtime.
     4→
     5→## Prerequisites
     6→
     7→You need a DigitalOcean account with:
     8→
     9→- An API token with the required permissions (see below)
    10→- An SSH key registered in the account
    11→- A DNS zone managed by DigitalOcean (e.g. `test.example.com`)
    12→
    13→### API Token Permissions
    14→
    15→The DigitalOcean API token must be a **custom token** with these scopes enabled:
    16→
    17→| Scope | Access | Used for |
    18→|---|---|---|
    19→| `droplet` | read, create, delete | Creating, listing, and destroying test droplets |
    20→| `ssh_key` | read | Looking up SSH keys by name |
    21→| `domain` | read, create, delete | Creating and removing DNS A records |
    22→| `project` | read, update | Listing projects and assigning droplets to them |
    23→| `tag` | read, create | Tagging droplets by type and custom tags |
    24→
    25→A full-access read/write token will also work, but a scoped token is recommended.
    26→
    27→## Environment Variables
    28→
    29→| Variable | Required | Description |
    30→|---|---|---|
    31→| `E2E_DO_TOKEN` | Yes | DigitalOcean API token |
    32→| `E2E_SSH_KEY` | Yes | Name of an SSH key in your DO account |
    33→| `E2E_DNS_ZONE` | Yes | DO-managed DNS zone for test records |
    34→| `E2E_PROJECT` | Yes | DO project to assign droplets to |
    35→| `E2E_REGION` | No | Region slug (default: `nyc1`) |
    36→| `E2E_IMAGE` | No | Image slug (default: `ubuntu-24-04-x64`) |
    37→| `E2E_SIZE` | No | Droplet size (default: `s-1vcpu-512mb-10gb`) |
    38→
    39→## Running
    40→
    41→```bash
    42→# Set credentials
    43→export E2E_DO_TOKEN="dop_v1_..."
    44→export E2E_SSH_KEY="my-ssh-key"
    45→export E2E_DNS_ZONE="test.example.com"
    46→export E2E_PROJECT="my-project"
    47→
    48→# Run e2e tests
    49→make test-e2e
    50→
    51→# Or directly
    52→uv run pytest tests/test_e2e.py -v -m e2e
    53→```
    54→
    55→The normal `make test` (and CI) will **skip** these tests automatically.
    56→
    57→## What's Tested
    58→
    59→- **Droplet lifecycle** — create, list, destroy, verify removal
    60→- **DNS lifecycle** — create with `--update-dns`, verify A record, destroy with `--delete-dns`, verify record removal
    61→- **Cloud-init initialization** — create with `--type`, verify type tag
    62→- **Custom tags** — create with `--tag`, verify tag filtering
    63→
    64→## Cleanup
    65→
    66→Each test cleans up after itself. A safety fixture also destroys any leftover droplets if a test fails mid-run. All test droplets use unique names prefixed with `e2etest-` so they are easy to identify.
    67→
    68→## Cost
    69→
    70→Tests use the smallest available droplet size (`s-1vcpu-512mb-10gb`) and destroy VMs immediately after verification, so cost is minimal.
    71→

The file /home/david/projects/stirlingbridge/machine/tests/E2E.md has been updated successfully.