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​

On this page