Vendia CLI Guide | Vendia

Vendia CLI Guide

Vendia is accessible via a GraphQL API, and can be called from any https-capable client or language. The Vendia CLI is provided as an easy way to access Vendia’s capabilities from a Mac, Linux, or another compatible command line.

Supported Cloud Platforms and Regions

Cloud Platform Region
AWS us-east-1
AWS us-east-2
AWS us-west-2
AWS eu-west-1
AWS eu-central-1
Azure eastus
Azure westus2
Azure northeurope
Azure germanywestcentral

Installing Vendia CLI Prerequisites

The Vendia CLI is implemented in NodeJS and requires at least Node v18 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 CLI

You can download the Vendia 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 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.com

> Enter your vendia password for me@vendia.com

Password: ********************

✔  Logged in as me@vendia.com

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

Understanding Project Registration

Creating a new project 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 project and its workspaces, along with the Vendia user ids to which each workspace belongs and their regions.

If a project has workspaces from more than one owner (i.e., two or more workspaces have different Vendia user ids), then each of the owners must call share uni create separately to create their workspaces. Each call must have the same "global" information ( project name, schema, and list of workspaces). 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 will track the status of the registration process and will only initialize the project once all participants have signed up.

The process of registration is asynchronous, even if all workspaces are owned by the same Vendia user. Workspaces 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 project 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 file, 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.

Universal Application Schema - save as schema.json

{

"$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",

"x-vendia-indexes": {},

"x-vendia-acls": {

"ShapeAcl": {

"type": "Shape"

}

},

"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

}

Registration file - save as registration.json

NOTE: Choose a unique name that starts with test-. Using that prefix will ensure that you can delete the project later on and recover the name for future use.

NOTE: Vendia projects share a global namespace. Get creative with your name.

NOTE: Change the userId to match your own.

{

"name": "test-shapes",

"schema": "schema.json",

"initState": "init-state.json",

"nodes": [
  
    {
  
      "name": "TestNode",
  
      "userId": "me@domain.com",
  
      "region": "us-west-2"
  
    }
  
  ]

}

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 projects you have, including ones being deployed, you can use:

share uni list

to list all the projects associated with your account. You can get detailed information on a specific project with:

share uni get --uni <uni_name_here>

After a few minutes have passed, your shapes project should be ready to use; you can confirm that by checking the status returned from the get call - once the status is RUNNING your project is ready to use. At this point you can also retrieve the GraphQL API details needed to use your project. 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/

│  └─ websocketUrl wss://somewhere-else.execute-api.us-east-2.amazonaws.com/graphql/

├─ 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 the schema, use the --json flag. Example: "share uni get --uni test-schema-evolution.unis.vendia.net --json"

In the resources list returned by get, you’ll see httpsUrl. We will also need an API Key to add and read data from our workspace.

share node add-api-key \

--uni 'an-example-uni' \

--node 'TestNode' \

--name 'my-key' \

We’ll save these two values to use to add and read data:

export HTTPS_URL=your-graphqlapi-https-url

export API_KEY=your-graphqlapi-api-key

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

curl -XPOST ${HTTPS_URL} \

-H "Content-Type:application-graphql" \

-H "Authorization${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 project, you can delete it:

share uni delete --uni <uni_name>

Summary of Vendia CLI Commands