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 another 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.

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 share uni create 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 share uni create 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

The shape demo Universal Application (Uni) can be deployed by saving the the following files to your local computer. Note that the shape registration file contains a relative path to the schema and initial state files, so you should either run the share uni create command from within the directory in which the files were created or modify these paths to suit your installation location.

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "http://vendia.net/schemas/demos/basic_schema.json",
    "title": "Sample schema for blockchain demos and testing",
    "description": "A minimal example, modeling a list of Shapes",
    "type": "object",
    "properties": {
        "Shape": {
            "description": "A list of shapes",
            "type": "array",
            "items": {
            "type": "object",
            "properties": {
                "name": {
                    "description": "The common name of the shape",
                    "type": "string"
                },
                "color": {
                    "description": "The color of the shape",
                    "type": "string"
                },
            "num_sides": {
                "description": "How many sides the shape has",
                "type": "number"
            }
        },
        "required": [
            "name",
            "color"
        ],
        "additionalProperties": false
            },
            "minItems": 0,
            "uniqueItems": true
            }
        },
    "additionalProperties": false
}

{
    "name": "test-shapes",
    "schema": "schema.json",
    "initState": "init-state.json",
    "nodes": [
        {
            "name": "TestNode",
            "userId": "me@domain.com",
            "region": "us-west-2",
            "settings": {
                "apiSettings": {
                    "auth": {
                        "authorizerType": "API_KEY"
                    }
                }
            }
        }
    ]
}

{
    "Shape": [
        {
            "name": "square",
            "color": "red",
            "num_sides": 4
        },
        {
            "name": "circle",
            "color": "blue"
        }
    ]
}

Once the files have been downloaded and the registration.json file has been updated, run the following command:

share uni create --config registration.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:

Getting an-example-uni.unis.vendia.net info...
┌─────────────────────┐
│   Uni Information   │
└─────────────────────┘
Uni Name:    an-example-uni.unis.vendia.net
Uni Status:  RUNNING
Node Count:  1
Node Info:
└─ ⬢ TestNode
   ├─ name: TestNode
   ├─ status: RUNNING
   └─ resources:
      ├─ graphqlApi
      │  ├─ httpsUrl https://somewhere.execute-api.us-east-2.amazonaws.com/graphql/
      │  ├─ apiKey SECRETKEY
      │  └─ websocketUrl wss://somewhere-else.execute-api.us-east-2.amazonaws.com/graphql/
      ├─ aws_AsyncIngressQueue
      │  ├─ url https://sqs.us-east-2.amazonaws.com/123456789012/ingressQ_an-example-uni_TestNode
      │  └─ name ingressQ_an-example-uni_TestNode
      ├─ aws_FileStorage
      │  ├─ arn arn:aws:s3:::an-example-uni-1-testnode-bucket83908e77-zyhicf3p9ju3
      │  └─ name testnode-bucket83908e77-zyhicf3p9ju3
      ├─ aws_BlockNotifications
      │  └─ arn arn:aws:sns:us-east-2:158170696360:an-example-uni-1-TestNode-BlockTopic661B6EDF-1G0NDWBH5IESG
      ├─ aws_DeadLetterNotifications
      │  └─ arn arn:aws:sns:us-east-2:158170696360:an-example-uni-1-TestNode-DeadLetterTopicC237650B-1I5KE0PYAZ9EH
      └─ aws_Cognito
         ├─ userPoolId null
         ├─ userPoolClientId null
         └─ identityPoolId null

To display schema & initial state, use the --json flag. Example: "share get test-schema-evolution.unis.vendia.net --json"

In the resources list returned by get, you'll see httpsUrl and apiKey. We will need this information to add and read data from our node.

export HTTPS_URL=your-graphqlapi-https-url
export API_KEY=your-graphqlapi-api-key

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

curl -XPOST ${HTTPS_URL} \
-H "Content-Type:application-graphql" \
-H "x-api-key:${API_KEY}" \
-d "{\"query\": \"query q { list_ShapeItems(limit: 10) { _ShapeItems { name color num_sides id } } } \"}"

You can add a new yellow hexagon by running the following command:

curl -XPOST ${HTTPS_URL} \
-H "Content-Type:application-graphql" \
-H "x-api-key:${API_KEY}" \
-d "{\"query\": \"mutation m { add_Shape_async(input:{color: \\\"yellow\\\", name: \\\"hexagon\\\", num_sides: 6}) { result { id } } }\"}"

This should create a new shape. You can repeat the call to list your updated shapes, which should now include our newly added 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 add additional nodes in an existing Uni if there are multiple owners. The share uni create command also allows for optionally providing the schema and initial state filenames as an alternative to providing 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: 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.    
  * `deadLetterEmails` - An array of addresses to which failed mutations are emailed
  * `deadLetterWebhooks` - An array of URLs to which failed mutations are POSTed
  * `aws_deadLetterLambdas` - An array of Lambda ARNs which are invoked asynchronously to send failed mutations. 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_deadLetterSQSQueues` - An array of SQS URLs which will receive failed mutations. 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",
            "settings": {
                "apiSettings": {
                    "auth": {
                        "authorizerType": "API_KEY"
                    }
                }
            }
        }
    ]
}

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-East 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",
            "settings": {
                "apiSettings": {
                    "auth": {
                        "authorizerType": "API_KEY"
                    }
                }
            }
        },
        {
            "name": "NodeB",
            "userId": "vendia_user_2",
            "region": "us-west-2",
            "settings": {
                "apiSettings": {
                    "auth": {
                        "authorizerType": "API_KEY"
                    }
                }
            }
        }
    ]
}

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 uni create 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 uni create.)

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 share uni create.

Supported Cloud Platforms and Regions

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