4.7 Sneak Preview – vsctl – The Improved Command Line Interface

By Eskil - September 14, 2016 (Last updated: April 9, 2017)

With Vidispine 4.7 you’ll get a new and improved command line interface called vsvtl. vsctl can be used to inspect and control a running Vidispine server. It is targeted at operations and developers working with Vidispine.

All information and operations are performed using the API, so this can also be seen as an example on how to interact with Vidispine from Python. We have selected a few commands that we believe are of importance to you, and will slowly but steady continue to improve on the tool.


Let’s start with an overview of everything you can do with vsctl. Just run the command without any arguments to see the full help, and you’ll get this list.

    vsctl [SWITCHES] [SUBCOMMAND [SWITCHES]] args...

    --help                    Prints this help message and quits
    --help-all                Print help messages of all subcommands and quit
    -v, --version             Prints the program's version and quits

    -a, --auth VALUE:str      Vidispine user (and password); the default is 'admin:admin'
    --color                   Always print colored output
    --debug                   Print https requests and responses
    -h, --host VALUE:str      Vidispine server host; the default is 'localhost:8080'

    audit                     Query the audit log; see 'vsctl audit --help' for more info
    find                      Find items matching keywords or query; see 'vsctl find --help' for more info
    health                    Show current Vidispine health; see 'vsctl health --help' for more info
    import                    Import files by path or by direct upload; see 'vsctl import --help' for more info
    indexing                  View reindex status; see 'vsctl indexing --help' for more info
    jobs                      Show job status; see 'vsctl jobs --help' for more info
    property                  Manage configuration properties; see 'vsctl property --help' for more info
    service                   Manage services; see 'vsctl service --help' for more info
    status                    Show current Vidispine status; see 'vsctl status --help' for more info
    threads                   Print stack trace from Vidispine; see 'vsctl threads --help' for more info

Below we’ll present a few of the commands in more detail, and as we continue to work on it we’ll present more commands in another blog post.

File import

The import commands imports a single file and displays the job id, which could then be checked using GET API/job/{id} or using the job command.

$ ./vsctl import media/squirrel.jpg 

Item search

The find command can be used to perform simple queries by field.

$ ./vsctl find originalFilename=squirrel.jpg
$ ./vsctl find -f title originalFilename=squirrel.jpg
VX-491810 Small squirrel

Job status

The job command displays the status of all running jobs.

$ vsctl jobs
$ vsctl import media/squirrel.jpg 
$ vsctl jobs
VX-128958 - PLACEHOLDER_IMPORT                          STARTED [==                  ] 11%
$ vsctl jobs
VX-128958 - PLACEHOLDER_IMPORT                          STARTED [=====               ] 29%
$ vsctl jobs
VX-128958 - PLACEHOLDER_IMPORT                          STARTED [=======             ] 35%
$ vsctl jobs

As you can see, the program displays the status and then exits. To avoid having to run the program repeatedly, use watch.

$ watch -n1 vsctl jobs


A common task in setting up a Vidispine system is tuning the configuration properties. The property command is meant to aid with this.

$ ./vsctl property
$ ./vsctl property solrpath
$ ./vsctl property solrpath=https://solr.example.com:8983/solr

Open for suggestions

The vsctl is very much open for suggestions, so if you have any suggestions on commands or arguments that would be useful to you, then please don’t hesitate to get in contact with us. A very good way to make suggestions is to use our support portal and add a new ticket of the type “Suggestion”.

This was part 1 of the sneak preview. Part 2 of the vsctl sneak preview is here.