0.27.0 • Public • Published


Package Version License PackagePhobia Node compatibility

Basic CLI for Xen-Orchestra


Installation of the npm package:

npm install --global xo-cli


> xo-cli --help

  xo-cli --register [--allowUnauthorized] [--expiresIn <duration>] [--otp <otp>] <XO-Server URL> <username> [<password>]
  xo-cli --register [--allowUnauthorized] [--expiresIn <duration>] --token <token> <XO-Server URL>
    Registers the XO instance to use.

    --allowUnauthorized, --au
      Accept invalid certificate (e.g. self-signed).

    --expiresIn <duration>
      Can be used to change the validity duration of the
      authorization token (default: one month).

    --otp <otp>
      One-time password if required for this user.

    --token <token>
      An authentication token to use instead of username/password.

  xo-cli --createToken <params>…
    Create an authentication token for XO API.

      Accept the same parameters as --register, see its usage.

  xo-cli --unregister
    Remove stored credentials.

  xo-cli --list-commands [--json] [<pattern>]...
    Returns the list of available commands on the current XO instance.

    The patterns can be used to filter on command names.

  xo-cli --list-objects [--<property>]… [<property>=<value>]...
    Returns a list of XO objects.

      Restricts displayed properties to those listed.

      Restricted displayed objects to those matching the patterns.

  xo-cli <command> [--json] [<name>=<value>]...
    Executes a command on the current XO instance.

      Prints the result in JSON format.

  xo-cli rest del <resource>
    Delete the resource.

      xo-cli rest del tasks/<task id>
      xo-cli rest del vms/<vm id>/tags/<tag>

  xo-cli rest get <collection> [fields=<fields>] [filter=<filter>] [limit=<limit>]
    List objects in a REST API collection.

      Full path of the collection to list

      When provided, returns a collection of objects containing the requested
      fields instead of the simply the objects' paths.

      The field names must be separated by commas.

      List only objects that match the filter

      Syntax: https://xen-orchestra.com/docs/manage_infrastructure.html#filter-syntax

      Maximum number of objects to list, e.g. `limit=10`

      xo-cli rest get
      xo-cli rest get tasks filter='status:pending'
      xo-cli rest get vms fields=name_label,power_state

  xo-cli rest get [--output <file>] <object> [wait | wait=result]
    Show an object from the REST API.

    --output <file>
      If specified, the response will be saved in <file> instead of being parsed.

      If <file> ends with `/`, it will be considered as the directory in which
      to save the response, and the filename will be last part of the <object> path.

      Full path of the object to show

      If the object is a task, waits for it to be updated before returning.

      If the object is a task, waits for it to be finished before returning.

      xo-cli rest get vms/<VM UUID>
      xo-cli rest get tasks/<task id>/actions wait=result

  xo-cli rest patch <object> <name>=<value>...
    Update properties of an object (not all properties are writable).

      Full path of the object to update

      Properties to update on the object

      xo-cli rest patch vms/<VM UUID> name_label='My VM' name_description='Its description

  xo-cli rest post <action> <name>=<value>...
    Execute an action.

      Full path of the action to execute

      Paramaters to pass to the action

      xo-cli rest post tasks/<task id>/actions/abort
      xo-cli rest post vms/<VM UUID>/actions/snapshot name_label='My snapshot'

  xo-cli rest put <collection>/<item id> <name>=<value>...
    Put a item in a collection

    <collection>/<item id>
      Full path of the item to add

      Properties of the item

      xo-cli rest put vms/<vm id>/tags/<tag>

Register your XO instance

> xo-cli --register http://xo.my-company.net admin@admin.net admin
Successfully logged with admin@admin.net

Note: only a token will be saved in the configuration file.

List available objects

Prints all objects:

> xo-cli --list-objects

It is possible to filter on object properties, for instance to prints all VM templates:

> xo-cli --list-objects type=VM-template

List available commands

> xo-cli --list-commands

Commands can be filtered using patterns:

> xo-cli --list-commands '{user,group}.*'

Execute a command

The same syntax is used for all commands: xo-cli <command> <param name>=<value>...

E.g., adding a new server:

> xo-cli server.add host=my.server.net username=root password=secret-password

The return value is the identifier of this new server in XO.

Because command lines are usually untyped, parameters (except true and false which are considered as booleans) are assumed as strings by default, other types must be encoded as JSON and prefixed by json::

> xo-cli method string=foo number=json:42 array=json:'["item1", "item2"]'
Configuration export
> xo-cli xo.exportConfig @=config.json
VM export
> xo-cli vm.export vm=a01667e0-8e29-49fc-a550-17be4226783c @=vm.xva
XVA VM import
> xo-cli vm.import sr=60a6939e-8b0a-4352-9954-5bde44bcdf7d @=vm.xva

Note: xo-cli only supports the import of XVA files. It will not import OVA files.

OVA VM import

A separate utility, xo-upload-ova, can be used to import .ova files.


Contributions are very welcomed, either on the documentation or on the code.

You may:

  • report any issue you've encountered;
  • fork and create a pull request.


AGPL-3.0-or-later © Vates SAS

Package Sidebar


npm i xo-cli

Weekly Downloads






Unpacked Size

32.3 kB

Total Files


Last publish


  • olivierlambert
  • julien-f
  • pdonias
  • tgoettelmann
  • mathieura
  • florent.beauchamp
  • b-nollet