---
name: list-proxmox-images
version: 1.0.0
description: Unified listing of all bootable content across storages — LXC templates, cloud-init images, and install ISOs — with kind and readiness annotation
tags: [proxmox, images, templates, iso, api, shell]
---

# List Proxmox Images

Assumes `my_auth`, `my_base_url`, `my_curl` are set (see `auth-proxmox-api` skill).

## Storage Content Endpoints

```
GET /api2/json/nodes/{node}/storage                              # list storages + content types
GET /api2/json/nodes/{node}/storage/{storage}/content           # list content in a storage
GET /api2/json/nodes/{node}/storage/{storage}/content?content=vztmpl   # LXC templates only
GET /api2/json/nodes/{node}/storage/{storage}/content?content=iso      # ISOs only
GET /api2/json/nodes/{node}/storage/{storage}/content?content=images   # disk images only
```

Content response fields: `volid`, `content`, `format`, `size` (bytes), `ctime`.

## Kind and Readiness Classification

| Proxmox content type | kind | ready | notes |
|----------------------|------|-------|-------|
| `vztmpl` | `lxc-template` | yes | Boots immediately, no install |
| `images` | `cloud-image` | yes | Needs cloud-init user/key/IP config at create time |
| `iso` | `iso` | no | Requires OS installation before usable |

## List All Images (Unified TSV)

Queries every storage on the target node for all three content types and merges output.

```sh
fn_images_list() { (
    my_node="${1:-${PROXMOX_TARGET_NODE}}"

    # Get storages that carry relevant content types
    my_storages="$(
        ${my_curl} -H "${my_auth}" "${my_base_url}/nodes/${my_node}/storage" |
            jq -r '.data[] | select(.content | test("vztmpl|iso|images")) | .storage'
    )"

    printf 'volid\tkind\tready\tformat\tsize_gb\n'

    printf '%s\n' "${my_storages}" | while read -r b_storage; do
        for b_ctype in vztmpl iso images; do
            ${my_curl} -H "${my_auth}" \
                "${my_base_url}/nodes/${my_node}/storage/${b_storage}/content?content=${b_ctype}" |
                jq -r --arg ctype "${b_ctype}" '
                    .data[] |
                    (
                        if $ctype == "vztmpl" then "lxc-template"
                        elif $ctype == "iso"   then "iso"
                        else "cloud-image"
                        end
                    ) as $kind |
                    (if $kind == "iso" then "no" else "yes" end) as $ready |
                    (.size / 1073741824 * 100 | round / 100) as $gb |
                    [.volid, $kind, $ready, .format, ($gb | tostring)] | @tsv
                ' 2>/dev/null || true
        done
    done
); }
```

## Filter by Kind

```sh
# LXC templates only
fn_images_list | awk -F'\t' '$2 == "lxc-template"'

# Ready-to-go only (templates + cloud images)
fn_images_list | awk -F'\t' '$3 == "yes"'

# ISOs only
fn_images_list | awk -F'\t' '$2 == "iso"'
```

## List from All Nodes

When storage is local (not shared), images may differ per node. Query each node:

```sh
fn_images_list_cluster() { (
    my_nodes="$(
        ${my_curl} -H "${my_auth}" "${my_base_url}/nodes" |
            jq -r '.data[].node'
    )"

    printf 'node\tvolid\tkind\tready\tformat\tsize_gb\n'

    printf '%s\n' "${my_nodes}" | while read -r b_node; do
        fn_images_list "${b_node}" | tail -n +2 | sed "s/^/${b_node}\t/"
    done
); }
```

## Notes

- `volid` is the value to pass as `ostemplate` (CT) or `iso`/`scsi0` import source (VM).
- `cloud-image` entries in the `images` content type are assumed ready for cloud-init use.
  If a storage holds raw data disks (not bootable), filter them out by format or filename.
- `size` from the API is in bytes; displayed here as GB rounded to 2 decimal places.
- For CT templates, also see `docs/ct-os-templates.md` for alias → volid mapping.