1. Home
  2. Docs
  3. Software Agent
  4. Command Line Interface (CLI)

Command Line Interface (CLI)

In addition to the Control Panel, you can interact with the Vawlt agent using the Command Line Interface (CLI). This mode might be handy for headless computers.

Running modes

There are two ways to run the CLI:

Interactive mode

In this mode, you can enter the Vawlt interpreter, navigate between the different menus and run one or more commands. The interactive mode can be started with vawlt cli. At this stage, you can execute a command from the top menu (root) or enter one of the sub-menus. You can go back anytime to the root menu with exit or get some help about the current sub-menu commands with help.

Once finished, you can simply exit the Vawlt interpreter with quit (or exit if you are in the root menu). Exiting the CLI has no effect on the Vawlt agent which keeps running in the background. However some commands are available to stop or restart the Vawlt agent from the CLI, they will be detailed in the next sections.

Note that the completion key (tab) can be pressed to automatically fill a partially typed command or get help on the current command arguments.

One-liner mode

This mode is suitable when running a single command through the shell command interpreter or including this command in a script. The one-liner mode syntax is the following:

vawlt cli <root-command> [ <argument> ... ]
ex: vawlt cli stop

vawlt cli <sub-menu> <command> [ <argument> ... ]
ex: vawlt cli user reset-password

Interactive and one-liner modes can be combined using vawlt cli <sub-menu> without any command. In this case, the user will start the interactive mode directly into the sub-menu. For instance, let’s assume the user intends to edit the S3 parameters, he can issue vawlt cli s3 to enter the s3 menu instead of using vawlt cli and next s3.

Command line reference

The CLI commands are distributed into the root menu and 10 sub-menus:

  • root: session management
  • config: configuration parameters
  • cache: cache disk management
  • policy: policy rule management
  • trash: file trash management
  • object: versioning and archive
  • share: folder sharing
  • stat: general statistics
  • desktop: file system management
  • user: user profile
  • s3: S3 interface management
  • keystore: self-signed certificates

Root commands

These basic commands lead with the Vawlt agent state and the user’s session management.

  • login: allow the user to enter username and password. Return immediately if the user is already logged in.
  • logout: user logout. Note that the remember-me option is disabled after a manual logout.
  • start: start the agent. The command is suitable to restart the agent after running the stop command. Note that the agent is automatically started after executing any command which requires the agent to be running.
  • restart: restart the agent. Combination of stop and start commands.
  • stop: stop the Vawlt agent. The CLI keeps on running while the agent is terminated.
  • update: check for update. If a new agent version is available, update automatically the agent.
  • version: show current agent version. Return as well the new update version if available.

Configuration commands

  • show: show all configuration parameters.
  • show mount-point-location: show mount point folder.
  • show cache-encryption: show cache encryption status.
  • show allow-other-users: whether other users can connect mount-point. This option is only available for Linux platforms.
  • show upload-thread-number: show the number of upload threads used to send data to the clouds.
  • show max-system-memory: show in MB the maximum memory allocation pool for the Vawlt agent.
  • mount-point-location <path>: set mount point folder (restart the agent to take effect).
  • cache-encryption on|off : set cache encryption status.
  • allow-other-users on|off: let other users connect mount-point. This option is only available for Linux platforms.
  • upload-thread-number <number> : set the number of upload threads used to send data to the clouds.
  • max-system-memory <size> : set in MB the maximum memory allocation pool for the Vawlt agent.

Note: Regarding the mount-point, the default location is the user’s home directory. In Linux platforms, be aware that other users could not access correctly the mount-point if the allow-other-users option is not enabled. Also, the line “user_allow_other” must be uncommented in the fuse configuration file in /etc/fuse.conf.

Cache commands

These commands are dedicated to the Vawlt cache management. You can create several cache locations on different storage devices with a maximum of one cache per device. You can use the whole disk space available in the device for each location or limit the cache space to a maximum value.

  • show: show for each cache location the current size, maximum size, and cache state. There are three possible states: “active” if the cache is up and running, “disconnected” if the cache is temporally unreachable, and “removed” if the cache is waiting to be removed.
  • clean: clean all cache disk locations. Only the data already sent to the cloud will be actually removed so clearing a cache may not result in a zero cache size.
  • add <path> [ <size> ]: add a new cache location. If the size argument is omitted, the maximum available size is configured. If the size is given, it must be lower or equal to the disk available size. The minimum cache size is 1Gb.
  • resize <path> [ <size> ]: update the cache maximum size. If the size argument is omitted, the maximum available size is configured. If the size is given, it must be greater than the current cache size.
  • remove <path> : remove cache disk location. The cache state is set to “removed” until all cache data is actually sent to the cloud. Then the cache location and its contents are removed from the disk.

The user can define the cache size in bytes (without unit) or add a size unit among as follows: K, KB, M, MB, G, GB, T, TB (case insensitive) with no space between value and unit. For instance: “10Gb”, “500k” or “512000”.

Policy commands

This command shows the policy rules configured for each volume. For now, only the retention policy rule is available. The policy rule edition must be done from the Vawlt platform.

  • show [ <rule-name> ]: return information about the policy rules configured for each volume.

Trash commands

If the retention policy rule is enabled on a volume, these commands allow to search and restore any file or folder from the trash. As several files with the same path can be sequentially removed and sent to the trash, a deletion date is associated with any file and can be used in the search or restore phase.

  • state: return information about the trash content, namely the total number and the total size of files. The files whose retention days left are lower than 7 days and 30 days are respectively given in the “By one week” and “By on month” columns.
  • show match <regex> (on|from|to <date>)*: search files from trash using a regex.
  • show path <path> (on|from|to <date>)*: search files from trash using an exact path.
  • restore match <regex> (on|from|to <date>)*: restore files from trash using a regex.
  • restore path <path> (on|from|to <date>)*: restore files from trash using an exact path.

Date filtering

The date filter format is “YYYY-MM-dd HH:mm:ss”. It can be used to filter files removed on a single date with the ON prefix, or within a date range using the FROM and TO prefixes. For instance:

ON "2022-02-03": files removed the 03/02/2022 regardless of the deletion time.

FROM "2022-02-03 10:00" TO "2022-02-03 12:00": files removed the 03/02/2022 between 10:00 and 12:00.

Regular expression filtering

A regular expression pattern can be used with the “show match” or “restore match” commands. The pattern is case insensitive by default.

Object commands

Object commands are divided into two groups: first the FETCH and STATE commands to deal with files in ARCHIVE volumes and secondly the HISTORY and RESTORE commands to manage file versioning in HOT and WARM volumes.

  • fetch <path>: restore an object from an ARCHIVE volume. The download time depends on the cloud providers initially used to create the volume and can be up to 15h.
  • state <path>: show the current object state after a FETCH command.
  • history <path>: show object version history.
  • restore <path> <version> : set current object version.

Share commands

These commands allow creating/removing shared folders and managing the user access list and the maximum folder size.

  • show <path>: show shared folder information. If the path is a volume, the command returns the volume’s size.
  • create <path> <size> <user>+: initialize the shared object. The path must be an empty directory created in the volume root. The minimum shared folder size is 50 (Gb).
  • remove <path>: remove a shared folder. Beware that the operation cannot be undone. All granted users will no longer have access to the folder and the shared folder content will be removed.
  • grant-access <path> <user>+: grant access to the shared object.
  • revoke-access <path> <user>+: revoke access to the shared object.
  • resize <path> <size>: resize shared folder size.

Unlike other commands, share sizes used in CREATE and RESIZE commands are in “Gb” and must NOT be combined with size units.

In CREATE, GRANT-ACCESS, and REVOKE-ACCESS commands, users are defined as a space-separated list of emails. For instance:

create /my-volume/my-shared-folder 120 john.doe@my-company.com jane.doe@my-company.com

In order to be shared, a folder must fulfill some rules:

  • The folder must already exist, be empty and have the volume folder as a direct parent. In other words, it cannot be located in any subdirectory of the volume folder.
  • The folder name must be between 3 and 63 characters long. It can consist only of lowercase letters, numbers, and hyphens (-). It must begin and end with a letter or number.

Stat commands

Return information about download and upload data queue. Refresh data frequency is 5 seconds.

  • show: show all information.
  • show speed: show download and upload transfer speeds.
  • show buffer: show download and upload buffer sizes.

User commands

These commands allow to change and reset the user password. The reset password operation requires the user recovery code generated at the user account creation.

  • show: show user profile.
  • change-password: change the user password.
  • reset-password: reset the user password.

S3 commands

The Vawlt agent provides an S3 interface designed to receive HTTP or HTTPS requests from any S3 clients intending to have access to a volume. As a requisite, the S3 option must be enabled on the volume and the user must have created S3 credentials.

The S3 data upload can be performed in two ways: using the local cache or the direct-upload mode. With the local cache, the file is sent to the cloud in the background, the advantage is to not block the upload request which can return as soon as the file is fully copied in the cache. With the direct-upload mode, the upload request does not return until the file is completely sent to the cloud and the cache is not used.

  • show: show all information.
  • show state: show interface state.
  • show ssl: whether SSL is enabled.
  • show port: show HTTP or HTTPS port.
  • show private-key: show SSL private key fingerprint.
  • show certificate: show SSL certificate fingerprint.
  • show direct-upload: whether direct upload is enabled.
  • on|off: change S3 interface state.
  • ssl on|off: enable SSL on the server.
  • port <port>: set HTTP or HTTPS port.
  • private-key <path>: set SSL private key path.
  • certificate <path>: set SSL certificate path.
  • direct-upload yes|no: enable direct upload.

Note that it’s necessary to restart the agent for the changes in the S3 interfaces to take effect.


The desktop commands can be divided into two groups. First, the commands to select the volumes and shared folders to be shown in the file system, the user can modify at any time the state of any volume or shared folder: visible or hidden.

The second group of commands is only available on Windows for the moment, it allows to mount a volume into a Windows drive. The drive’s name is the same as the volume’s name but starts with a capital letter. The drives are assigned letters towards the end of the alphabet. Once the drive is created, the volume appears both in the main mount-point (called Vawlt) and in the drive.

  • show: show all information.
  • show state: show interface state.
  • show drive: show volumes mounted as a drive.
  • show volume: show visible volumes.
  • show shared-folder: show visible shared folders.
  • drive <name> on|off: mount/umount volume as drive.
  • volume <name> visible|hidden: show/hide a volume in file system.
  • shared-folder <name> visible|hidden: show/hide a shared-folder in file system

Keystore commands

On-prem storage servers may use self-signed certificates. In this case, these certificates must be stored in the Vawlt keystore otherwise the connection to the storage server will be denied to safety reasons. The keystore sub-menu allows showing, adding, removing, or renaming any self-signed certificate.

  • show: show keystore content. The first column index is used with remove and rename commands.
  • add <path> <name>: load an X509 certificate from disk and store it into the Vawlt keystore.
  • remove <index>: remove a certificate with a given index from the Vawlt keystore.
  • rename <index> <name>: rename a certificate with a given index from the Vawlt keystore.
Was this article helpful to you? Yes No