Yet Another CLI (not) – vcautils

In the last year or so I have focused primarily on vCloud Air API and Automation. As a mere exercise I have been working on some code that I am making available today:

In the README on Github you can read everything about it, so I am not going to repeat myself (too much) in this blog post.

I just want to make it very clear that this tool is a toy, an experiment, a learning exercise and something I have been using when I was too bored to use a web browser REST plugin to navigate the API structure of vCloud Air. I also would like to use this as a basis for future experiments (and learning exercises) around CI / CD workflows.

This tool isn’t meant to be something that hides the API complexity richness, rather, it’s meant to expose that complexity richness. For education purposes if you will. In this sense, no it’s not YACLI (Yet Another CLI).

I often describe the vCloud Air architecture as a mix of loosely coupled platforms and services. The platform(s) is what provides things such as authentication, service discovery, metering, billing. The services are the actual cloud services that a user is interested in consuming (e.g. Compute, Object Storage, DBaaS, etc). This is how I picture the architecture of the service:

And this is how I built the vcautils tool-set:

I wanted it to be a reference for how you could build code that has either:

  • a 1:1 reference to platforms and/or services (e.g. the CLIs)

  • a 1:many reference to platforms and/or services such as an app that blends all of those together (e.g. the Sinatra app).

The tool is written in Ruby and it provides back-end libraries for the front end consumers (that are the CLIs and the Sinatra app). The back-end libraries aren’t general purpose and are not higher abstractions (so I discourage people to use them as an “SDK”). They are just meant to map the raw REST API calls.

This is an output example of the Sinatra sample application (which is available both on GitHub or online at http://

I strongly suggest you read (and see more pictures!) in the README file on GitHub in its entirety to get a better idea of the nature of this tool:

I strongly suggest you read carefully the Technical Background section in the end if you want to understand more about the vCloud Air architecture and its API consumption principles.

I do not expect heavy usage nor external contribution but if you have any comments and/or ideas feel free to let me know.


2 comments to Yet Another CLI (not) – vcautils

  • davide

    Hi Massimo, very interesting stuff!
    BTW as I cant find an answer anywhere else, maybe you can point me out to the right direction:

    do you know if the Vcloud Director API query service / vcloud air can return additional object properties apart from the default ones?
    Ex. if I query vcloud for all my vapps in records

    I will get a record of type QueryResultAdminVAppRecordType for each Vapp.
    These objects will contain only a small amount of the AdminVapp object properties (as listed here

    If I need another property of my vapps is there a way I can get it directly using the wuery service or am I obliged to call an API for each object to get it?
    If I have thousands of vapps this is really going to be slow, otherwise a single api call will suffice.

    Hope to hear from you!


    • Massimo

      Good question. AFAIK there is no way to extend a packaged query to extract a property value that isn’t packages with the out of the box query. So if you need a non provided property then yes you have to query the single vApp. I understand your concerns in doing so.

      I will run this question against a few other folks to see if they have a different view.

Leave a Reply

You can use these HTML tags

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>