| name | inventory-tool-guide |
| description | Guide for querying MTV provider inventory with TSL. Covers available resources per provider, output formats, TSL syntax, common pitfalls, and using inventory for network/storage mapping. Use when querying provider inventory. |
Inventory Tool Guide
Use mtv_read with get inventory RESOURCE to query provider inventory. Use mtv_help for unfamiliar commands.
For field references and ready-to-use queries, load the appropriate per-provider skill:
inventory-vsphere, inventory-ovirt, inventory-openstack, inventory-ec2, inventory-ova, inventory-hyperv, inventory-openshift.
Common Pitfalls
flags must be a JSON object — never pass it as a string.
- Correct:
"flags": {"namespace": "mtv", "output": "markdown"}
- Wrong:
"flags": "{namespace: mtv, output: markdown}"
fields is a top-level parameter, not a flag — use it on mtv_read directly (not inside flags) to limit response to specific top-level JSON keys (e.g. fields: ["metadata", "spec"]). Run mtv_help to see valid flags.- Discovering fields — use
"output": "json" with "query": "limit 1" to inspect one object and see all available field names.
- oVirt disk types live on a standalone resource — query
get inventory disk, not the VM's diskAttachments, to find storageType = 'lun'.
- EC2 and OVA use PascalCase field names — unlike vSphere/oVirt/OpenStack which use camelCase.
Provider Field Differences
| Concept | vSphere | oVirt | OpenStack | EC2 | OVA | HyperV | OpenShift |
|---|
| Power | powerState | status | status | State.Name | N/A | powerState | N/A (k8s) |
| Memory | memoryMB | memory (bytes!) | via flavorId | via InstanceType | memoryMB | memoryMB | N/A (k8s) |
| CPU | cpuCount | cpuSockets * cpuCores | via flavorId | via InstanceType | cpuCount | cpuCount | N/A (k8s) |
| Disks on VM | disks[*] | diskAttachments[*] | attachedVolumes[*] | BlockDeviceMappings | disks[*] | disks[*] | N/A |
| Standalone | N/A | get inventory disk | get inventory volume | get inventory volume | get inventory disk | get inventory disk | get inventory pvc |
| LUN/RDM | disks[*].rdm | disk.storageType + lunStorage | N/A | N/A | N/A | N/A | N/A |
| Field case | camelCase | camelCase | camelCase | PascalCase (AWS) | PascalCase (OVF) | camelCase | k8s objects |
Resource Availability Matrix
| Resource | vSphere | oVirt | OpenStack | EC2 | OVA | HyperV | OpenShift |
|---|
| vm | Y | Y | Y | Y (ec2-instance) | Y | Y | Y |
| network | Y | Y | Y | Y (ec2-network) | Y | Y | Y (NAD) |
| storage | Y (datastore) | Y (storageDomain) | Y (volumeType) | Y (ec2-volume-type) | Y | Y | Y (storageClass) |
| disk | -- | Y | -- | -- | Y | Y | -- |
| volume | -- | -- | Y | Y (ec2-volume) | -- | -- | -- |
| host | Y | Y | -- | -- | -- | -- | -- |
| cluster | Y | Y | -- | -- | -- | -- | -- |
| datacenter | Y | Y | -- | -- | -- | -- | -- |
| folder | Y | -- | -- | -- | -- | -- | -- |
| resource-pool | Y | -- | -- | -- | -- | -- | -- |
| disk-profile | -- | Y | -- | -- | -- | -- | -- |
| nic-profile | -- | Y | -- | -- | -- | -- | -- |
| flavor | -- | -- | Y | -- | -- | -- | -- |
| image | -- | -- | Y | -- | -- | -- | -- |
| project | -- | -- | Y | -- | -- | -- | -- |
| subnet | -- | -- | Y | -- | -- | -- | -- |
| snapshot | -- | -- | Y | -- | -- | -- | -- |
| volumetype | -- | -- | Y | -- | -- | -- | -- |
| namespace | -- | -- | -- | -- | -- | -- | Y |
| pvc | -- | -- | -- | -- | -- | -- | Y |
| data-volume | -- | -- | -- | -- | -- | -- | Y |
Output Formats
| Format | Use when |
|---|
markdown | Presenting results to the user (default). |
json | Parsing results or discovering fields. |
table | Compact display. |
yaml | Structured output. |
planvms | Export for create plan --vms @file. |
TSL Query Syntax
Use the query flag to filter, sort, and project results. use pipe output to jq, grep, or other post-processing tools only in cases --query does not handle.
The query flag handles filtering, field selection, sorting, and limiting natively.
TSL (Tree Search Language) supports four optional clauses, in this order:
[select <field>, ...] [where <condition>] [order by <field> [asc|desc]] [limit N]
All clauses are optional and can be combined freely.
select -- choose which fields to return
Use select to project only the fields you need (like SQL SELECT):
select name, cpuCount, memoryMB
select name, powerState, len(disks) as diskCount
select name, disks[*].capacity as diskSizes
where -- filter rows
where name ~= 'prod-.*'
where powerState = 'poweredOn' and memoryMB > 4096
where cpuCount > 4 and len(disks) > 1
where any(concerns[*].category = 'Critical')
where name in ['vm1', 'vm2', 'vm3']
where memoryMB between 2048 and 8192
where not (powerState = 'poweredOff')
where name is not null
order by -- sort results
order by name asc
order by memoryMB desc
order by cpuCount desc
limit -- cap the number of results
limit 10
limit 5
Combining clauses
select name, cpuCount, memoryMB where powerState = 'poweredOn' order by memoryMB desc limit 10
where name like '%web%' order by memoryMB desc limit 10
select name, powerState where cpuCount > 4 order by name asc
where memoryMB > 4096 limit 5
select name where any(concerns[*].category = 'Critical') order by name asc limit 20
Operators
- Comparison:
=, !=, <>, <, <=, >, >=
- String:
like (% wildcard), ilike (case-insensitive), ~= (regex), ~! (regex not)
- Logical:
and, or, not
- Set:
in [...], not in [...], between X and Y
- Null:
is null, is not null
Array Functions
len(field) -- array length: where len(disks) > 1any(field[*].sub = 'val') -- any element matches: where any(concerns[*].category = 'Critical')all(field[*].sub >= N) -- all elements matchsum(field[*].sub) -- sum of values: where sum(disks[*].capacity) > 100Gi
Array Access
field[0] -- index accessfield[*].sub -- wildcard across elementsfield.sub -- implicit traversal (same as field[*].sub)
SI Units
Ki (1024), Mi (1024^2), Gi (1024^3), Ti (1024^4)
Using Inventory for Mapping
Network mapping
- List source networks:
get inventory network with source provider
- List target NADs:
get inventory network with provider: "host"
- Match by name, use in
create mapping network
mtv_read { "command": "get inventory network", "flags": { "provider": "<SOURCE>", "namespace": "<NS>", "output": "json" } }
Storage mapping
- List source datastores:
get inventory datastore with source provider
- List target StorageClasses:
get inventory storage with provider: "host"
- Match by name, use in
create mapping storage
mtv_read { "command": "get inventory datastore", "flags": { "provider": "<SOURCE>", "namespace": "<NS>", "output": "json" } }
