iVX CLI

Installation

The iVX CLI uses Node 8+ and is installed using NPM. It works best when installed globally.

$ npm i -g ivx-deploy

Usage & Global Options

$ ivx help

Usage: index [options] [command] Options:

-V, --version            Output the version number
-h, --help               Output usage information

Commands:

init|i [options]         Set up the environment variables for a working directory
login|l [options]        Authenticates to the directory using email verification code
scaffold|s [options]     Scaffolds out the root directory for story assets
add|a [options]          Adds a story to this directory for management
pull|p [options]         Pulls down all the associated assets for a given story
status [options]         Checks the status by comparing assets for a given story
push|u [options]         Pushes all the associated assets to a given story

Initialization

The first thing the tool needs to do is initialize a workspace on the filesystem. Like NPM, the init function will prompt the developer about basic settings and hold them in two small files at the root of the workspace.

$ ivx init|i [options]

Set up the environment variables for a working directory

Options:

-D, --debug              Debug output.
-e, --environment [env]  Environment to use against [local|dev|stage] (default: dev)
-p, --path <path>        Directory for this project (if not the root where the command is execute from)
-E, --email <email>      Email address of the current user
-d, --directory <dir>    Which directory holds stories (default: null)
-h, --help               output usage information

Environments

The environment determines which iVX environment endpoints will be used to upload the asset.

• local
• dev
• stage
• production *

* Production (prod) is only available in the non-interactive authentication mode. The tool will allow you to push straight from the workstation to the platform in local, dev and stage, but production MUST go through a build-deployment from TeamCity. This way, we can be nimble in staging environments and once the story looks good, a check in (after pull-request) is needed to get the assets up to the platform.

Currently, the assets can still be built and uploaded through the UI, but we need to update permissions so that we can lock assets down to deployment-mode only.

Authentication

We need to make sure this tool can only be used by authorized StoryAdmins (w/AssetManagement grant in production). This means we need to authenticate the user or server for a token with permission to update the assets. We should use our Auth0 to authenticate this tool in one of two modes, interactive or application.

Mode: Interactive

By default, this tool requires user credentials with permission to update the story assets. credentials and will prompt the user into the login-flow below, using the passwordless-email option in Auth0. No passwords will ever be transmitted or collected. However, the tokens should be saved in a location that allows the token to be reused if the command is run again.

$ ivx login|l [options] [email]

Authenticates to the directory using email verification code

Options:

-D, --debug              Debug output.
-e, --environment [env]  Environment to use against [local|dev|stage] (default: dev)
-p, --path <path>        Directory for this project (if not the root where the command is execute from)
-E, --email <email>      Your email address (for authentication)
-c, --code <code>        Email verification code (default: null)
-t, --token <token>      An existing token to write to the directory
-f, --force              Force new authentication
-h, --help               Output usage information

Mode: Application

If we initialize Auth0 as Machine-to-Machine application and provide environment variables for the ClientID and ClientSecret for the client, this tool can authenticate as itself from the build-server with the special permissions needed to push assets to production.

Environment Variables:

• AUTH0_CLIENT_ID
• AUTH0_CLIENT_SECRET
• AUTH0_DOMAIN

Pull : Download Existing Story Assets

The quickest way to get set up on an existing story is to pull all assets for a story using this command. It assumes the convention configuration mode and downloads the assets according to the file structure above.

$ ivx pull|p [options] [keys...]

Pull down all the associated assets for a given story

Options:

-D, --debug              Debug output.
-e, --environment [env]  Environment to use against [local|dev|stage] (default: dev)
-p, --path <path>        Directory for this project (if not the root where the command is execute from)
-k, --key <key>          Story key to pull assets from
-x, --explicit           Write all file locations in the ivx-config.json file.
-a, --all                Pull all stories without prompting
-h, --help               output usage information

Scaffold : New Story Assets

If this is a brand new repository for a new story. You can scaffold the folder structure along with empty files to get you started.

$ ivx scaffold|s [options] [keys...]

Scaffolds out the root directory for story assets

Options:

-D, --debug              Debug output.
-e, --environment [env]  Environment to use against [local|dev|stage] (default: dev)
-p, --path <path>        Directory for this project (if not the root where the command is execute from)
-k, --key <key>          Scaffold using this story key
-x, --explicit           Write all file locations in the ivx-config.json file.
-h, --help               Output usage information

Status : Compare Story Assets on disc to the Story on the iVX Platform

The status command will compare the contents of the assets on the platform with the contents of the files on disc. This gives the user a quick way of seeing the impact a push might have.

$ ivx check|c [options] [keys...]

Checks to see what files are different on disc from the platform

Options:

-D, --debug              Debug output.
-e, --environment [env]  Environment to use against [local|dev|stage] (default: dev)
-p, --path <path>        Directory for this project (if not the root where the command is execute from)
-k, --key <key>          Story key to push (default: null)
-a, --all                Push all stories without prompting

Push : Upload Story Assets to the Story on the iVX Platform

The deployment command executes differently depending on the authenticating mode. For interactive clients, if not yet logged in, you are prompted first. Then the plan command is executed first with a prompt to continue. Then the validate command is executed. If no errors exist, the user is prompted to push.

$ ivx push|u [options] [keys...]

Pushes all the associated assets to a given story

Options:

-D, --debug              Debug output.
-e, --environment [env]  Environment to use against [local|dev|stage] (default: dev)
-p, --path <path>        Directory for this project (if not the root where the command is execute from)
-k, --key <key>          Story key to push (default: null)
-a, --all                Push all stories without prompting

Configuration

Folder & File Conventions

This application works best when the folder and file conventions are used. This method reduces the amount of configuration necessary for deployments. The following illustrates the convention for a given story.

Story Folder:

[root]
ivx-config.json
📁<story-key>
  /story.json
  /story.js
  /story.css
  /story-intro.html
  📁html-templates
    /<file-key>.html
  📁text-templates
    /<file-key>.txt|json|js|css|less|csv|xml
  📁email-templates
    /<email-key>.cshtml
  📁episodes
    📁<episode-key>
      /story.json
      /story.css

Simple Configuration : /ivx-config.json

{
  "directory": "./", // optional
  "stories": {      // not optional
    "testing": {
      "name": "Sample Story"
    }
  }
}

Explicit Configuration : /ivx-config.json

{
  "directory": "/src/stories",
  "stories": {
      "testing": {
        "name": "Sample Story",
        "intro_html_file": "/testing/story-intro.html",
        "js_file": "/testing/story.json",
        "json_file": "/testing/story.js",
        "css_file": "/testing/story.css",
        "episodes": {
            "test-episode": {
                "json_file": "/testing/episodes/test-episode/story.json",
                "css_file": "/testing/episodes/test-episode/story.css"
            }
        },
        "email_templates": {
            "example": "/testing/email-templates/example.cshtml"
        },
        "html_templates": {
            "example": "/testing/html-templates/example.html"
        },
        "text_templates": {
            "example": "/testing/text-templates/example.js"
        }
      }
    }
}

---

FUTURE

Validate : Check files against story configuration

This is another important part of all interactive deployments. It gives the user a chance to validate all file contents within the configuration, whether it was by convention or declaration. This command shows server validation for each file, including token errors.

$ ivx validate|v [options] [keys...]

Sync : Synchronize All Assets

With push, all assets need to exist on the platform. You cannot add or remove assets when deploying. This command will use the local-configuration as the source of truth, creating any assets missing on the platform as well as removing any not found locally on disc.

$ ivx sync|s [options] [keys...]