# DXP Story CLI ## Installation The DXP Story CLI uses *Node 8+* and is installed using NPM. It works best when installed globally. $ npm i -g @viewdo/dxp-story-cli ## Getting Started The first thing the tool needs to do is initialize a workspace on the filesystem. To manage a single, existing story: $ dxp-story init -e or, to manage an existing organization $ dxp-story init -k -e or, if this is a new story and org: $ dxp-story init -e Like NPM, the init function will prompt the developer about basic settings and hold them in three small files at the root of the workspace: * dxp-config.json * .auth * .env #### ./dxp-config.json The Story CLI requires a **dxp-config.json** file to exist. This file defines how the assets are named in the repository. { "kind": "Configuration", "apiVersion": "api.view.do/v1/attachments", "output": ".", "organizations": { "dotedu-tech": { "name": "view.DO (Tech-Testing)", "sync_file": "./organizations/dotedu-tech/organization-config.json", ... } }, "stories": { "tech-sample": { "name": "Sample Story", "organization_key": "dotedu-tech", "sync_file": "./stories/tech-sample/story-config.json", "episodes": { "alternative": { "name": "Alternative" ... } } ... } } } #### ./.auth The **.auth** file holds your token and email address. This file should NEVER be added to Git and should only live in your own file-system. { "kind": "Credentials", "apiVersion": "auth.view.do/v1", "email": "@view.do", "token": "..." } #### ./.env The **.env** file, holds environment variables. The CLI tool expects a 'NAMESPACE' environment variable to tell it which platform instance to use. NAMESPACE=develop ### Authenticate 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. $ dxp-story login ## Usage & Global Options Usage: $ dxp-story [options] [command] Options: -V, --version output the version number -h, --help output usage information ## Commands: |command |Description | |---|---| |[init](##INIT) | Set up the namespace variables for a working output | |[login](##LOGIN) | Authenticate to the output using email verification code | |[scaffold](##SCAFFOLD) | Create all the asset files and folders for brand new story | |[pull](##PULL) | Pull down all the assets for a given set of organization keys | |[push](##PUSH) | Pushes all the associated assets to a given story | |[check](##CHECK) | Checks to see what files are different on disc from the platform | |[validate](##VALIDATE) | Validate tokens in local files using the configured story | ## INIT Set up the required configuration files for using the CLI within a folder. Usage: $ dxp-story init|i [options] [keys...] Options: -v, --verbose Verbose logging. -n, --namespace Namespace to use against [local|dev|stage] -e, --email Email address of the current user -o, --output Folder for bundled story files, used to sync with the platform -h, --help output usage information ### Namespaces The namespace determines which DXP environment endpoints to use. * local * develop * \ * default * \* Production (default) 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 namespaces and once the story looks good, a check in (after pull-request) is needed to get the assets up to the platform. ## LOGIN Usage: $ login|a [options] [email] [keys...] Options: -v, --verbose Verbose logging. -n, --namespace Namespace to use against [local|dev|stage] -E, --email Your email address (for authentication) -t, --token An existing token to write to the output -f, --force Force new authentication -h, --help output usage information ### Mode: Interactive By default, this tool requires user credentials with permission to update the story assets. Login 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. $ dxp-story login ### 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. *Namespace Variables:* * AUTH0_CLIENT_ID * AUTH0_CLIENT_SECRET * NAMESPACE=default ## PULL 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. Pull down all the associated assets for a given set of story keys Usage: $ pull|p [options] [keys...] Options: -v, --verbose Verbose logging. -n, --namespace Namespace to use against [local|dev|stage] -k, --key Org key to pull all assets for its stories -x, --explicit In this mode, all files are declared in the dxp-config.json file. This mode is meant for shared-asset repositories -a, --all Pull all stories without prompting -o, --output Which output holds the assets -i, --client_id Auth0 Client ID -s, --client_secret Auth0 Client Secret -A, --audience Auth0 audience -c, --config_only Pull only the org & story config. -t, --token Auth token -h, --help output usage information ## SCAFFOLD 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. Creates all the asset files and folders for brand new story Usage: $ scaffold|s [options] [keys...] Options: -v, --verbose Verbose logging. -k, --key Scaffold using this story key -x, --explicit In this mode, all files are declared in the dxp-config.json file. This mode is meant for shared-asset repositories -o, --output Which output holds stories -h, --help output usage information ## CHECK Compare Story Assets on disc to the Story on the DXP Platform The check 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. Usage: $ check|c [options] [keys...] Options: -v, --verbose Verbose logging. -n, --namespace Namespace to use against [local|dev|stage] -k, --key Story key to check -a, --all Checks all stories without prompting -o, --output Which output holds stories -i, --client_id Auth0 Client ID -s, --client_secret Auth0 Client Secret -A, --audience Auth0 audience -t, --token Auth token -h, --help output usage information ## VALIDATE The validate command will validate the contents of the assets on the platform to ensure all tokens are valid. Usage: $ validate|v [options] [keys...] Options: -v, --verbose Verbose logging. -n, --namespace Namespace to use against [local|dev|stage] -k, --key Story key to validate -a, --all Validates all stories without prompting -o, --output Which output holds stories -i, --client_id Auth0 Client ID -s, --client_secret Auth0 Client Secret -A, --audience Auth0 audience -t, --token Auth token -h, --help output usage information ## PUSH 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. Usage: $ push|u [options] [keys...] Options: -v, --verbose Verbose logging. -n, --namespace Namespace to use against [local|dev|stage] -k, --key Org key to push all its stories -a, --all Push all stories without prompting -o, --output Which output holds stories -i, --client_id Auth0 Client ID -s, --client_secret Auth0 Client Secret -A, --audience Auth0 audience -t, --token Auth token -h, --help output usage information