Blog
Community
VESrepo
libVES.js
libVES.c
VESauth
$>ves
TOS
VES CLI Utility
Overview
ves is a platform-independent command line interface to the libVES.c API library (the default command name is ves). It operates on end-to-end encrypted data stored in the VESvault cloud repository – keys are generated and held by the user, and the server never sees plaintext or unlocked private keys.
The utility covers these areas, reflected in the option groups below:
  • Key management and exchange – create, list, rekey, propagate, and delete Vault Keys; unlock a vault with a VESkey or a session token.
  • Item encryption and sharing – store secrets as Vault Items and share them with other vaults, so each recipient's own key can decrypt them.
  • Stream encryption – encrypt and decrypt arbitrarily large files or streams with a symmetric cipher key that is itself stored and shared as a Vault Item.
  • Offline encryption – encrypt and decrypt items and streams with a key pair kept on disk, with no Vault and no network access (ves 1.11 and later).
The latest source code of libVES.c and VES utility can be found in the GitHub repository. Pre-built binaries for *nix and a win32 exe are available in the releases.
Key Concepts
The options throughout this reference act on a few core objects:
  • Primary Vault – the vault of a VESvault account, identified by an email login and selected with -A. It holds the account's primary Vault Key and the VESkeys of the account's App Vaults.
  • App Vault – an application- or device-scoped vault within an App Domain, addressed as [ves:]//domain/externalId/ and selected with -a. Each App Vault has its own Vault Key.
  • Vault Key – the asymmetric key pair of a vault. Its private key is kept encrypted at rest and is unlocked by a VESkey.
  • VESkey – the secret that unlocks a Vault Key. VESlocker guards PIN-based VESkeys against brute force, and VESrecovery™ can restore a lost key chain without exposing private data.
  • Vault Item – a unit of encrypted data – a secret value, a stream cipher key, plus optional metadata – addressed by external or internal id and selected with -o. Sharing an item re-encrypts its content key to each recipient's Vault Key.
  • Temporary Vault Key – an interim key auto-created when sharing with a vault that does not exist yet; the owner adopts it later through key propagation.
The general invocation form is:
ves [authentication] operation ...
Options are evaluated left to right. A value-bearing option (e.g. -a, -o, -i) can be immediately followed by a modifier – -p to print the current value, or -f / -F to redirect the value to/from a file or a file descriptor.
VES Utility Usage
ves -A myaccount@gmail.com -a ves://demo/myaccount@gmail.com/ -n -upf my.key
Log in to an existing VESvault account myaccount@gmail.com (VES utility will prompt to enter the password and the primary VESkey).
Create a new App Vault within an App Domain demo, assign an external ID myaccount@gmail.com (If an App Vault with the selected external ID already exists, an error message will be shown).
Generate a random VESkey for the App Vault, save it to a local file my.key.
ves -A myaccount@gmail.com -l
List all Vault Items stored in the Primary Vault.
ves -A myaccount@gmail.com -a ves://demo/myaccount@gmail.com/ -upf my.key
Output the currently stored VESkey for the App Vault ves://demo/myaccount@gmail.com/ to a file my.key.
ves: in the beginning of a URI can always be omitted
ves -a //demo/myaccount@gmail.com -uf my.key -o myItem1 -i "My Secret" -s "myfriend1@yahoo.com/My Friend <myfriend1@yahoo.com>"
Unlock the App Vault ves://demo/myaccount@gmail.com/ using a VESkey stored in a local file my.key. Store a secret text "My Secret" in a User Vault Item ves://demo/myItem1 (the App Domain for the item defaults to the App Vault's domain).
If the item didn't exist, it will be created.
Share the item with an App Vault ves://demo/myfriend1@yahoo.com/, so the VESkey for ves://demo/myfriend1@yahoo.com/ can be used to decrypt the content of this item.
If this App Vault didn't exist, create a temporary App Vault key belonging to a VESvault account myfriend1@yahoo.com.
If this VESvault account didn't exist, create a pending account and send a setup link to an email address myfriend1@yahoo.com.
ves -a //demo/myaccount@gmail.com/ -uf my.key -l
List all Vault Items stored in the App Vault ves://demo/myaccount@gmail.com/.
ves -a //demo/myaccount@gmail.com/ -uf my.key -o myItem1 -ip
Print the content of the Vault Item ves://demo/myItem1. If the item didn't exist, or wasn't shared with App Vault ves://demo/myaccount@gmail.com/, an error will be thrown.
ves -a //demo/myaccount@gmail.com/ -uf my.key -o myItem1 -s myfriend2@yahoo.com/
Share the Vault Item ves://demo/myItem1 with an App Vault ves://demo/myfriend2@yahoo.com/. If this App Vault doesn't exist, an error will be thrown.
The sharing status of the item with any other App Vaults will remain unchanged.
ves -a //demo/myaccount@gmail.com/ -uf my.key -o myItem1 -S myaccount@gmail.com/,//x-my-domain/myfriend3@yahoo.com/myfriend3@yahoo.com
Share the Vault Item ves://demo/myItem1 with App Vaults ves://demo/myaccount@gmail.com/ and ves://x-my-domain/myfriend3@yahoo.com/.
The latter App Vault will be automatically created for user myfriend3@yahoo.com if it didn't exist.
If the item was shared with any other vaults, the sharing will be removed.
The sharing list must include an App Vault of the item's owner, otherwise an error will be thrown.
ves -a //demo/myaccount@gmail.com/ -uf my.key -o myItem1 -X
Explore the Vault Item ves://demo/myItem1 – display various information about the item in a human readable format.
Explore is the default action, -X can be omitted if no other actions are specified.
ves -a //demo/myaccount@gmail.com/ -uf my.key -o myCipher1 -e -Pf test.txt -Cf encrypted.ves -s myfriend1@yahoo.com/
Create a stream cipher with a random key using the default algorithm. Store the cipher key in a User Vault Item ves://demo/myCipher1.
Encrypt an existing local file test.txt with the cipher, save the encrypted content to a local file encrypted.ves.
Share the cipher key with an existing App Vault /demo/myfriend1@yahoo.com.
ves -a //demo/myaccount@gmail.com/ -uf my.key -o myCipher1 -d -Pf decrypted.txt -Cf encrypted.ves -ipf cipher.key
Decrypt a local file encrypted.ves using the stream cipher info stored in the Vault Item ves://demo/myCipher1.
Save the encrypted content to a local file decrypted.txt.
Save the raw binary cipher key data to a local file cipher.key.
ves -a //demo/myaccount@gmail.com/ -uf my.key -o myCipher2 -c AES256GCM1K -if cipher.key -e -Pf test.txt -Cf encrypted2.ves
Create a stream cipher with a raw key loaded from a file cipher.key using algorithm AES256GCM1K.
Store the cipher info in a User Vault Item ves://demo/myCipher2.
Encrypt an existing local file test.txt with the cipher, save the encrypted content to a local file encrypted2.ves.
ves -a //demo/myaccount@gmail.com/ -uf my.key -o myCipher2 --delete
Delete the Vault Item ves://demo/myCipher2.
Deleted and overwritten items are stored in VESvault for some time, and can be accessed by their internal VESvault ID.
ves -a //demo/myaccount@gmail.com/ -uf my.key -l
List all Vault Items stored in the App Vault ves://demo/myaccount@gmail.com/.
Demo App Vault
The existing App Vault ves://demo/demo/, with App VESkey demo, can be used by anyone for test purposes.
Do not store any private information in the Demo App Vault. There is no privacy expectation associated with the Demo App Vault, as its VESkey is publicly available.
Offline Usage
Without a Vault, ves encrypts and decrypts with keys kept on disk, and makes no network requests. See Offline Operations for the details.
Offline data has none of the Vault's recovery, sharing or event history: the private key and its VESkey are the only way back in.
ves -g -ypf my.key.pem -Ypf my.pub.pem -vpf my.veskey
Generate a key pair with the default algorithm (OQS, ML-KEM-768). Save the private key to my.key.pem, encrypted with a newly generated VESkey saved to my.veskey, and the public key to my.pub.pem.
ves -Yf my.pub.pem -Yf friend.pub.pem -e -Pf test.txt -Cf encrypted.ves
Encrypt a local file test.txt to encrypted.ves for two recipients. A random cipher key is generated and written, encrypted for each public key, in a header at the start of encrypted.ves.
ves -yf my.key.pem -vf my.veskey -d -Cf encrypted.ves -Pf decrypted.txt
Decrypt encrypted.ves with the private key: the cipher key is read from the stream header.
Without -P and -C, both commands read STDIN and write STDOUT, so they work through pipes.
ves -Yf friend.pub.pem -i "My Secret" > secret.ves
Encrypt a short secret for the public key friend.pub.pem, print the item ciphertext.
ves -yf friend.key.pem -vf friend.veskey -If secret.ves
Decrypt the item ciphertext from secret.ves, print the secret.
Command Line Options
Authentication and Vault Management
-a URI, --account=URI
Select an App Vault. URI is an App Vault URI, [ves:]//domain/externalId/.
This option is required for most operations.
-E [flag[,flag...]], --keystore[=flag[,flag...]]
Use a local Encryption Key Store, so the App VESkey can be unlocked via a VESlocker PIN dialog and/or cached locally for subsequent access without re-entering the PIN.
Without any flag the default behavior is applied. One or more comma-separated flags fine-tune the Key Store:
  • default – Default options.
  • nopin – Disable the VESlocker PIN dialog, fail if no plaintext key is stored. Does not disable the PIN dialog on sync; use nopin,nosync to do so.
  • nosync – Disable VES account syncing, fail if not previously synced.
  • sess – No App VESkey required, use a persistent session token for write-only Vault access if available.
  • save – Save a plaintext App VESkey for further access without a PIN. Use save,sess to save a persistent session token.
  • forget – Delete a previously synced account, a saved plaintext App VESkey (forget,nopin) or a session token (forget,sess).
  • resync – Force VES account syncing.
  • primary – Use the primary session token and keep the Primary Vault unlocked. Typically combined with elevate when creating or rekeying secondary keys.
  • persist – Obtain a persistent, non-expiring session token. Implied by sess,save.
  • elevate – Elevated authorization for the Primary Key, required for managing secondary keys. When creating a new secondary key from a synced account, combine with primary (e.g. save,elevate,primary) so the primary stays unlocked through the post.
-El
List the available Key Store flags.
-u VESKEY, --unlock=VESKEY
Unlock the App Vault using the VESKEY.
-uf FILE
Read the VESkey from FILE.
Since the command line arguments can be visible to other processes in the system, it is not secure to pass an opentext VESkey in a command line. This option is recommended to be used with the -f modifier to read the VESkey from a file with restricted access – -uf FILE.
-up, -upf FILE
Print the VESkey that unlocks the App Vault selected with -a.
Since the App VESkeys are stored in the Primary Vault, this option is intended to be used in conjunction with -A.
If used with the -f modifier – the App VESkey will be saved to the file that can be used later with -uf FILE.
-A LOGIN, --primary-account=LOGIN
Select a VES Account / Primary Vault. LOGIN is an email address associated with a VESvault account, or a Primary Vault URI (ves:////email).
-T TOKEN, --token=TOKEN
Authorize the API session using a token created by another session or by delegate login.
-Tp, -Tpf FILE
Print the Session Token assigned to the current API session.
-L, --lock
Authorize the API session but keep the Vault locked.
If used with -A – do not ask for the primary VESkey.
If used with -a – the App Vault needs to be unlocked to decrypt the session authorization token, lock the Vault upon that.
-n, --new
Create an App Vault identified by -a.
-a and -A are required. -G, -y and -u will be used when generating the Vault Key if provided.
Vault Item Operations
-o URI, --vault-item=URI
Select a Vault Item for further actions. URI is a VES Vault Item URI, [ves:][//domain/]externalId or [ves:]///internalId.
-O and --object are accepted as aliases of -o and --vault-item.
-i DATA, --item=DATA
Set the raw content of the Vault Item.
-if FILE
Content for the Vault Item is to be retrieved from FILE.
Vault Items in the VESvault repository are subject to a 16K soft size limit. For large files, stream encryption should be used. See -e, -d, -P and -C.
-ip, -ipf FILE
Print the raw content of the Vault Item.
-s URI[,URI...], --share=...
Share the Vault Item with the specified Vaults identified by Vault URIs, [ves:][//domain/]externalId/[userRef]. Any previously existing shares with other Vaults will remain intact.
-r URI[,URI...], --unshare=...
Stop sharing the Vault Item with the Vaults identified by URIs. Sharing with any other Vaults will remain intact.
-S URI[,URI...], --set-share=...
Share the Vault Item with the Vaults identified by the URIs, and only with these Vaults. Previously existing shares with any other Vaults will be removed.
The list of URIs must include the creator's Vault, otherwise the API will reject the action.
-Sp, -Spf FILE
Print the share list for the item, one share per line:
key_id <SP> key_uri <SP> key_type <LF>
The -p modifier applies equally to -s (-sp, -spf FILE).
-m JSON, --meta=JSON
Specify plaintext metadata for the Vault Item. A 16K size limit applies.
The Vault Item metadata is stored in an unencrypted form. Do not store any private information here, use cipher metadata -z instead.
-mp, -mpf FILE
Print JSON plaintext Vault Item metadata.
--delete
Delete the Vault Item.
A deleted Vault Item can be accessed by internal id for some time – ves:///internalId. -U can be used to restore a deleted item.
-U, --force
Force the update of the Vault Item. Suppress an error on unsafe operations, such as overwriting a cipher key.
If the Vault Item is shared with any lost Vault Key, -U will reshare the item with the currently active key for the target Vault.
When used on a deleted Vault Item, the item will be restored and shared with the same Vaults it was shared with before the deletion, unless directed otherwise by -s | -r | -S.
-X, --explore
Print human readable information about the selected Vault Item.
Explore is the default action when no other read/write action is specified, so -X can usually be omitted.
Stream Cipher Operations
All Stream Cipher actions require -o to select the Vault Item that stores the symmetric cipher key, and can be combined with other Vault Item options. Without -o they run offline, see Offline Operations.
-c ALGO, --cipher=ALGO
Create a new stream cipher key for ALGO.
Can be combined with -i to supply a raw binary key. Otherwise the key will be generated randomly.
-cp, -cpf FILE
Print the algorithm of the cipher key.
Results in an error if the Vault Item does not store a cipher key.
-cl
List supported stream cipher algorithms.
-z JSON, --cipher-meta=JSON
Specify secret metadata for the cipher key.
The secret metadata is stored in an encrypted form along with the cipher key.
Subject to a 16K soft limit for an encrypted Vault Item size.
-zp, -zpf FILE
Print JSON secret cipher metadata.
-e, --encrypt
Encrypt a file or a stream using the stream cipher key.
The plaintext input is specified by -P, defaults to STDIN.
The ciphertext output is specified by -C, defaults to STDOUT.
If the selected Vault Item did not exist, or did not store a cipher key, a new cipher key will be generated.
-d, --decrypt
Decrypt a file or a stream using the stream cipher key.
The ciphertext input is specified by -C, defaults to STDIN.
The plaintext output is specified by -P, defaults to STDOUT.
-P[f] FILE, --plaintext=FILE
Select a plaintext file for -e | -d.
-C[f] FILE, --ciphertext=FILE
Select a ciphertext file for -e | -d.
Vault Key Operations
Vault Key operations that produce output – -l and -*p – apply to:
  • The Vault Key selected with -k,
  • if -k is not supplied – to the App Vault Key selected with -a,
  • if -a is not supplied either – to the current Primary Vault Key selected with -A.
Vault Key operations that supply a value – -y, -G, -v – apply to every generated Vault Key:
  • A newly generated App Vault Key when used with -n,
  • A Vault Key generated for a Vault identified by -k, if it didn't exist or was forced by -g,
  • Every Temporary Vault Key generated when sharing with non-existing Vaults – -s | -S.
Using the same private key and/or VESkey for temp keys created for different users is a potential security issue.
-k URI, --vault-key=URI
Select a Vault Key for further operations. The URI is a Vault URI, [ves:][//domain/]externalId/[userRef].
-l, --list
List all Vault Items shared with the Vault Key.
-v VESKEY, --veskey=VESKEY
Supply a VESkey for any generated Vault Keys, and/or to unlock the key specified with -k.
The latter case is useful for lost Vault Keys, and for Temporary Vault Keys when the VESkey is communicated out of system instead of using key propagation.
-vp, -vpf FILE
Print the VESkey that unlocks the Vault Key.
Can be used only if the Vault Key is unlocked indirectly by a VESkey stored in a vault.
-g, --generate
Force generation of a new Vault Key to replace the selected Vault Key. API restrictions apply.
With none of -o, -a, -A, -k, generates a key pair offline, see Offline Operations.
-y KEY, --private-key=KEY
Supply a PEM private key for the generated Vault Key.
-yf is more practical than plain -y.
With none of -o, -a, -A, -k, the private key is used offline, see Offline Operations.
-yf FILE
Private key from the PEM FILE.
-yp, -ypf FILE
Print the PEM private key, non-encrypted if the Vault Key is unlocked, encrypted otherwise.
-Y[p], --public-key, -Ypf FILE
Print a PEM public key.
In offline mode, -Y KEY and -Yf FILE supply a public key to encrypt with, see Offline Operations.
-G ALGO, --key-algo=ALGO
Specify an algorithm to generate the Vault Key.
-Gp, -Gpf FILE
Print the name of the selected Vault Key algorithm.
-Gl
List supported Vault Key algorithms.
--delete
Delete the Vault Key. API restrictions apply.
-R, --rekey
Rekey the Vault Key – re-encrypt all Vault Items with the active key for the matching Vault. Useful for temp keys, and for lost and found keys.
Rekeying is done automatically for temp keys, unless --manual is specified.
-K, --propagate
Propagate the Vault Key – share the Vault Item that stores the VESkey with the owner of the Vault Key.
Propagation is done automatically for temp keys, unless --manual is specified.
--manual
Manual key management – disable automatic propagation and rekeying for Temporary Vault Keys.
-X, --explore
Print human readable information about the selected Vault Key.
Explore is the default action when no other read/write action is specified.
Offline Operations
Stream encryption and decryption (-e, -d) and item crypto (-I, -Y KEY) without -o, and a private key (-y) or key pair generation (-g) with none of -o, -a, -A, -k, run offline: they use the one key given on the command line, with no Vault and no network access. Options that need a Vault (-a, -A, -k, -T, -u, -E, -s, -r, -S, -l, -n, -R, -K, -U, -L, -W, -X, --delete) are rejected. Available in ves 1.11 and later.
Offline data has none of the Vault's recovery, sharing or event history. The public key is trusted as given: nothing ties it to a Vault identity, so obtain it from a source you trust.
-Y KEY, -Yf FILE
The PEM public key to encrypt with.
For stream encryption -Y may repeat, one per recipient; one -G applies to all of them.
-y KEY, -yf FILE
The PEM private key to decrypt with; its public key also encrypts. Supply -v VESKEY or -vf FILE if the PEM is encrypted.
Only one of -g, -y and -Y may be given.
-g
Generate a key pair. The private key must be saved with -ypf FILE; -Ypf FILE saves the public key.
-G ALGO
The algorithm of the -Y public key or the -g key pair, OQS by default. ALGO may carry options as listed by -Gl, such as RSA:4096.
The algorithm of a -y private key is detected from the PEM unless -G is given.
-yp, -ypf FILE, -vp, -vpf FILE
-yp prints the private key as a plain PEM, unless -vp asks for a VESkey: then the PEM is encrypted with -v VESKEY, or with a newly generated VESkey, and -vp prints the VESkey.
-g -v VESKEY also encrypts the new private key with VESKEY.
-I DATA, --item-ciphertext=DATA
The item ciphertext, base64, to decrypt with -y.
It is the same encData a Vault Item stores for each share.
-If FILE
Read the item ciphertext from FILE.
-Ip, -Ipf FILE
Encrypt the item content (from -i, or the stream cipher key) with the key, and print the item ciphertext.
-i DATA, -if FILE
The plaintext to encrypt, or a raw stream cipher key. -ip, -ipf FILE print the decrypted plaintext, or the raw cipher key.
A raw cipher key is used as is, with no key derivation, and must be at least 32 bytes.
Item encryption and decryption
-Y KEY -i DATA prints the item ciphertext, and -y KEY -I DATA prints the plaintext, unless other output is requested.
Stream encryption and decryption
-e generates a cipher key for -c ALGO (default AES256GCM1K), unless -i or -I supplies one. With -Y, -y or -g, the cipher key goes in a stream header written ahead of the ciphertext, encrypted for each key. -Ipf FILE saves it apart instead, encrypted for one key, and -ipf FILE saves it raw; with neither a key nor -ipf, a generated cipher key is refused. The key is saved before any ciphertext is written.
-d -y KEY reads the cipher key and its algorithm from the stream header. With -I and -y, or -i, the key is apart and the stream has no header: the algorithm comes from -c, else from the a field of -m JSON, else AES256GCM1K.
Stream header
Three lines ahead of the ciphertext: 
ves/1
{"meta":{"a":"AES256GCM1K",...},"entries":["encData",...]}
--- MAC
Each encData is the cipher key encrypted for one recipient, as -Ip prints it; -d tries each with the -y key, so the header does not name its recipients. MAC is a base64 HMAC-SHA256 over the first two lines, keyed by HKDF-SHA256 of the cipher key with info ves/1 header mac, so a modified header is refused before any plaintext is written.
Event Tracking
-W [SPEC], --events[=SPEC], --watch[=SPEC]
Track events. The scope follows the selected object:
  • -o – a single Vault Item,
  • -k – a Vault Key,
  • -A – a VES Account,
  • -a – an App Vault (use //domain// for domain-wide events).
SPEC selects the range and follow behavior, [COUNT | =ID[:COUNT]][+[SECONDS]]:
  • (none) – the last 16 events,
  • COUNT – the last COUNT events,
  • =ID – events starting from event id ID (up to 16),
  • =ID:COUNT – COUNT events starting from event id ID,
  • + – follow: keep streaming new events,
  • +SECONDS – follow, but stop after SECONDS,
  • COUNT+ – the last COUNT events, then follow.
Output, one event per line:
id <TAB> time <TAB> type <TAB> key_id <TAB> item_id <TAB> actor <TAB> vault_uri <TAB> item_uri <TAB> ref_id <LF>
ref_id is the session id, when available.
Combine with -X for verbose, human-readable output.
Action Modifiers
-p, --print
Print the current value of the preceding option.
Can be used with almost any option that supplies a value, as listed in the preceding sections.
-f FILE, --file=FILE
Read a value from, or write to, a file.
Can be used with any option that supplies a value, or produces an output.
-F FDESC, --fd=FDESC
Read a value from, or write to, a file descriptor.
Similarly to -f, can be used with any option that supplies a value, or produces an output.
Miscellaneous
-x, --debug
Display debugging messages.
-xx
More detailed debugging.
-q, --quiet
Suppress error messages, except for arg errors. Return error codes only.
Can be used with -o to check if the Vault Item exists. The exit code is: No authorization is needed to check for the existence of a Vault Item.
--api-url=URL
Override the VESvault API endpoint URL.
Intended for development and testing. Defaults to the public VESvault API.
--www-url=URL
Override the VESvault web (front-end) endpoint URL, used to build setup and recovery links.
Intended for development and testing.
-V, --version
Print version information and exit.
-h, --help
Print the help screen and exit.
Exit Codes
VESvault  »  Developer Center  ·  Security  ·  Community
© 2026 VESvault Corp