The DXP Story CLI uses Node 14+ and is installed using NPM.
npm i @viewdo/dxp-story-cli
Once installed, add the following scripts to the package.json:
```json
{
"scripts": {
"storyctl": "storyctl",
"build": "storyctl build -a",
"pretest": "storyctl build -a",
"test": "storyctl check -a",
"prevalidate": "storyctl build -a",
"validate": "storyctl validate -a",
"prepush": "storyctl build -a",
"push": "storyctl push -a",
"preview": "storyctl preview"
}
```
This allows you to use 'yarn' to call the local package.
yarn storyctl XXX
yarn build
yarn push
Alternatively, you can install the CLI globally, but this will force all repositories to be updated to 2.0 before it can work on older stories.
The first thing the tool needs to do is initialize a workspace on the filesystem.
To manage a single, existing story:
storyctl init <story-key>
or, to manage an existing organization
storyctl init -k <org-key>
or, if this is a new story and org:
storyctl init
Like NPM, the init function will prompt the developer about basic settings and hold them in files at the root of the workspace and user directory:
- ./dxp-config.yml
- ./.env
The Story CLI requires a dxp-config.yml file at the root of the repository. This file defines how the assets are named in the repository and what stories and orgs are synchronized.
kind: DXP
apiVersion: api.view.do/v4/admin
cdn:
enabled: true
organizations:
- key: viewdo-napp
name: "NAPP Demos"
stories:
- key: napp-sample
name: "Sample Story"
organization_key: viewdo-nappThe .env file, holds environment variables. The CLI tool expects a 'NAMESPACE' environment variable to tell it which platform instance to use.
NAMESPACE=develop
#GOOGLE_APPLICATION_CREDENTIALS=~./gcp/service-account.json
If you plan to push directly and the repository has CDN uploads enabled, you will need to provide your service-account file location in the file as depicted above (un-commented, of course).
This tool can only be used by authorized users, you must login before accessing the API. This means we need to authenticate the user or server for a token with permission to update the assets.
This adds a 12-hour token to the user directory for the given environment for use during commands.
Usage:
storyctl [options] [command]
Options:
-V, --version output the version number
-h, --help output usage information
Set up the required configuration files for using the CLI within a folder.
Usage:
storyctl init|i [options]
Options:
-a, --auto For use when created during automation. [No auth]
-o, --overwrite Overwrite existing files.
-g, --git This flag will setup git as well. Use this the first time!
-h, --help display help for command
The namespace determines which DXP environment endpoints to use.
- local
- develop
- stage
- main *
- main-archer *
* 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, develop and stage, but production MUST go through a build-deployment in BitBucket. 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.
Authenticates to the output using email verification code
Usage:
storyctl login|auth [options] [email] [code]
Options:
-f, --force Force new authentication
-i, --client_id <client_id> Auth0 client id
-s, --client_secret <secret> Auth0 client secret
-n, --namespace <namespace> Override the namespace
-h, --help display help for command
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.
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
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:
storyctl pull|p [options] [keys...]
Options:
-k, --key <key> Pull all stories for a given organization
-a, --all Pull all stories without prompting
-f, --force Overwrite story build files
-c, --client_id <client_id> Auth0 client id
-s, --client_secret <secret> Auth0 client secret
-n, --namespace <namespace> Override the namespace
-h, --help display help for command
To pull a story and clone it as a new story, use this command.
Usage:
storyctl pull-as|pa [options] <story_key> <as_key> <org_key>
Options:
-c, --client_id <client_id> Auth0 client id
-s, --client_secret <secret> Auth0 client secret
-n, --namespace <namespace> Override the namespace
-h, --help display help for command
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:
storyctl check|c [options] [keys...]
Options:
-a, --all Checks all stories without prompting
-c, --client_id <client_id> Auth0 client id
-s, --client_secret <secret> Auth0 client secret
-n, --namespace <namespace> Override the namespace
-h, --help display help for command
The validate command will validate the contents of the assets on the platform to ensure all tokens are valid.
Usage:
storyctl validate|v [options] [keys...]
Options:
-k, --key <key> Story key to validate
-a, --all Validates all stories without prompting
-c, --client_id <client_id> Auth0 client id
-s, --client_secret <secret> Auth0 client secret
-n, --namespace <namespace> Override the namespace
-h, --help display help for command
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:
storyctl push|u [options] [keys...]
Options:
-k, --key <key> Push all stories for a given organization
-a, --all Push all stories without prompting
-S, --skip-cdn Skip CDN assets (default: false)
-b, --build_id The commit/sync identifier for this push (defaults to BUILD_ID)
-B, --build Build stories before pushing
-c, --client_id <client_id> Auth0 client id
-s, --client_secret <secret> Auth0 client secret
-n, --namespace <namespace> Override the namespace
-h, --help display help for command
Performs a webpack build on configured stories using the story's webpack.config.js.
Usage:
storyctl build|b [options] [keys...]
Options:
-v, --verbose Verbose logging
-k, --key <key> Build only this story key
-a, --all Build all stories without prompting
-h, --help display help for command
Previews a given story using the story's webpack.config.dev.js configuration, with a mocked XAPI API.
Usage:
storyctl preview|u [options] [key] [episode]
Options: -p, --port Overrides the port for previewing -f, --force Overwrites the preview config for all specified stories -h, --help display help for command
The update command was introduced in v.2. This command updates old 1.x repositories to the new format, with support for the new self-hosted format for stories (these use custom HTML, rather than the StoryPlayer's rigid harness)
Usage:
storyctl update [options] [keys...]
Options:
-r, --root Update files in root and .dxp folders (webpack,gitignore, pipeline, etc)
-d, --dxp Update files in .dxp folder (templates and schemas)
-s, --stories Update story build files for each story.
-o, --organizations Update organization folders for each org.
-p, --packages Update dependencies in package.json
-a, --all Update everything
-h, --help display help for command
Lists available organization secrets.
Usage:
storyctl secret-list [options]
Options:
-o, --org [org] Specify an org for multi-org repos
-h, --help display help for command
Set the value of an organization secret. A new secret version will be returned.
Usage:
storyctl secret-set [options] <seretKey>
Options:
-o, --org [org] Specify an org for multi-org repos
-h, --help display help for command