# CLI

# annotation

persistr annotation -s <space> -d <domain> -o <stream> [new-annotation]

Get, set, or remove stream annotation

Arguments:

-s space name
-d domain name
-o stream ID
new-annotation JSON string (optional)

To set or replace a stream annotation, pass in the new-annotation argument in the form of a JSON string:

$ persistr annotation -s humorous-visitor-5629 -d sassy-agreement -o ce844abe-05f2-4a9b-abec-ac4a055b1a73 '{"hello":"world"}'
Annotated stream humorous-visitor-5629.sassy-agreement.ce844abe-05f2-4a9b-abec-ac4a055b1a73

To display stream annotation, omit the new-annotation argument:

$ persistr annotation -s humorous-visitor-5629 -d sassy-agreement -o ce844abe-05f2-4a9b-abec-ac4a055b1a73
{ hello: 'world' }

If the stream does not have an annotation, undefined is returned:

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

# clone-space

persistr clone-space <source> <destination>

Clone space

Arguments:

source name of space to be cloned
destination name of new space to be created

Destination space must not already exist. It is not possible to clone into a space that already exists.

Example:

$ persistr clone-space humorous-visitor-5629 test
Cloned space humorous-visitor-5629 to test

# create-domain

persistr create-domain -s <space> [domain]

Create a new domain in the given space

Arguments:

-s space name
domain new domain name (optional)

To create a new domain with a specific name, provide the name on the command line:

$ persistr create-domain -s humorous-visitor-5629 newdomain
Created domain humorous-visitor-5629.newdomain

If you omit the domain name, one will be generated for you:

$ persistr create-domain -s humorous-visitor-5629
Created domain humorous-visitor-5629.stark-crack

# create-space

persistr create-space [space]

Create new space

Arguments:

space name of the new space to create (optional)

To create a new space with a specific name, provide the name on the command line:

$ persistr create-space newspace
Created space newspace

If you omit the space name, one will be generated for you:

$ persistr create-space
Created space winged-dress-8764

# destroy-domain

persistr destroy-domain -s <space> <domain>

Destroy domain

Arguments:

space space name
domain name of domain to be destroyed

This is a destructive operation that cannot be undone. You will be prompted to confirm.

When a domain is destroyed, all of its contents are destroyed. This includes all events, event streams, and annotations. Once destroyed, they are unrecoverable.

Example:

$ persistr destroy-domain -s humorous-visitor-5629 stark-crack
WARNING: Domain humorous-visitor-5629.stark-crack and all its contents will be destroyed
WARNING: This action cannot be undone
Confirm by typing in 'YES': YES
Destroyed domain humorous-visitor-5629.stark-crack

# destroy-event

persistr destroy-event -s <space> -d <domain> -o <stream> <event>

Destroy event

Arguments:

space space name
domain domain name
stream stream identifier
event identifier of event to be destroyed

This is a destructive operation that cannot be undone. You will be prompted to confirm.

Example:

$ persistr destroy-event -s humorous-visitor-5629 -d sassy-agreement -o ce844abe-05f2-4a9b-abec-ac4a055b1a73 
WARNING: Domain humorous-visitor-5629.stark-crack and all its contents will be destroyed
WARNING: This action cannot be undone
Confirm by typing in 'YES': YES
Destroyed domain humorous-visitor-5629.stark-crack

# destroy-space

persistr destroy-space <space>

Destroy space

Arguments:

space name of space to be destroyed

This is a destructive operation that cannot be undone. You will be prompted to confirm.

When a space is destroyed, all of its contents are destroyed. This includes all of its domains, events, event streams, and annotations. Once destroyed, they are unrecoverable.

Example:

$ persistr destroy-space humorous-visitor-5629
WARNING: Space humorous-visitor-5629 and all its contents will be destroyed
WARNING: This action cannot be undone
Confirm by typing in 'YES': YES
Destroyed space humorous-visitor-5629

# destroy-stream

persistr destroy-stream -s <space> -d <domain> <stream>

Destroy event stream

Arguments:

space space name
domain domain name
stream identifier of stream to be destroyed

This is a destructive operation that cannot be undone. You will be prompted to confirm.

When an event stream is destroyed, all events contained in the stream are destroyed. Once destroyed, they are unrecoverable.

Example:

$ persistr destroy-stream -s humorous-visitor-5629 -d sassy-agreement ce844abe-05f2-4a9b-abec-ac4a055b1a73
WARNING: Stream humorous-visitor-5629.sassy-agreement.ce844abe-05f2-4a9b-abec-ac4a055b1a73 and all its contents will be destroyed
WARNING: This action cannot be undone
Confirm by typing in 'YES': YES
Destroyed stream humorous-visitor-5629.sassy-agreement.ce844abe-05f2-4a9b-abec-ac4a055b1a73

# export-domain

persistr export-domain -s <space> <domain>

Export domain

Arguments:

space space name
domain domain name

Example:

$ persistr export-domain -s humorous-visitor-5629 sassy-agreement
Exported domain humorous-visitor-5629.sassy-agreement

Each stream in the domain is exported into a separate file in the current working folder. Events are in JSON format, one event per line.

Note that any existing files with the same names will be overwritten as part of the export process without prior warning.

# export-event

persistr export-event -s <space> -d <domain> -o <stream> <event>

Export event

Arguments:

space space name
domain domain name
stream stream identifier
event event identifier

Example:

$ persistr export-event -s humorous-visitor-5629 -d sassy-agreement -o ce844abe-05f2-4a9b-abec-ac4a055b1a73 1e29546f-9bf5-44ff-9e55-adf6092274a5
Exported event humorous-visitor-5629.sassy-agreement.ce844abe-05f2-4a9b-abec-ac4a055b1a73.1e29546f-9bf5-44ff-9e55-adf6092274a5

$ cat humorous-visitor-5629.sassy-agreement.ce844abe-05f2-4a9b-abec-ac4a055b1a73.1e29546f-9bf5-44ff-9e55-adf6092274a5.json
{"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"}}

Inside the file is a single event--the one we exported--in JSON format.

Note that any existing file with the same name will be overwritten as part of the export process without prior warning.

# export-space

persistr export-space <space>

Export space

Arguments:

space space name

Example:

$ persistr export-space humorous-visitor-5629
Exported space humorous-visitor-5629

Each stream in each domain of the space is exported into a separate file in the current working folder. Events are in JSON format, one event per line.

Note that any existing files with the same names will be overwritten as part of the export process without prior warning.

# export-stream

persistr export-stream -s <space> -d <domain> <stream>

Export stream

Arguments:

space space name
domain domain name
stream stream identifier

Example:

$ persistr export-stream -s humorous-visitor-5629 -d sassy-agreement ce844abe-05f2-4a9b-abec-ac4a055b1a73
Exported stream humorous-visitor-5629.sassy-agreement.ce844abe-05f2-4a9b-abec-ac4a055b1a73

$ cat humorous-visitor-5629.sassy-agreement.ce844abe-05f2-4a9b-abec-ac4a055b1a73.json
{"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"}}
{"data":{"credit":100},"meta":{"id":"1d753204-a4ab-4e9a-a253-35ec7f5efae6","ts":"2018-12-13T05:45:26.118Z","tz":"America/Vancouver","type":"Deposit","space":"humorous-visitor-5629","domain":"sassy-agreement","stream":"ce844abe-05f2-4a9b-abec-ac4a055b1a73"}}

The exported event stream is saved in the current working folder. Events are in JSON format, one event per line.

Note that any existing file with the same name will be overwritten as part of the export process without prior warning.

# list-domains

persistr list-domains -s <space>

List all domains in a space

Arguments:

-s space name

Example:

$ persistr list-domains -s humorous-visitor-5629
  sassy-agreement

# list-spaces

persistr list-spaces

List all spaces in currently logged-in account

Example:

$ persistr list-spaces
  humorous-visitor-5629

# list-streams

persistr list-streams -s <space> -d <domain>

Llist all streams in a domain

Arguments:

-s space name
-d domain name

Example:

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

persistr login <email>

Log-in via email and password

Arguments:

email account email address

You will be prompted to type in a password.

Example:

$ persistr login myemail@somedomain.com
Password: ********
myemail@somedomain.com logged in

# logout

persistr logout

Log out

Example:

$ persistr logout
Logged out

# read

persistr read -s <space> -d <domain> -o <stream> [-a after] [-u until] [-i include] [event]

Read one or more events from an event stream

Arguments:

space space name
domain domain name
stream stream identifier
after identifier of event to start reading after
until identifier of event to read until
include what event data or metadata to include (default is -i all)
event event identifier (optional)

To read a single event from the stream, pass in the event identifier:

$ persistr read -s humorous-visitor-5629 -d sassy-agreement -o ce844abe-05f2-4a9b-abec-ac4a055b1a73 1e29546f-9bf5-44ff-9e55-adf6092274a5
{ 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' } }

You can select if data, meta, or both fields will be returned for the event. Pass -i data to display the data field. Pass -i meta to display the meta field. Or pass -i all to display both data and meta fields. Unless otherwise specified, both data and meta fields are displayed in results.

$ persistr read -i data -s humorous-visitor-5629 -d sassy-agreement -o ce844abe-05f2-4a9b-abec-ac4a055b1a73 1e29546f-9bf5-44ff-9e55-adf6092274a5
{ credit: 5000 }

$ persistr read -i meta -s humorous-visitor-5629 -d sassy-agreement -o ce844abe-05f2-4a9b-abec-ac4a055b1a73 1e29546f-9bf5-44ff-9e55-adf6092274a5
{ 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' }

$ persistr read -i all -s humorous-visitor-5629 -d sassy-agreement -o ce844abe-05f2-4a9b-abec-ac4a055b1a73 1e29546f-9bf5-44ff-9e55-adf6092274a5
{ 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' } }

To read all events stored in a stream, omit the event identifier:

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

To only read events after a specific event, pass in the identifier of the event to read after:

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

To read events prior to a specific event, pass in the identifier of the event to read until:

$ persistr read -s humorous-visitor-5629 -d sassy-agreement -o ce844abe-05f2-4a9b-abec-ac4a055b1a73 -u 1d753204-a4ab-4e9a-a253-35ec7f5efae6
{ 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' } }

Options -a and -u can be combined together to read events contained between two known start and end events.

There are two special -a and -u values: past-events and caught-up. To skip historical events and only read real-time events, pass in the -a past-events option. To read historical events but stop prior to real-time events, pass in the -u caught-up option.

Example of reading only past events:

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

Example of skipping past events and reading only real-time events:

$ persistr read -s humorous-visitor-5629 -d sassy-agreement -o ce844abe-05f2-4a9b-abec-ac4a055b1a73 -a past-events

These special -a and -u values can be combined with other options. For example, to read all past events after a specific event but to stop short of real-time events:

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

The persistr read command will seamlessly continue waiting for new real-time events to come in after having read all matching past events. This behavior can be modified by including the -u option. If -u caught-up is provided then persistr read will not read any real-time events. If -u is provided with an event identifier then persistr read will read only past events until the given event is reached and no real-time events will be read.

# rename-domain

persistr rename-domain -s <space> <domain> <newname>

Rename domain

Arguments:

space space name
domain domain name to be renamed
newname new domain name

Example:

$ persistr rename-domain -s humorous-visitor-5629 newdomain rose
Renamed domain from humorous-visitor-5629.newdomain to humorous-visitor-5629.rose

# rename-space

persistr rename-space <space> <newname>

Rename space

Arguments:

space space name to be renamed
newname new space name

Example:

$ persistr rename-space humorous-visitor-5629 humorous-visitor
Renamed space from humorous-visitor-5629 to humorous-visitor

# tail

persistr tail -s <space> -d <domain> [-o <stream>]

Read real-time events

Arguments:

space space name
domain domain name
stream stream identifier (optional)

Tail command skips all past historical events and displays only new real time events for the given event stream.

Note that the tail command is essentially identical to invoking persistr read -s <space> -d <domain> -o <stream> -a past-events or persistr read -s <space> -d <domain> -a past-events.

If -o <stream> argument is ommitted then the tail command will listen to all streams in the given domain.

# truncate-domain

persistr truncate-domain -s <space> <domain>

Remove all content from domain

Arguments:

space space name
domain name of domain to truncate

This is a destructive operation that cannot be undone. You will be prompted to confirm.

When a domain is truncated, all of its contents are destroyed. This includes all events, event streams, and annotations. Once destroyed, they are unrecoverable.

The domain itself remains available in the system but without any content. This is different from the destroy-domain command which destroys the domain as well in addition to the content in the domain.

Example:

$ persistr truncate-domain -s humorous-visitor-5629 rose
WARNING: All contents of humorous-visitor-5629.rose will be destroyed
WARNING: This action cannot be undone
Confirm by typing in 'YES': YES
Truncated domain humorous-visitor-5629.rose

# whoami

persistr whoami

Display information about the currently signed-in user, including name email address

# write

persistr write -s <space> -d <domain> -o <stream> <event>

Write event to a stream

Arguments:

space space name
domain domain name
stream stream identifier
event JSON string

An event is an object with two fields: data and meta. The data field is where all of your custom event attributes go. The meta field is reserved for Persistr use; however, some meta fields are standard and can be set at the time of writing an event:

meta.id unique event identifier (optional). If not present, Persistr will automatically assign a unique identifier to the event.
meta.type event type (optional but highly recommended). The event type is used to differentiate between events. You can set this to any string value. Events with equal meta.type fields will be considered to have the same type.

To write an event to a stream, include the event formatted as a JSON string on the command-line:

$ persistr write -s humorous-visitor-5629 -d sassy-agreement -o ce844abe-05f2-4a9b-abec-ac4a055b1a73 '{"data":{"hello":"world"}}'
Wrote 1 event

$ persistr read -s humorous-visitor-5629 -d sassy-agreement -o ce844abe-05f2-4a9b-abec-ac4a055b1a73 -u caught-up
{ data: { hello: 'world' },
  meta:
   { id: '2f2babb8-417b-4809-8788-0cf0c04fbc05',
     ts: '2018-12-14T04:14:23.750Z',
     tz: 'America/Vancouver',
     space: 'humorous-visitor-5629',
     domain: 'sassy-agreement',
     stream: 'ce844abe-05f2-4a9b-abec-ac4a055b1a73' } }

As you can see, Persistr automatically assigned a unique identifier to the event. It added a few more fields, such as the timestamp and timezone of when the event was written.

To add an event with a known event type, include the meta.type field when you write the event:

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

$ persistr read -s humorous-visitor-5629 -d sassy-agreement -o ce844abe-05f2-4a9b-abec-ac4a055b1a73 -u caught-up
{ data: { hello: 'world' },
  meta:
   { id: '2f2babb8-417b-4809-8788-0cf0c04fbc05',
     ts: '2018-12-14T04:14:23.750Z',
     tz: 'America/Vancouver',
     space: 'humorous-visitor-5629',
     domain: 'sassy-agreement',
     stream: 'ce844abe-05f2-4a9b-abec-ac4a055b1a73' } }
{ data: { hello: 'world' },
  meta:
   { id: '8e3a154c-766f-4351-9fd0-ccf485c69ff4',
     ts: '2018-12-14T04:17:57.440Z',
     tz: 'America/Vancouver',
     type: 'greeting',
     space: 'humorous-visitor-5629',
     domain: 'sassy-agreement',
     stream: 'ce844abe-05f2-4a9b-abec-ac4a055b1a73' } }

Now there are 2 events in the stream. The second event has a meta.type field present. In addition to being useful to your own code to tell events apart, the meta.type field is also displayed in the Persistr Console.

# CLI

# annotation

# clone-space

# create-domain

# create-space

# destroy-domain

# destroy-event

# destroy-space

# destroy-stream

# export-domain

# export-event

# export-space

# export-stream

# list-domains

# list-spaces

# list-streams

# login

# logout

# read

# rename-domain

# rename-space

# tail

# truncate-domain

# whoami

# write