7.3. Command line interface#

This page contains the API reference of the functions in the vantage package. This package contains the Command-Line Interface (CLI) of the Vantage6 framework.

7.3.1. Node CLI#

vantage6.cli.node#

v6 node#

Manage your vantage6 node instances.

v6 node [OPTIONS] COMMAND [ARGS]...
cli-node-attach#

Show the node logs in the current console.

v6 node cli-node-attach [OPTIONS]

Options

-n, --name <name>#

Configuration name

--system#

Search for configuration in system folders rather than user folders

--user#

Search for configuration in user folders rather than system folders. This is the default

cli-node-clean#

Erase temporary Docker volumes.

v6 node cli-node-clean [OPTIONS]
cli-node-create-private-key#

Create and upload a new private key

Use this command with caution! Uploading a new key has several consequences, e.g. you and other users of your organization will no longer be able to read the results of tasks encrypted with current key.

v6 node cli-node-create-private-key [OPTIONS]

Options

-n, --name <name>#

Configuration name

-c, --config <config>#

Absolute path to configuration-file; overrides NAME

--system#

Search for configuration in system folders rather than user folders

--user#

Search for configuration in user folders rather than system folders. This is the default

--no-upload#

Don’t upload the public key to the server

-o, --organization-name <organization_name>#

Organization name. Used in the filename of the private key so that it can easily be recognized again later

--overwrite#

Overwrite existing private key if present

cli-node-files#

Prints the location of important node files.

If the specified configuration cannot be found, it exits. Otherwise it returns the absolute path to the output.

v6 node cli-node-files [OPTIONS]

Options

-n, --name <name>#

Configuration name

--system#

Search for the configuration in the system folders

--user#

Search for the configuration in the user folders. This is the default

cli-node-list#

Lists all node configurations.

Note that this command cannot find node configuration files in custom directories.

v6 node cli-node-list [OPTIONS]
cli-node-new-configuration#

Create a new node configuration.

Checks if the configuration already exists. If this is not the case a questionnaire is invoked to create a new configuration file.

v6 node cli-node-new-configuration [OPTIONS]

Options

-n, --name <name>#

Configuration name

--system#

Store this configuration in the system folders

--user#

Store this configuration in the user folders. This is the default

cli-node-remove#

Delete a node permanently.

Remove the configuration file, log file, and docker volumes attached to the node.

v6 node cli-node-remove [OPTIONS]

Options

-n, --name <name>#

Configuration name

--system#

Search for configuration in system folders rather than user folders

--user#

Search for configuration in user folders rather than system folders. This is the default

-f, --force#

Don’t ask for confirmation

cli-node-set-api-key#

Put a new API key into the node configuration file

v6 node cli-node-set-api-key [OPTIONS]

Options

-n, --name <name>#

Configuration name

--api-key <api_key>#

New API key

--system#

Search for configuration in system folders rather than user folders

--user#

Search for configuration in user folders rather than system folders. This is the default

cli-node-start#

Start the node.

v6 node cli-node-start [OPTIONS]

Options

-n, --name <name>#

Configuration name

-c, --config <config>#

Path to configuration-file; overrides NAME

--system#

Search for the configuration in the system folders

--user#

Search for the configuration in the user folders. This is the default

-i, --image <image>#

Node Docker image to use

--keep, --auto-remove#

Keep node container after finishing. Useful for debugging

--force-db-mount#

Always mount node databases; skip the check if they are existing files.

--attach, --detach#

Show node logs on the current console after starting the node

--mount-src <mount_src>#

Override vantage6 source code in container with the source code in this path

cli-node-stop#

Stop one or all running nodes.

v6 node cli-node-stop [OPTIONS]

Options

-n, --name <name>#

Configuration name

--system#

Search for configuration in system folders instead of user folders

--user#

Search for configuration in the user folders instead of system folders. This is the default.

--all#

Stop all running nodes

--force#

Kill nodes instantly; don’t wait for them to shut down

cli-node-version#

Returns current version of a vantage6 node.

v6 node cli-node-version [OPTIONS]

Options

-n, --name <name>#

Configuration name

--system#

Search for configuration in system folders rather than user folders

--user#

Search for configuration in user folders rather than system folders. This is the default

7.3.2. Server CLI#

v6 server#

Manage your vantage6 server instances.

v6 server [OPTIONS] COMMAND [ARGS]...

cli-server-attach#

Show the server logs in the current console.

v6 server cli-server-attach [OPTIONS]

Options

-n, --name <name>#

configuration name

--system#
--user#

cli-server-configuration-list#

Print the available server configurations.

v6 server cli-server-configuration-list [OPTIONS]

cli-server-files#

List files that belong to a particular server instance.

v6 server cli-server-files [OPTIONS]

Options

-n, --name <name>#

Name of the configuration you want to use.

-c, --config <config>#

Absolute path to configuration-file; overrides NAME

--system#

Use system folders instead of user folders. This is the default

--user#

Use user folders instead of system folders

cli-server-import#

Import vantage6 resources into a server instance.

This allows you to create organizations, collaborations, users, tasks, etc from a yaml file.

The FILE_ argument should be a path to a yaml file containing the vantage6 formatted data to import.

v6 server cli-server-import [OPTIONS] FILE

Options

--drop-all#

Drop all existing data before importing

-i, --image <image>#

Node Docker image to use

--mount-src <mount_src>#

Override vantage6 source code in container with the source code in this path

--keep, --auto-remove#

Keep image after finishing. Useful for debugging

--wait <wait>#

Wait for the import to finish

-n, --name <name>#

Name of the configuration you want to use.

-c, --config <config>#

Absolute path to configuration-file; overrides NAME

--system#

Use system folders instead of user folders. This is the default

--user#

Use user folders instead of system folders

Arguments

FILE#

Required argument

cli-server-new#

Create a new server configuration.

v6 server cli-server-new [OPTIONS]

Options

-n, --name <name>#

name of the configuration you want to use.

--system#
--user#

cli-server-remove#

Function to remove a server.

Parameters#
ctxServerContext

Server context object

forcebool

Whether to ask for confirmation before removing or not

v6 server cli-server-remove [OPTIONS]

Options

-n, --name <name>#

Name of the configuration you want to use.

-c, --config <config>#

Absolute path to configuration-file; overrides NAME

--system#

Use system folders instead of user folders. This is the default

--user#

Use user folders instead of system folders

-f, --force#

cli-server-shell#

Run an iPython shell within a running server. This can be used to modify the database.

NOTE: using the shell is no longer recommended as there is no validation on the changes that you make. It is better to use the Python client or a graphical user interface instead.

v6 server cli-server-shell [OPTIONS]

Options

-n, --name <name>#

Name of the configuration you want to use.

-c, --config <config>#

Absolute path to configuration-file; overrides NAME

--system#

Use system folders instead of user folders. This is the default

--user#

Use user folders instead of system folders

cli-server-start#

Start the server.

v6 server cli-server-start [OPTIONS]

Options

--ip <ip>#

IP address to listen on

-p, --port <port>#

Port to listen on

-i, --image <image>#

Server Docker image to use

--with-ui#

Start the graphical User Interface as well

--ui-port <ui_port>#

Port to listen on for the User Interface

--with-rabbitmq#

Start RabbitMQ message broker as local container - use in development only

--rabbitmq-image <rabbitmq_image>#

RabbitMQ docker image to use

--keep, --auto-remove#

Keep image after server has stopped. Useful for debugging

--mount-src <mount_src>#

Override vantage6 source code in container with the source code in this path

--attach, --detach#

Print server logs to the console after start

-n, --name <name>#

Name of the configuration you want to use.

-c, --config <config>#

Absolute path to configuration-file; overrides NAME

--system#

Use system folders instead of user folders. This is the default

--user#

Use user folders instead of system folders

cli-server-stop#

Stop one or all running server(s).

v6 server cli-server-stop [OPTIONS]

Options

-n, --name <name>#

Configuration name

--system#
--user#
--all#

Stop all servers

cli-server-version#

Print the version of the vantage6 server.

v6 server cli-server-version [OPTIONS]

Options

-n, --name <name>#

Configuration name

--system#
--user#

7.3.3. Local test setup CLI#

v6 dev#

Quickly manage a test network with a server and several nodes.

These commands are helpful for local testing of your vantage6 environment.

v6 dev [OPTIONS] COMMAND [ARGS]...

create-demo-network#

Creates a demo network.

Creates server instance as well as its import configuration file. Server name is set to ‘dev_default_server’. Generates n node configurations, but by default this is set to 3. Then runs a Batch import of organizations/collaborations/users and tasks.

v6 dev create-demo-network [OPTIONS]

Options

-n, --name <name>#

Name for your development setup

--num-nodes <num_nodes>#

Generate this number of nodes in the development network

--server-url <server_url>#

Server URL to point to. If you are using Docker Desktop, the default http://host.docker.internal should not be changed.

-p, --server-port <server_port>#

Port to run the server on. Default is 5000.

-i, --image <image>#

Server docker image to use when setting up resources for the development server

--extra-server-config <extra_server_config>#

YAML File with additional server configuration. This will be appended to the server configuration file

--extra-node-config <extra_node_config>#

YAML File with additional node configuration. This will be appended to each of the node configuration files

remove-demo-network#

Remove all related demo network files and folders.

Select a server configuration to remove that server and the nodes attached to it.

v6 dev remove-demo-network [OPTIONS]

Options

-n, --name <name>#

Name of the configuration you want to use.

-c, --config <config>#

Absolute path to configuration-file; overrides NAME

--system#

Use system folders instead of user folders. This is the default

--user#

Use user folders instead of system folders

start-demo-network#

Starts running a demo-network.

Select a server configuration to run its demo network. You should choose a server configuration that you created earlier for a demo network. If you have not created a demo network, you can run vdev create-demo-network to create one.

v6 dev start-demo-network [OPTIONS]

Options

-n, --name <name>#

Name of the configuration you want to use.

-c, --config <config>#

Absolute path to configuration-file; overrides NAME

--system#

Use system folders instead of user folders. This is the default

--user#

Use user folders instead of system folders

--server-image <server_image>#

Server Docker image to use

--node-image <node_image>#

Node Docker image to use

stop-demo-network#

Stops a demo network’s server and nodes.

Select a server configuration to stop that server and the nodes attached to it.

v6 dev stop-demo-network [OPTIONS]

Options

-n, --name <name>#

Name of the configuration you want to use.

-c, --config <config>#

Absolute path to configuration-file; overrides NAME

--system#

Use system folders instead of user folders. This is the default

--user#

Use user folders instead of system folders

7.3.4. vantage6.cli.context#

The context module in the CLI package contains the definition of the ServerContext and NodeContext classes. These contexts are related to the host system and therefore part of the CLI package.

Both classes are derived from the abstract AppContext class. And provide the node and server with naming conventions, standard file locations, and in the case of the node with a local database URIs.

Server Context

A class to provide context for the server, both for development mode as for production.

Node Context

In case the node is run in development mode, this context will also used by the node package. Normally the node uses the vantage6.node.context.DockerNodeContext which provides the same functionality but is tailored to the Docker environment.

class NodeContext(instance_name, system_folders=False, config_file=None, print_log_header=True)#

Bases: AppContext

Node context

See DockerNodeContext for the node instance mounts when running as a dockerized service.

Parameters:
  • instance_name (str) – Name of the configuration instance, corresponds to the filename of the configuration file.

  • system_folders (bool, optional) – _description_, by default N_FOL

  • config_file (str, optional) – _description_, by default None

INST_CONFIG_MANAGER#

alias of NodeConfigurationManager

classmethod available_configurations(system_folders=False)#

Find all available server configurations in the default folders.

Parameters:

system_folders (bool, optional) – System wide or user configuration, by default N_FOL

Returns:

The first list contains validated configuration files, the second list contains invalid configuration files.

Return type:

tuple[list, list]

classmethod config_exists(instance_name, system_folders=False)#

Check if a configuration file exists.

Parameters:
  • instance_name (str) – Name of the configuration instance, corresponds to the filename of the configuration file.

  • system_folders (bool, optional) – System wide or user configuration, by default N_FOL

Returns:

Whether the configuration file exists or not

Return type:

bool

property databases: dict#

Dictionary of local databases that are available for this node.

Returns:

dictionary with database names as keys and their corresponding paths as values.

Return type:

dict

property docker_container_name: str#

Docker container name of the node.

Returns:

Node’s Docker container name

Return type:

str

property docker_network_name: str#

Private Docker network name which is unique for this node.

Returns:

Docker network name

Return type:

str

property docker_squid_volume_name: str#

Docker volume in which the SSH configuration is stored.

Returns:

Docker volume name

Return type:

str

property docker_ssh_volume_name: str#

Docker volume in which the SSH configuration is stored.

Returns:

Docker volume name

Return type:

str

docker_temporary_volume_name(job_id)#

Docker volume in which temporary data is stored. Temporary data is linked to a specific run. Multiple algorithm containers can have the same run id, and therefore the share same temporary volume.

Parameters:

job_id (int) – run id provided by the server

Returns:

Docker volume name

Return type:

str

property docker_volume_name: str#

Docker volume in which task data is stored. In case a file based database is used, this volume contains the database file as well.

Returns:

Docker volume name

Return type:

str

property docker_vpn_volume_name: str#

Docker volume in which the VPN configuration is stored.

Returns:

Docker volume name

Return type:

str

classmethod from_external_config_file(path, system_folders=False)#

Create a node context from an external configuration file. External means that the configuration file is not located in the default folders but its location is specified by the user.

Parameters:
  • path (str) – Path of the configuration file

  • system_folders (bool, optional) – System wide or user configuration, by default N_FOL

Returns:

Node context object

Return type:

NodeContext

get_database_uri(label='default')#

Obtain the database URI for a specific database.

Parameters:

label (str, optional) – Database label, by default “default”

Returns:

URI to the database

Return type:

str

static type_data_folder(system_folders=False)#

Obtain OS specific data folder where to store node specific data.

Parameters:

system_folders (bool, optional) – System wide or user configuration

Returns:

Path to the data folder

Return type:

Path

class ServerContext(instance_name, system_folders=True)#

Bases: AppContext

Server context

Parameters:
  • instance_name (str) – Name of the configuration instance, corresponds to the filename of the configuration file.

  • system_folders (bool, optional) – System wide or user configuration, by default S_FOL

INST_CONFIG_MANAGER#

alias of ServerConfigurationManager

classmethod available_configurations(system_folders=True)#

Find all available server configurations in the default folders.

Parameters:

system_folders (bool, optional) – System wide or user configuration, by default S_FOL

Returns:

The first list contains validated configuration files, the second list contains invalid configuration files.

Return type:

tuple[list, list]

classmethod config_exists(instance_name, system_folders=True)#

Check if a configuration file exists.

Parameters:
  • instance_name (str) – Name of the configuration instance, corresponds to the filename of the configuration file.

  • system_folders (bool, optional) – System wide or user configuration, by default S_FOL

Returns:

Whether the configuration file exists or not

Return type:

bool

property docker_container_name: str#

Name of the docker container that the server is running in.

Returns:

Server’s docker container name

Return type:

str

classmethod from_external_config_file(path, system_folders=True)#

Create a server context from an external configuration file. External means that the configuration file is not located in the default folders but its location is specified by the user.

Parameters:
  • path (str) – Path of the configuration file

  • system_folders (bool, optional) – System wide or user configuration, by default S_FOL

Returns:

Server context object

Return type:

ServerContext

get_database_uri()#

Obtain the database uri from the environment or the configuration. The VANTAGE6_DB_URI environment variable is used by the Docker container, but can also be set by the user.

Returns:

string representation of the database uri

Return type:

str

7.3.5. vanatge6.cli.configuration_manager#

class NodeConfiguration(*args, **kwargs)#

Bases: Configuration

Stores the node’s configuration and defines a set of node-specific validators.

class NodeConfigurationManager(name, *args, **kwargs)#

Bases: ConfigurationManager

Maintains the node’s configuration.

Parameters:

name (str) – Name of the configuration file.

classmethod from_file(path)#

Create a new instance of the NodeConfigurationManager from a configuration file.

Parameters:

path (str) – Path to the configuration file.

Returns:

A new instance of the NodeConfigurationManager.

Return type:

NodeConfigurationManager

class ServerConfiguration(*args, **kwargs)#

Bases: Configuration

Stores the server’s configuration and defines a set of server-specific validators.

class ServerConfigurationManager(name, *args, **kwargs)#

Bases: ConfigurationManager

Maintains the server’s configuration.

Parameters:

name (str) – Name of the configuration file.

classmethod from_file(path)#

Create a new instance of the ServerConfigurationManager from a configuration file.

Parameters:

path (str) – Path to the configuration file.

Returns:

A new instance of the ServerConfigurationManager.

Return type:

ServerConfigurationManager

class TestConfiguration(*args, **kwargs)#

Bases: Configuration

class TestingConfigurationManager(name, *args, **kwargs)#

Bases: ConfigurationManager

classmethod from_file(path)#

Load a configuration from a file.

Parameters:
  • path (Path | str) – The path to the file to load the configuration from.

  • conf_class (Type[Configuration]) – The class to use for the configuration.

Returns:

The configuration manager with the configuration.

Return type:

ConfigurationManager

Raises:

AssertionError – If the name of the configuration could not be extracted from the file path.

7.3.6. vantage6.cli.configuration_wizard#

configuration_wizard(type_, instance_name, system_folders)#

Create a configuration file for a node or server instance.

Parameters:
  • type (str) – Type of the instance. Either “node” or “server”

  • instance_name (str) – Name of the instance

  • system_folders (bool) – Whether to use the system folders or not

Returns:

Path to the configuration file

Return type:

Path

node_configuration_questionaire(dirs, instance_name)#

Questionary to generate a config file for the node instance.

Parameters:
  • dirs (dict) – Dictionary with the directories of the node instance.

  • instance_name (str) – Name of the node instance.

Returns:

Dictionary with the new node configuration

Return type:

dict

select_configuration_questionaire(type_, system_folders)#

Ask which configuration the user wants to use. It shows only configurations that are in the default folder.

Parameters:
  • type (str) – Type of the instance. Either “node” or “server”

  • system_folders (bool) – Whether to use the system folders or not

Returns:

Name of the configuration

Return type:

str

server_configuration_questionaire(instance_name)#

Questionary to generate a config file for the node instance.

Parameters:

instance_name (str) – Name of the node instance.

Returns:

Dictionary with the new server configuration

Return type:

dict

7.3.7. vanatge6.cli.rabbitmq.queue_manager#

class RabbitMQManager(ctx, network_mgr, image=None)#

Manages the RabbitMQ docker container

Parameters:
  • ctx (ServerContext) – Configuration object

  • network_mgr (NetworkManager) – Network manager for network in which server container resides

  • image (str) – Docker image to use for RabbitMQ container. By default, the image harbor2.vantage6.ai/infrastructure/rabbitmq is used.

is_running()#
Returns:

Whether the container has fully initialized RabbitMQ or not

Return type:

bool

start()#

Start a docker container which runs a RabbitMQ queue

Return type:

None

7.3.8. vanatge6.cli.rabbitmq#

RabbitMQ utilities.

split_rabbitmq_uri(rabbit_uri)#

Get details (user, pass, host, vhost, port) from a RabbitMQ uri.

Parameters:

rabbit_uri (str) – URI of RabbitMQ service (‘amqp://$user:$pass@$host:$port/$vhost’)

Returns:

The vhost defined in the RabbitMQ URI

Return type:

dict[str]

7.3.9. vantage6.cli.utils#

Utility functions for the CLI

check_config_name_allowed(name)#

Check if configuration name is allowed

Parameters:

name (str) – Name to be checked

Return type:

None

check_if_docker_daemon_is_running(docker_client)#

Check if Docker daemon is running

Parameters:

docker_client (docker.DockerClient) – The docker client

Return type:

None

prompt_config_name(name)#

Get a new configuration name from the user, or simply return the name if it is not None.

Parameters:

name (str) – Name to be checked

Returns:

The name of the configuration

Return type:

str

remove_file(file, file_type)#

Remove a file if it exists.

Parameters:
  • file (str) – absolute path to the file to be deleted

  • file_type (str) – type of file, used for logging

Return type:

None