virgil-cli

README

Virgil CLI

Virgil Security introduces to developers a Virgil CLI – a tool to manage your Virgil account and applications. With minimal configuration, you can start using all of the functionality provided by the Virgil from your favorite terminal program.

• Linux shells – Use common shell programs such as Bash, Zsh, and tsch to run commands in Linux, macOS, or Unix.
• Windows command line – On Microsoft Windows, run commands in either PowerShell or the Windows Command Processor.

Content

• Installation
• Launching CLI
• Manage Virgil Account
  • Register new Account
  • Login into Account
  • Logout from Account
• Manage PURE application
  • Update keys
  • Generate a secret key
• Manage E2EE application
  • Create new application
  • Delete application
  • Get list of E2EE applications
  • Update application
  • Set up default Application
  • Create new API Key
  • Delete API Key
  • Get list of API Keys
  • Update API Key
• Manage application cards
  • Config file
  • Search cards
  • Delete card
• Cryptographic operations
  • Generate private key
  • Extract public key
  • Encrypt
  • Decrypt
  • Sign
  • Verify signature
• License
• Support

Installation

The Virgil CLI is provided as a binary file, and it is available for Mac OS, FreeBSD, Linux OS and Windows OS. Download the latest CLI package here: https://github.com/VirgilSecurity/virgil-cli/releases.

Launching Virgil CLI

FreeBSD / Linux / Mac OS

Run the CLI with the following command:

./virgil

or use sudo ./virgil when you need to run the command as an administrator

Windows OS

Run the CLI with the following command:

virgil.exe
# or just `virgil`

To get more information, run the Virgil CLI or its command with the --help or -h option that displays full help list and available commands.

Manage Virgil Account

Register new account

This command is used to create a new account:

# FreeBSD / Linux / Mac OS
./virgil register <email>

# Windows OS
virgil register <email>

Login into account

This command is used to open session for account:

# FreeBSD / Linux / Mac OS
./virgil login

# Windows OS
virgil login

Logout from account

This command is used to close the current session for account:

# FreeBSD / Linux / Mac OS
./virgil logout

# Windows OS
virgil logout

Manage PURE application

Update keys

This command is used to update the app_secret_key and service_public_key of a Pure application

# FreeBSD / Linux / Mac OS
./virgil pure update-keys <service_public_key> <app_secret_key> <update_token>

# Windows OS
virgil pure update-keys <service_public_key> <app_secret_key> <update_token>

Generate a secret key

This command is used to generate a new app_secret_key for a Pure application:

# FreeBSD / Linux / Mac OS
./virgil pure keygen

# Windows OS
virgil pure keygen

Manage E2EE application

Create new E2EE application

This command is used to create new application:

# FreeBSD / Linux / Mac OS
./virgil app create --type e2ee <application name>

# Windows OS
virgil app create --type e2ee <application name>

Note! You have to verify your email in order to be able to create more than one application

Delete application

This command is used to delete application:

# FreeBSD / Linux / Mac OS
./virgil app delete <application_id>

# Windows OS
virgil app delete <application_id>

List applications

This command is used to print list of all user applications:

# FreeBSD / Linux / Mac OS
./virgil app list

# Windows OS
virgil app list

Update application

This command is used to update name of application:

# FreeBSD / Linux / Mac OS
./virgil app update <application_id>

# Windows OS
virgil app update <application_id>

Use application

This command allows you to specify the application that will be used by default. In this way, you'll be able you to use CLI commands without specifying app_id where it's needed.

# FreeBSD / Linux / Mac OS
./virgil use <app_name>

# Windows OS
virgil use <app_name>

Create new api-key

This command is used to create new api-key for current application:

# FreeBSD / Linux / Mac OS
./virgil apikey create --app_id <app_id> <api-key name>

# Windows OS
virgil apikey create --app_id <app_id> <api-key name>

Delete api-key

This command is used to delete api-key:

# FreeBSD / Linux / Mac OS
./virgil apikey delete <api_key_id>

# Windows OS
virgil apikey delete <api_key_id>

List api-keys

This command is used to print list of all users api-keys:

# FreeBSD / Linux / Mac OS
./virgil apikey list

# Windows OS
virgil apikey list

Update api-key

This command is used to update name of api-key:

# FreeBSD / Linux / Mac OS
./virgil apikey update <api_key_id>

# Windows OS
virgil apikey update <api_key_id>

Manage application cards

Config file

Config file is a json, with contains API_KEY, API_KEY_ID, APP_ID

It could be generated on dashboard or by hands

config file example :

{
  "API_KEY": "1234567890",
  "API_KEY_ID": "12345678901234567890",
  "APP_ID": "12345678901234567890"
}

Search cards

This command searches for any Virgil Card by its identity:

# FreeBSD / Linux / Mac OS
./virgil cards search -c <file> <identity>,

# Windows OS
virgil cards search -c <file> <identity>,

flags :
-c  - Config file name.

Delete card

This command deletes Virgil Card by it's id

# FreeBSD / Linux / Mac OS
./virgil cards delete -c <file> -i <identity> <card_id>,

# Windows OS
virgil cards delete -c <file> -i <identity> <card_id>,

flags :
-c  - Config file name.
-i  - Card identity, mandatory.

Cryptographic operations

Generate private key

This command generates a User's Private Key:

# FreeBSD / Linux / Mac OS
./virgil keygen -o <file>  -p <password>,

# Windows OS
virgil keygen -o <file> -p <password>,

flags :
-o  - Key file name. If omitted, stdout is used.
-p  - Use password to encrypt Private Key. If omitted (not recommended), private key will be generated without password

Extract public key

This command extracts a Public Key from a Private Key:

# FreeBSD / Linux / Mac OS
./virgil key2pub -i <file> -o <file>  -p <password>,

# Windows OS
virgil key2pub  -i <file> -o <file> -p <password>,

flags :
-i  - Key's File Name. If omitted, stdin is used.
-o  - Public key's file name. If omitted, stdout is used.
-p  - Use password to decrypt Private Key. 

Encrypt

This command encrypts any data for the specified public key(s):

# FreeBSD / Linux / Mac OS
./virgil encrypt  -i <file> -o <file>  -key <public_key_file_1> -key <public_key_file_2> ...,

# Windows OS
virgil encrypt  -i <file> -o <file> -key <public_key_file_1> -key <public_key_file_2> ...,

flags :
-i  - Data to be encrypted - If omitted, stdin is used..
-o  - Encrypted data. If omitted, stdout is used..
-key  - Public key file (could be many files). 

Decrypt

This command decrypts the encrypted data with a a Private Key:

# FreeBSD / Linux / Mac OS
./virgil decrypt  -i <file> -o <file>  -key <private_key_file> -p <password>,

# Windows OS
virgil decrypt  -i <file> -o <file> -key <private_key_file>  -p <password>,

flags :
-i  - Data to be decrypted - If omitted, stdin is used.
-o  - Decrypted data. If omitted, stdout is used.
-key  - Private key file. 
-p  - Use password to decrypt Private Key. 

Sign

This command signs data with a provided User’s Private Key:

# FreeBSD / Linux / Mac OS
./virgil sign  -i <file> -o <file>  -key <private_key_file> -p <password>,

# Windows OS
virgil sign  -i <file> -o <file> -key <private_key_file>  -p <password>,

flags :
-i  - Data to be signed - If omitted, stdin is used.
-o  - The signed data. If omitted, stdout is used.
-key  - Private key file. 
-p  - Use password to decrypt Private Key. 

Verify signature

This command signs data with a provided User’s Private Key:

# FreeBSD / Linux / Mac OS
./virgil verify  -i <file> -s <file>  -key <public_key_file> ,

# Windows OS
virgil verify  -i <file> -s <file> -key <public_key_file> ,

flags :
-i  - File with data which necessary to verify.
-s  - Digest sign.
-key  - Public key file.  If omitted, stdin is used. 

License

See LICENSE for details.

Support

Our developer support team is here to help you. Find out more information on our Help Center.

You can find us on Twitter or send us email support@VirgilSecurity.com.

Also, get extra help from our support team on Slack.