CLI Guide

Vendia Share is accessible via a GraphQL API, and can be called from any https-capable client or language. The Vendia Share CLI is provided as an easy way to access Share's capabilities from a Mac, Linux, or other compatible command line. This page documents the CLI; for information on using the GraphQL API directly (for example, to build your own CLI or interact with Vendia Share programmatically), see the Vendia Share GraphQL Schema.

This is an early access ("beta") release. Your use is governed by the terms of the beta release agreement.

Supported Cloud Platforms and Regions

This release is supported on AWS only, in the following AWS regions:

  • us-east-2
  • us-east-1
  • us-west-2
  • sa-east-1
  • ap-south-1
  • ap-northeast-2
  • ap-southeast-1
  • ap-southeast-2
  • ap-northeast-1
  • eu-central-1
  • eu-west-1
  • eu-west-2

Installing Vendia Share CLI Prerequisites

The share CLI is implemented in NodeJS and requires at least Node v12 to be installed in your environment. We recommend the latest available LTS, but it is not required.

You will also need /bin/bash or /bin/zsh installed. Refer to your local sysadmin for assistance if this executable is not available.

Downloading the Vendia Share CLI

You can download the Share CLI directly from npm or install via npm install -g @vendia/share-cli. You should then be able to execute the share command from your bash or zsh shell.

npm install -g @vendia/share-cli
which share

For a list of limitations and known issues in this release, see the Release Notes.

Checking Your Subscription

You must be signed up for Vendia Share in order to use its APIs; otherwise, any attempt to invoke the APIs (directly or via the CLI) will result in an "unauthorized user" error message. You will need the user id and password for the following steps.

If you don't have those, or don't remember them, contact Vendia for assistance.

To log in, run share login:

% share login
> Enter your email address
Username: me@vendia.net

> Enter your vendia password for me@vendia.net
Password: ********************

✔  Logged in as me@vendia.net

If your login expires, the share CLI will prompt you to log in again during any other command.

Understanding Uni Registration

Creating a new Uni is easy - all you need is a valid JSON schema to define the data model and a few pieces of metadata, including names for the uni and its nodes, along with the Vendia user ids to which each node belongs and their regions.

If a uni has nodes from more than one owner (i.e., two or more nodes have different Vendia user ids), then each of the owners must call register separately to create their nodes. Each call must have the same "global" information (uni name, schema, list of nodes, and - if present - initial state). This intentional redundancy ensures that all participants are aware of, and in agreement regarding, the sharing relationship being constructed.

Individual participants will not necessarily all call register at the same time. Vendia Share will track the status of the registration process and will only initialize the uni once all participants have signed up.

The process of registration is asynchronous, even if all nodes are owned by the same Vendia user. Nodes are created and deployed in parallel, and usually take just a few minutes to construct.

See detailed documentation on the format of the registration and other files.

Running the Shape Demo

Download the shape demo files and unzip them. Note that the shape registration file contains a relative path to the schema and initial state files, so you should either run the register command from within the sample directory or modify these paths to suit your installation location.

To create a new shape uni, change the registration file to customize it:

  1. Choose a unique name that starts with "test-". Using that prefix will ensure that you can delete the uni later on and recover the name for future use.
  2. Change the user id's to match your own.

Then run

share uni create --config shapes.json

If all goes successfully, you will receive a message that construction is in progress. To see the list of unis you have, including ones being deployed, you can use

share uni list

to list all the unis associated with your account. You can get detailed information on a specific uni with

share uni get --uni <uni_name_here>

After a few minutes have passed, your shapes uni should be ready to use; you can confirm that by checking the status returned from the get call - once the status is RUNNING your uni is ready to use. At this point you can also retrieve the GraphQL API details needed to use your uni. These are also output by the get command:

Uni Name:    an-example-uni.unis.vendia.net
Uni Status:  RUNNING
Node Count:  1
Node Info:
└─ ⬢ TestNode
   ├─ name: TestNode
   ├─ status: RUNNING
   └─ resources:
      ├─ graphqlurl https://somewhere.execute-api.us-east-2.amazonaws.com/preview/
      ├─ graphqlapikey SECRETKEY
      ├─ sqs https://sqs.us-east-2.amazonaws.com/130453501410/ingressQ_an-example-uni_TestNode
      └─ s3bucketarn arn:aws:s3:::an-example-uni-1-testnode-bucket83908e77-zyhicf3p9ju3

The graphqlurl and graphqlapikey are what you will need to add / read data from the node, and presents a GraphQL API generated from the JSONschema provided earlier. If you want to explore, open vendia.net and click on your uni to get a GraphQL explorer session that is preloaded with your schema and some sample quries.

In the resources list returned by get, you'll see graphqlurl and graphqlapikey. Open the add-shape and list-shapes scripts in the shapes example directory and modify their API configuration information to match those resources, then save the file. Note that each script requires both the client api key and the client api url.

Even though you haven't created any transaction yet, you can already view the shapes created by your initial state by running the following from within your shapes example directory:

./list-shapes

You can add new shapes by running the add-shape script:

./add-shape yellow hexagon 6

(Note that it can take up 20 seconds for your transaction to be picked up, as consensus will pause for approximately 15 seconds at a time when there is no work to do.)

This should create a new shape. You can repeat the call to list-shapes to get a list of your updated shapes, which should now include a yellow hexagon!

When you're done with your uni, you can delete it:

share uni delete --uni <uni_name>

Summary of Vendia Share CLI Commands

  • share uni create --config <registration_file>: Used to create a new uni or to register additional nodes in an existing uni if there are multiple owners. The register command also allows for optionally providing the schema and initial state filenames as an alternative to provind them in the registration file.
  • share uni get --uni <uni_name>: Retrieves details for uni_name, including the GraphQL API resources needed to access it.
  • share uni list: Lists all unis that you have a node in. Add --json to get more detailed information like the JSONschema for the uni.
  • share uni delete <uni_name>: Deletes uni_name, including all nodes and resources associated with it.
  • share uni node get --uni <uni_name> --node <node_name>: Retrieves settings for node node_name in uni uni_name.
  • share uni node update --uni <uni_name> --node <node_name> --config '{<new_settings>}': Replaces settings for node node_name in uni uni_name with the values in new_settings. The format of new_settings is JSON syntax. An example to set the SNS block reporting email to foo@bar.com would look like: '{"blockReportEmails":["foo@bar.com"]}'. Additional emails can be specified, separated by commas like any JSON list. Note that running config sets all the settings; if you do not mention a previously applied setting, it is implicitly assumed to be deleted and will be removed. As a best practice, fetch your existing settings (with the share uni node get command), update them to correspond to the new set you want in place, and then use that as the argument to config. Supported settings include:
    * `blockReportEmails` - An array of addresses to which block creation reports are emailed
    * `blockReportWebhooks` - An array of URLs to which block creation reports are POSTed
    * `aws_blockReportLambdas` - An array of Lambda ARNs which are invoked asynchronously to send block creation reports. Note that these accounts must have permitted inbound access from your Vendia Share proxy account, or permit anyone to invoke them, in order to be called successfully. Only AWS-based nodes
    can use this type of setting.
    * `aws_blockReportSQSQueues` - An array of SQS URLs which will receive block creation messages. Note that these queues must have
    permitted inbound access from your Vendia Share proxy account, or permit anyone to send to them, in order to be called successfully.
    Only AWS nodes can use this type of setting.
    * `aws_SQSIngressAccounts` - A list of AWS accounts authorized to send pending transactions to `node_name`. These accounts can then use
    whatever mechanism they prefer (Lambda, Step Functions, EC2, etc.) to make the SendMessage call. Transactions must be in proper Vendia
    transaction syntax (GraphQL with optional preconditions). Only AWS nodes can use this type of setting.
    * `aws_S3ReadAccounts` - A list of AWS accounts authorized to download Files from the S3 Bucket.
    

Other command-line options:

  • --version: Print the version of the Vendia release and exit.
  • --help: Print a summary of command-line help (can be customized to a specific command).
  • --verbose: Run in verbose mode, providing a more detailed trace of activities.
  • --json: Instead of human-readable tree output, send result to JSON for use in scripts or with jq.

Format of the Registration, Schema, and Initial State Files

A simple registration file looks like:

{
    "name": "test-BasicUni",
    "schema": "schema.json",
    "nodes": [
        {
            "name": "TestNode",
            "userId": "your_user_id",
            "region": "us-east-1"
        }
    ]
}

It has a global section that applies to all nodes in the uni, and a node local section where each node is individually described.

The global section defines the uni's name (which must be unique among all Vendia Share unis), its data model (in the form of a legal v7.0 JSON schema), and an optional initial world state (any JSON that validates successfully against the data model).

Each node defines the name of the node, the Vendia user (by email address) that owns the node, and the region in which the node should reside. The region should be expressed in a format compatible with the cloud vendor that will be used to access that node; in the example above, this is AWS' original US-Eastern region data center, us-east-1.

A more complex example of a registration file is:

{
    "name": "test-TwoAccountUni",
    "schema": "schema.json",
    "initState": "initial-state.json",
    "nodes": [
        {
            "name": "NodeA",
            "userId": "vendia_user_1",
            "region": "us-east-2"
        },
        {
            "name": "NodeB",
            "userId": "vendia_user_2",
            "region": "us-west-2"
        }
    ]
}

In this example you can see two different users owning nodes in two different regions, as well as a reference to an initial state file. Note that in this case, share register must be called twice: once by vendia_user_1 to create NodeA, and once by vendia_user_2 to create NodeB. (These nodes could also be created by the same user using two different user accounts, but would still require making two independent calls to share register.)

The Vendia Share CLI will try to locate your schema and (if provided) initial state files in several ways - you can mix and match any of these techniques and are not required to use the same approach for both.

  • Embedded JSON - simply embed the schema or initial state JSON directly into the registration file. Only "dictionary-style" JSON will be loaded this way (i.e., an embedded schema must start with a { character and end with a } character to be recognized).
  • Network load - names starting with http:// or https:// will be treated as URIs and loaded from a remote source.
  • Any other name is treated as a local filesystem path (both relative and absolute paths are permitted).
  • Finally, you can override the schema and initial state on the share command line as optional arguments to register.

Next Steps

Developing and Using Unis

Defining Your Data Model

Integrating a Vendia chain with other Cloud, Web, and Mobile Services

Learning More

Terms and Definitions

Release Notes

Using File Types

Using Secure Messaging