Skip to main content

Get started on your computer with the CLI

Learn the basics of Piiano Vault

This guide gets you started with Piiano Vault using the Dev environment and CLI on your computer.

Step 1: Register for your 7-day development license

Get your development license:

Register to get a free 7-day development license, no credit card required.

Step 2: Install Vault locally

note

This installation is not suitable for production use.

Prerequisites

To install Piiano Vault locally, you need:

  • A computer running macOS, Linux, or Windows
  • Docker
Install Piiano Vault developer edition

Pull and start the Piiano Vault server container, listening on the default Piiano Vault port of 8123:

docker run --rm --init -d \
--name pvault-dev \
-p 8123:8123 \
-e PVAULT_SERVICE_LICENSE={LICENSE_KEY} \
piiano/pvault-dev:1.13.0

When the Docker container starts, you have a running Piiano Vault. You can access Piiano Vault on http://localhost:8123 and interact with it using the Piiano Vault API or the Piiano CLI. The local API reference enables you to experiment with the APIs from your browser.

Step 3: Connecting using the Piiano CLI

The Piiano CLI is a built-in command-line tool to interact with Piiano Vault. The Piiano Vault server includes an up-to-date installation of the Piiano Vault CLI. The CLI is also provided on a dedicated container image or as a stand-alone binary.

  1. To install pvault CLI for macOS, run:

    brew install piiano/tap/pvault-cli
  2. To run as a stand-alone binary, download the pvault CLI for your platform and extract the archive.

  3. To run the pvault CLI as a container and to make working with it easier, create an alias for it to pvault:

    alias pvault="docker run --rm -i --add-host='host.docker.internal:host-gateway' -v \$(pwd):/pwd -w /pwd piiano/pvault-cli:1.13.0"
danger

Docker Desktop displays a warning when mapping the home directory to a container. Therefore, it's recommended that you run this command from a different directory or replace the \$(pwd) in the alias above with the alternative local directory (e.g., /tmp).

You can now check the status of your Piiano Vault container to make sure it's running correctly:

pvault status

You should get this response:

+------+---------+
| data | control |
+------+---------+
| pass | pass |
+------+---------+

Step 4: Create a collection

Now, add a collection to Vault. You create a personal information aware collection like this:

pvault collection add --collection-pvschema "
customers PERSONS (
ssn SSN UNIQUE COMMENT 'Social security number',
email EMAIL,
phone_number PHONE_NUMBER NULL,
zip_code_us ZIP_CODE_US NULL,
)"

You should get a response similar to this:

customers PERSONS (
email EMAIL,
phone_number PHONE_NUMBER NULL,
ssn SSN UNIQUE COMMENT 'Social security number',
zip_code_us ZIP_CODE_US NULL
);

Step 5: Add data

Now add some data:

pvault object add --fields '{ "ssn":"123-12-1234", "email":"john@somemail.com", "phone_number":"+1-121212123", "zip_code_us":"12345", "id": "2b917e1b-c891-458d-ae62-ee01af36bc1e" }' --collection customers
pvault object add --fields '{ "ssn":"123-12-1235", "email":"mary@somemail.com", "phone_number":"+1-121212124", "zip_code_us":"12345", "id": "48e26d47-e1d2-4f51-8fc1-c05a6aec41c0"}' --collection customers
pvault object add --fields '{ "ssn":"123-12-1236", "email":"eric@somemail.com", "phone_number":"+1-121212125", "zip_code_us":"12345", "id": "fc49e2ce-85e5-4e4d-ad36-1b3f27210199" }' --collection customers

💡 When adding objects without an ID, Vault automatically generate a GUID for each object.

As you add each person, you get a response similar to this:

+--------------------------------------+
| id |
+--------------------------------------+
| 2b917e1b-c891-458d-ae62-ee01af36bc1e |
+--------------------------------------+
info

Data in Vault is encrypted at rest. Vault provides automatic key provisioning and rotation. Data is also protected with granular access control and audited access.

Step 6: Query your data

You can return a combination of plain and transformed data in a query. Transformations desensitize personal information. Vault includes built-in transformations, and you can add custom transformations. Each transformation can act on data of the same type, such as email, phone number, or SSN.

pvault object get --id 2b917e1b-c891-458d-ae62-ee01af36bc1e --props ssn.mask,email.mask,phone_number.mask --collection customers

This returns:

Displaying 1 result.
+-------------------+-------------------+-------------+
| email.mask | phone_number.mask | ssn.mask |
+-------------------+-------------------+-------------+
| j***@somemail.com | *******2123 | ***-**-1234 |
+-------------------+-------------------+-------------+

Next steps