veritone-developer-cli

Veritone Developer CLI

⚠️ WARNING: This is under active development and not yet considered stable for production use!

veritone-developer is a command line interface (CLI) for deploying aiWARE applications to an aiWARE instance directly from their source code.

The tool analyzes a specially-formatted manifest.yaml file in the base of a project directory, looks at the difference between the configuration specified there and the live deployment of the application in aiWARE, and calls the aiWARE API to make changes to bring the deployed version of the application inline with the manifest file.

⚠️ WARNING: This means it will CHANGE THINGS IN YOUR ACCOUNT! USE WITH CAUTION!

Usage

For now, we need to git clone this repo and npm link it. In the future, you should be able to use npx or a raw binary instead.

1. Wherever you want to store this repo, clone this repo to your computer and install and link the library.

   git clone https://github.com/veritone/developer-cli-tool
   cd developer-cli-tool
   yarn install
   yarn link # This allows you to use the `veritone-developer` command on the command line
   

2. In the directory for your application, create a manifest.yaml that looks like test/manifest.yaml.

3. Retrieve an aiWARE token somehow (probably by logging in and pulling it out of your cookies)

4. Run this to create your application in the new environment (only VERI_TOKEN is required):

   VERI_TOKEN="<your token>" \
   VERI_GRAPHQL_URL="<the graphql endpoint for your environment>" \
   VERI_MANIFEST="<the manifest location>" \
   veritone-developer deploy
   

Commands

For now, there's just one command: deploy. And running veritone-developer or veritone-developer deploy does the same thing for the moment.

Environment Variables

In the future, these will be turned into command line arguments

Token	Required	Default	Purpose
VERI_TOKEN	Yes		The token to use when making calls to aiWARE's API
VERI_GRAPHQL_URL	No	https://api.aws-dev.veritone.com/v3/graphql	The aiWARE API endpoint
VERI_MANIFEST	No	manifest.yaml	The manifest file to process

Testing

Running the following should successfully register a full-featured application.

⚠️ WARNING: This DOES make changes in your account. Use with caution!

cd test
VERI_TOKEN="<your token>" ../bin/veritone-developer

Running it again should ideally make no changes.

Roadmap

Inspiration

Our sketches for the manifest can be seen in our CodeSandbox. See @SteveShaffer for access if you don't have it.

Following Twilio's guide on how to build a node CLI. But using yargs instead of arg.

Known Assumptions and Limitations

• The manifest structure is not validated and is assumed to be "well-formed"
• Does NOT present a plan or ask for consent before making API calls.
• Does NOT handle engines
• Does NOT handle by-reference schemas. Assumes the schema is "owned" by this project and defined completely inline.
• Does NOT de-link schemas if a schema is already linked to the application but it's not in the manifest or was removed from the manifest.
• Does NOT handle auto-generation of IDs for schemas. Schemas are required to have a GUID created by the author.
• Does NOT support breaking changes to schemas. If you manually publish a new breaking version through Developer App and then update the majorVersion number in the manifest, it should be able to push updates to the new major version though.

TODO

• Figure out proper name (veritone-developer vs. veri vs. aiware vs. aiware-developer-cli or something like that)
• Add option for dry run (i.e. don't perform any GraphQL mutations, just log what WOULD HAVE been performed)
• See TODOs inline in source code
• Get more formal automated tests in place
• Allow manifest to be either yaml or json
• Find a better default name of the manifest like .aiware.json
• Make into a real CLI
• Tell the user what's going to happen and gather consent (like tf plan)
• Have a mode where, instead of interactively calling the API, bundles up an immutable install "package" that can then be uploaded to any environment.
• TypeScript
• Incorporate interactive login. Ideally, only ask the user for their username and password the first time. And only use it to coin an API key that you store in some config file for use in the future. But there will probably be blockers to that at our API level.
• Extract this into its own tool for application developers
• Default to prod env?
• Switch all require to import (per esm)
• Convert all environment variables to command line arguments

Desired Dependencies

We'd like to be intentional about the dependencies we bring in. There's always lots of technologies to pick from on these projects.

Here's what we'd like to explore using for various things. If there's a better alternative, we might change our minds, but here's where our minds are at right now.

• yargs for parsing CLI args
• pkg for bundling a binary
• listr for progress meters
• chalk for colored STDOUT
• inquirer for interactive inputs
• Integrate into Veritone Jenkins environment for CI/CD and publishing to npm

Planned Deploy Targets

• Should have a command line synonym shorter than veritone-developer

• Should be able to run via npx

  npx veritone-developer deploy
  

• Should be able to run as a standalone binary

  curl https://scripts.veritone.com/veritone-developer | bash