Skip to content
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 PlatformRegion
AWSus-east-1
AWSus-east-2
AWSus-west-2
AWSeu-west-1
AWSeu-central-1
Azureeastus
Azurewestus2
Azurenortheurope
Azuregermanywestcentral

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.

Terminal window
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:

Terminal window
% 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:

Terminal window
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:

Terminal window
share uni list

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

Terminal window
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:

Terminal window
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.

Terminal window
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:

Terminal window
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:

Terminal window
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:

Terminal window
share uni delete --uni <uni_name>

Summary of Vendia CLI Commands

  • share uni create --config <registration_file>: Used to create a new project or add additional workspaces in an existing project if there are multiple owners.
  • 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 projects that you have a workspace in. Add --json to get more detailed information like the JSONschema for the project.
  • share uni delete <uni_name>: Deletes uni_name, including all workspaces and resources associated with it.
  • share uni node get --uni <uni_name> --node <node_name>: Retrieves settings for workspace node_name in project uni_name.
  • share uni node update --uni <uni_name> --node <node_name> --config '{<new_settings>}': Replaces settings for workspace node_name in project 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.
SettingDescription
blockReportEmailsAn array of addresses to which block creation reports are emailed
blockReportWebhooksAn array of URLs to which block creation reports are POSTed
aws_blockReportLambdasAn 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 proxy account, or permit anyone to invoke them, in order to be called successfully. Only AWS-based workspaces can use this type of setting.
aws_blockReportSQSQueuesAn array of SQS URLs which will receive block creation messages. Note that these queues must have permitted inbound access from your Vendia proxy account, or permit anyone to send to them, in order to be called successfully. Only AWS workspaces can use this type of setting.
deadLetterEmailsAn array of addresses to which failed mutations are emailed
deadLetterWebhooksAn array of URLs to which failed mutations are POSTed
aws_deadLetterLambdasAn array of Lambda ARNs which are invoked asynchronously to send failed mutations. Note that these accounts must have permitted inbound access from your Vendia proxy account, or permit anyone to invoke them, in order to be called successfully. Only AWS-based workspaces can use this type of setting.
aws_deadLetterSQSQueuesAn array of SQS URLs which will receive failed mutations. Note that these queues must have permitted inbound access from your Vendia proxy account, or permit anyone to send to them, in order to be called successfully. Only AWS workspaces can use this type of setting.
aws_S3ReadAccountsA list of AWS accounts authorized to download Files from the S3 Bucket.

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:

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 and Schema

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 workspaces in the project, and a workspace local section where each workspace is individually described.

The global section defines the project’s name (which must be unique among all Vendia projects) and its data model (in the form of a legal v7.0 JSON schema).

Each workspace defines the name of the workspace, the Vendia user (by email address) that owns the workspace, and the region in which the workspace should reside. The region should be expressed in a format compatible with the cloud vendor that will be used to access that workspace; 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",
  "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 workspaces in two different regions. 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 workspaces 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 CLI will try to locate your schema 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 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 in the share command line as optional arguments to share uni create.