VIRGO Command Line Interface

The command line interface is designed based on an object - verb structure.

VIRGO currently defines the following types of objects (subsystems):

The sections below describe the VIRGO command line syntax. Note that VIRGO command line options follow the standard Portable Operating System Interface (POSIX) convention. This means that many of those options come in a short (single dash prefix) and a long (double dash prefix) form.

Command Line Options

Help

> virgo --help
> virgo -h
<help text>

Shows all available VIRGO command line options.

Administrator

Get the current administrator configuration

> virgo administrator get

This command causes VIRGO to print the current administrator configuration. VIRGO may either be administrated by a cloud server (aka VIRGA) or it may be self-administrated. ‘Virgo' is printed in the former case ‘Virga' in the later.

Setting the administrator configuration

> virgo administrator set <name>   // <name> is either 'virga' or 'virgo'
Administrator: <name>

This command causes VIRGO to switch to the specified administrator. Pass ‘virga' if VIRGO should be administrated via the VIRGA server. Note that the environment definition must contain an admin-server-url entry in this case. Pass ‘virgo' if VIRGO should be used standalone without a cloud command & control server. Standalone mode allows you to freely add, remove, and change feeds whereas the VIRGA administration mode requires that feeds are added, removed, and changed via VIRGA.

Service

Get information about the VIRGO service

> virgo service info
Version:       1.0.0
Target:        x86_64-macos
Domain:        System
Administrator: Virga
Environment:   PROD
Client ID:     <client-id>
Client Type:   <client type>

This command prints the following information about the installed VIRGO daemon build and its fundamental configuration.

Get the current service status

> virgo service status
camera_1: ok
camera_2: ok
camera_3: inactive

This command tells VIRGO to print the current status of all registered feeds.

Monitor the current status of all feeds

> virgo service monitor

This command enables the service monitor. See Service Monitoring for more information.

Logging

> virgo service log <log specification>

This command displays the current service log. See Service Logging for more information.

Resetting the VIRGO daemon state

> virgo service reset

This command tells VIRGO that it should delete its current state and reinitialize it from the contents of the factory configuration file. This effectively resets the daemon back to the factory state.

Updating VIRGO

> virgo service update <version> <url> [--verbose]    // download an install a new version.
> virgo service update <version> [--verbose]          // switch virgo to a previously installed version. E.g. downgrade to an old version.

This command causes VIRGO to upgrade or downgrade to the specified version. <version> is the version to upgrade or downgrade to and <url> is a file or HTTP/HTTPS URL that points to VIRGO update archive. Specifying the update archive URL is only necessary if the version you are trying to switch to isn't already installed on the machine. By default VIRGO shows the current update status and progress. Specify the "–verbose" switch to cause VIRGO to show the full update log instead.

Get information about the installed VIRGO versions

> virgo service versions
Installed:
   1.0.0
   1.1.0
-> 1.2.0
  
Current:
   1.2.0

This command causes VIRGO to print the version numbers of all installed VIRGO packages plus the version number of the currently active and running VIRGO daemon.

Environment

A VIRGO daemon has a built-in list of supported environments. Only one of those environments can be active at a given time. The active environment determines to which VIRGA, face recognition, and event servers virgod and its virgafeedd child processes will talk.

List supported environments

> virgo environment list
DEV
INT2
LOCAL
PROD

Lists all environments supported by VIRGO.

Get the active environment

> virgo environment get [--verbose]
PROD

Returns the currently active environment. This is the environment to which virgod and all of its virgofeedd daemons connect. Additionally VIRGO will show the URLs of the individual servers in the environment if you pass the --verbose flag.

Set the active environment

> virgo environment set <environment name> [--verbose]
OK

Sets the environment which VIRGO and its feeds will use. Note that <environment name> must be one of the supported environments or one of the custom environments defined in the factory configuration file. Note that changing the environment also resets the VIRGO daemon back to the factory configuration.

By default the command prints "OK" if the switch to the new environment succeeds, while it prints an error if one or more services can not be contacted. You can pass the --verbose flag to get a detailed status for each service.

Cloud User

Get cloud account details

> virgo user get
User ID: <user id>
Password: ***

Prints the User ID and and an indication whether a password was provided. Three asterisk characters indicate that VIRGO has a password on file, while an empty password line indicates that VIRGO doesn't have a password for the user on file.

Set the cloud account

> virgo user set
User ID: <user id>
Password: ***

Replaces the current cloud account's credentials with the provided User ID and Password. All currently enabled feeds are automatically restarted with the new account information.

Feeds

A single virgod daemon instance is capable of managing a set of video feeds. Virgod spawns one virgofeedd instance per feed and this virgofeedd instance is exclusively responsible for tracking its assigned feed. Virgod automatically respawns a virgofeedd instance if it dies unexpectedly.

A feed has:

Virgod stores the configuration information for a feed persistently. A feed can be added, removed, started, and stopped at any time. A VIRGO instance may come prepackaged with the configuration information for one or more feeds. New feeds may be added dynamically any time as long as virgod is running.

List feeds

> virgo feed list
camera_1
camera_2

Lists all enabled and disabled feeds that have been registered with VIRGO.

Get the configuration information for a feed

> virgo feed get <feed name>
{
   "active":true
   "url":"rtp://camera.is.here/with/stream:8789"
   ...
}

Prints the feed configuration JSON dictionary.

Update/set the configuration information for a feed

> virgo feed set <feed name> <feed config file path>

Updates the current configuration of the feed with name <feed name>. The feed configuration file is read and the properties in the configuration file are applied to the current feed configuration stored in VIRGO. The feed configuration file is a JSON file with a single dictionary which contains the feed properties that you want to change. Note that the feed configuration file only needs to contain those properties that you want to change. See Video Feeds Properties for a list of supported feed properties.

Get the PID of a feed

> virgo feed get-pid <feed name>
53280

Prints the PID of the feed. -1 is printed if the feed is currently not active and thus no feed daemon is running to process the feed video stream.

Get the status of a feed

> virgo feed status <feed name>
ok

Prints the current status of a feed.

Add a new feed

> virgo feed add <feed name> <feed config file path>

Adds a new feed configuration to the persistent list of feeds. The feed name must be unique with respect to the VIRGO instance. The feed configuration is read from the supplied feed configuration file. The feed will immediately start processing if it is marked as "enabled" in the configuration file; otherwise the feed will be added to the persistent list of feeds but a separate "virgo feed start <feed name>" command will have to be issued to cause the feed to start running.

Remove an existing feed

> virgo feed remove <feed name>

VIRGO will stop the feed and then remove the feed configuration information from its persistent feed table.

Starting a feed

> virgo feed start <feed name>

VIRGO will mark the feed as active and start processing it. A video file feed starts processing from the beginning of the video while a camera feed starts processing from the current time code of the video stream. If the feed is already active and running this command instead does nothing.

Stopping a feed

> virgo feed stop <feed name>

Marks the feed as inactive and stops processing the video stream. If the feed is already marked as inactive, then this command instead does nothing.

Capturing an image from a feed

> virgo feed capture-image <feed name> <url or path> [--size <image_size>] [--max-frames <max_number_of_frames>] [--frame-delay <delay_in_milliseconds>]

Enables capturing of a single image or a series of consecutive images from the specified feed. <url or path> is a file or HTTP URL or a file system path. The URL/path is expected to point to a directory. VIRGO will create the directory if necessary and it will write all captured images to this directory. The size of the larger side of the capture image can be specified with the --size option. The default capture image size is 720 pixels. The maximum number of consecutive frames that should be captured can be specified with the --max-frames option. The default is to capture a single image. The --frame-delay option allows you to specify the delay between consecutive frames in milliseconds.

See Also