🏁 Usage

🏁 Usage#

Important

In the examples of commands in script mode, olvid-cli can be replaced by any means of launching the CLI (docker or python).

Principle#

The Olvid CLI implements a number of commands divided into groups of commands.

For example, the identity command group brings together a set of commands to manage the identities present on the daemon. Among them, the new, get, and rm commands which respectively allow creating, listing, and deleting identities.

Here are some examples of valid commands:

identity new FirstName LastName
identity get
identity rm 1

At any time, you can get the list of groups, commands, and associated usages by adding --help at the end of your command (even if it’s incomplete).

# list available command groups
--help
# list commands related to identties 
identity --help
# show identity new command usage
identity new --help

Interactive mode / Script mode#

When launching the CLI without passing any argument, by default it launches in interactive mode.

It is also possible to run a command directly by passing it as an argument. For example:

olvid-cli identity get

Will execute the command identity get and then stop automatically. This will be referred to as script mode in next examples.

Current Identity#

Most of the CLI commands require specifying an identity to use. For example, listing discussions or sending a message must be done “as” such an identity.

For this, we will use the identifier of the identity in question (a number). The way to pass this identifier varies depending on the current operating mode of the CLI.

Interactive mode

In interactive mode, the CLI automatically selects the first available identity upon launch. It displays the used identity in the prompt.

However, it is possible to change the user identity using the following command.

# change current identity to 2
1 > identity current 2
# show current identity
2 > identity current
Script mode

In script mode, if necessary, use the option -i to specify the identity to use. For example, to list messages from identity 1.

olvid-cli -i 1 message get

Hint

The option -i must be placed before the start of the command, here before message get.

List items#

All command groups related to an entity (identity, discussion, message, etc.) implement the get command which allows listing associated elements.

To display only certain fields of entities, it is possible to use the -f or –fields option followed by a comma-separated list of field names for the entity in question.

Every get command can also implement its specificities, so we invite you to check the additional options and arguments it might implement using the –help option.

Here are some examples of commands related to the list of items:

# Show display name for every identity
1> identity get --fields display_name
# List id and body of 1st identity messages
1 > message get --fields id,body

Client Key Management#

The key group of commands allows managing client keys for the daemon. It does not require a current identity since client keys are global.

A client key is either associated with an identity, as in the case of client keys used for our programs, or it is an admin client key. Admin client keys allows to choose which identity to use for each API call. This is the case for the client key used by the CLI.

Client keys have an associated name. It is not used and merely serves to help manage them.

Here are examples of commands related to client key management:

# List client keys
key get 
# Create admin client key
key new key-name 0
# Create client key for identity 1
key new my-client-key 1
# Delete a client key (we pass the key, not it's name)
key rm 00000000-0000-0000-0000-000000000000

Storage#

The storage API of the daemon allows for storing arbitrary data as key-value pairs in the daemon’s database.

These elements are all associated with a non-admin user key. This allows both to split storage by client and to correctly restore stored items in case of backup restoration.

To access storage elements using the CLI, it is therefore necessary to specify the client key to use.

Interactive mode
# We specify that, from now, we want to use a different client key than the admin client key 
1 > key impersonate 00000000-0000-0000-0000-000000000000
# Now we can use storage api for this client key 
1 > storage get
Script mode

In script mode, one uses the -k option in a similar way as the -i option.

olvid-cli -k 00000000-0000-0000-0000-000000000000 storage get

Daemon storage contains two types of storage: a global storage and a per-discussion storage. In the latter case, it is possible to store multiple values for the same key in several discussions.

Daemon storage has two main advantages:

  • simplicity of use and deployment: no need to set up a client-side storage system.

  • backup resilience: the storage of the daemon is backed up using the same mechanism as the rest of the daemon’s data. This ensures more robustness, but above all it allows for resilience to changes in identifiers that occur during a backup restoration.