# 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](https://www.npmjs.com/package/@vendia/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](https://www.vendia.com/releases). ## 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](https://docs.vendia.com/platform/cli/guide/#format-of-the-registration-and-schema). ## 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 ``` 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 ``` ## Summary of Vendia CLI Commands - `share uni create --config `: Used to create a new **project** or add additional **workspaces** in an existing **project** if there are multiple owners. - `share uni get --uni `: 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 `: Deletes `uni_name`, including all **workspaces** and resources associated with it. - `share uni node get --uni --node `: Retrieves settings for **workspace**`node_name` in **project**`uni_name`. - `share uni node update --uni --node --config '{}'`: 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: `'{