CLI walk through

Vendia provides share-cli, a Command Line Interface (CLI) for creating and managing Unis. We will be using the share-cli to deploy and manage our Shopping List Uni.

Installation

The share-cli can be installed using the NodeJS Node Package Manager (NPM).

To install the CLI globally, run the following command:

npm install @vendia/share-cli -g

NOTE You can also install Vendia CLI inside a project (instead of globally).

For more information, please visit the @vendia/share-cli NPM package page or view the CLI commands list.

Define Your Uni

Here's where we can use the Uni Schema and Node Config we defined earlier. Remember to make the adjustments to the Node Config to match your userId.

We'll need to create a registration file that contains information about our Uni:

  • Its name

  • Where to find the schema

  • Where to get the Uni's initial data

  • The nodes that are particiapting in the Uni

NOTE You will need to provide your Vendia Share userId when defining your nodes. For the quick start, please use your same userId across all nodes.

ANOTHER NOTE Pick a unique name for your Uni - by default all Unis share a common namespace so here is your chance to get creative.

Sample Registration file - save as registration.json
{
  "name": "test-shopping-list",
  "schema": "schema.json",
  "initState": "initial-state.json",
  "nodes": [{
      "name": "ParentalUnit1",
      "userId": "me@vendia.net",
      "region": "us-west-2"
    },
    {
      "name": "ParentalUnit2",
      "userId": "me@vendia.net",
      "region": "us-west-2"
    },
    {
      "name": "ChildUnit1",
      "userId": "me@vendia.net",
      "region": "us-west-2"
    },
    {
      "name": "ChildUnit2",
      "userId": "me@vendia.net",
      "region": "us-west-2"
    }
  ]
}
Sample Schema file - save as schema.json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://vendia.net/schemas/demos/shopping-list.json",
  "title": "Shopping List",
  "description": "Store shopping list data",
  "type": "object",
  "properties": {
    "ShoppingList": {
      "description": "Items on the shopping list",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "item": {
            "description": "What to buy",
            "type": "string"
          },
          "quantity": {
            "description": "How much to buy",
            "type": "string"
          },
          "recommendedLocation": {
            "description": "Where I should buy",
            "type": "string"
          },
          "bought": {
            "description": "Whether it has been bought",
            "type": "boolean"
          },
          "timestampAdded": {
            "description": "When the item was added",
            "type": "string",
            "format": "date-time"
          },
          "timestampPurchased": {
            "description": "When the item was purchased",
            "type": "string",
            "format": "date-time"
          }
        },
        "required": ["item"]
      }
    }
  }
}
Sample Initial State file - save as initial-state.json
{
    "ShoppingList": [
        {
            "item": "Bread",
            "quantity": "1 loaf",
            "recommendedLocation": "Best Bakery",
            "bought": false,
            "timestampAdded": "2020-12-05T18:43:54Z"
        },
        {
            "item": "Cheese",
            "quantity": "2 lb",
            "recommendedLocation": "Cheesy Charlies",
            "bought": false,
            "timestampAdded": "2020-12-05T14:23:32Z"
        }
    ]
}

Deployment

Once we have the files saved we are able to deploy our Uni using the share-cli.

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.

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. If you don't yet have a user account for Vendia Share you will first need to sign up. If you have an account but have forgotten your username and password you can reset your password.

The share uni create command can be used to deploy our Uni.

share uni create --config registration.json

Check on Uni Status

The Uni deployment will take approximately 4 minutes. We can check on the status of the Uni by running the share get command.

% share get --uni test-shopping-list # Adjust Uni name based on the name you specified
Getting test-shopping-list info...
┌─────────────────────┐
│   Uni Information   │
└─────────────────────┘
Uni Name:    test-shopping-list.unis.vendia.net
Uni Status:  PENDING_REGISTRATION
Node Count:  4
Nodes Info:
├─ ⬢ ParentalUnit1
│  ├─ name: ParentalUnit1
│  ├─ status: DEPLOYING
│  └─ resources:
│     ├─ graphqlurl
│     ├─ graphqlapikey
│     ├─ sqs
│     └─ s3bucketarn
├─ ⬢ ParentalUnit2
│  ├─ name: ParentalUnit2
│  ├─ status: DEPLOYING
│  └─ resources:
│     ├─ graphqlurl
│     ├─ graphqlapikey
│     ├─ sqs
│     └─ s3bucketarn
├─ ⬢ ChildUnit1
│  ├─ name: ChildUnit1
│  ├─ status: DEPLOYING
│  └─ resources:
│     ├─ graphqlurl
│     ├─ graphqlapikey
│     ├─ sqs
│     └─ s3bucketarn
└─ ⬢ ChildUnit2
   ├─ name: ChildUnit2
   ├─ status: DEPLOYING
   └─ resources:
      ├─ graphqlurl
      ├─ graphqlapikey
      ├─ sqs
      └─ s3bucketarn

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

Once the Uni is running we will query and update our Shopping List Uni.

Please refer to the Vendia Share CLI documentation for more detailed information.