# Command Line

The Persistr Command Line Interface (CLI) makes it easy to create and manage your Persistr spaces directly from the terminal. It's an essential part of using Persistr.

# Download and Install

The CLI is a Node.js app that can be installed with npm version 6 or later.

$ npm install -g @persistr/cli

# Verifying Your Installation

To verify your CLI installation, use the persistr --version command.

$ persistr --version
2.3.5

# Getting Started

After you install the CLI, run the persistr login command to log in with your Persistr account credentials:

$ persistr login admin@example.com
Password: ********
Logged in as admin@example.com

The CLI saves your email address and an API token to ~/.persistr for future use.

Now you're ready to create your first Persistr space:

$ persistr create-space
Created space humorous-visitor-5629

A space in Persistr is similar to a database. It is where all data is stored. In order to save any data to Persistr, you must have a space to save it to. And, similarly, if you delete a space, all data contained in that space will be deleted as well.

In addition to spaces, Persistr has the concept of domains. Each domain defines its own data model and acts as a namespace. You can have multiple domains within a single space.

Let's add our first domain:

$ persistr create-domain -s humorous-visitor-5629
Created domain humorous-visitor-5629.sassy-agreement

Now we are ready to add some data.

# Publishing Events

The basic unit of data in Persistr is an event. Events are organized into streams. Each event can only be contained in one stream. Within a stream, events are automatically arranged chronologically, from oldest to newest.

Streams don't have to exist before you write events to them. If a stream doesn't already exist, it will be created. Every stream must have a UUID as its unique identifier.

Here is an example of how to write a single event into a stream using the CLI:

$ persistr write -s humorous-visitor-5629 -d sassy-agreement -o ce844abe-05f2-4a9b-abec-ac4a055b1a73 '{"data":{"credit":5000},"meta":{"type":"Open Account"}}'
Wrote 1 event

Note that the event has to be a valid JSON string.

# Reading Events

To verify that the event was written into the stream correctly, we can read back all of the events from the stream.

$ persistr read -s humorous-visitor-5629 -d sassy-agreement -o ce844abe-05f2-4a9b-abec-ac4a055b1a73
{ data: { credit: 5000 },
  meta:
   { id: '1e29546f-9bf5-44ff-9e55-adf6092274a5',
     ts: '2018-12-13T05:06:59.028Z',
     tz: 'America/Vancouver',
     type: 'Open Account',
     space: 'humorous-visitor-5629',
     domain: 'sassy-agreement',
     stream: 'ce844abe-05f2-4a9b-abec-ac4a055b1a73' } }

There is our event!

Notice that in addition to the attributes we set when writing the event, Persistr added a few more attributes. Now the event has a unique identifier meta.id which is a UUID. There is also a timestamp when the event was saved as well as a timezone of the local machine that initiated the event write.

The command persistr read can be used to read events from all streams within a given space and domain. To do that, you would simply omit the -o parameter.

# Tailing Events

If you're only interested in new events added to a stream, you can tail the stream.

To see how this works, open two terminal windows. In the first one, execute this command:

$ persistr tail -s humorous-visitor-5629 -d sassy-agreement -o ce844abe-05f2-4a9b-abec-ac4a055b1a73

Then in the second terminal, execute this command:

$ persistr write -s humorous-visitor-5629 -d sassy-agreement -o ce844abe-05f2-4a9b-abec-ac4a055b1a73 '{"data":{"credit":100},"meta":{"type":"Deposit"}}'
Wrote 1 event

If you look at the first terminal window, you'll see that the newly added event was logged to the console:

$ persistr tail -s humorous-visitor-5629 -d sassy-agreement -o ce844abe-05f2-4a9b-abec-ac4a055b1a73
{ data: { credit: 100 },
  meta:
   { tz: 'America/Vancouver',
     type: 'Deposit',
     id: '1d753204-a4ab-4e9a-a253-35ec7f5efae6',
     stream: 'ce844abe-05f2-4a9b-abec-ac4a055b1a73',
     domain: 'sassy-agreement',
     space: 'humorous-visitor-5629',
     ts: '2018-12-13T05:45:26.118Z' } }

This is useful if you want to see, in real-time, what changes are being made to your event streams.

# Reference

You can see a full reference of all Persistr CLI commands here:

CLI Reference

← Use Cases