search

nuance-communications / mix-cli

A command line tool for the Mix V4 authoring API
Apache License 2.0
14 stars 2 forks source link

readme

mix-cli

mix-cli is a command line tool that provides access to the Mix V4 API.

oclif Version Downloads/week License

Installing mix-cli

To install mix-cli, simply type:

npm install -g @nuance-mix/mix-cli

mix-cli requires Node.js version 14 or more recent.

Migrating to version 2 of mix-cli

mix-cli introduces a few breaking changes. See the migration documentation as those changes could disrupt automated workflows.

Configuring mix-cli

In order to configure mix-cli, you need service credentials that give you access to the Mix V4 API. These credentials can be found under your user profile in the Mix.dashboard Tool.

To configure mix-cli, simply type:

mix init

The init command asks for a few pieces of configuration data. Defaults are provided for the Mix production system in the US geography. Service credentials are requested last.

The mix-cli configuration is stored under ~/.config/@nuance-mix/mix-cli/ on Unix and macOS systems and under %LOCALAPPDATA%\@nuance-mix\mix-cli\ on Windows systems. The configuration is stored in a file named "config.json" that is accessible only to the user who executed the init command.

Using mix-cli with multiple Mix systems

When you run the init command, mix-cli detects the name of the Mix system by parsing the hostname provided for the Mix API server. It suggests this name as an answer when it prompts you for the "Mix system name".

Say you have initially run the init command to configure mix-cli for the "us" Mix system. You can run the init command a second time to configure the "eu" system using the relevant hostnames. mix-cli stores the configuration of both systems.

You can then type mix auth --system us to switch to and authenticate with the "us" Mix system. Similarly, typing mix auth --system eu does the same but with the "eu" Mix system. mix-cli remembers the last Mix system it authenticated with so using mix auth with the system flag is only needed when switching to a different Mix system.

Finally, all mix-cli commands complete their human-readable output by reporting which Mix system the command was executed against.

Overriding the central configuration

Configuration elements can be overriden by using the following environment variables:

It is also possible to configure these environment variables using a .env file. mix-cli looks for the .env file in the current working directory when it starts up.

Configuration values are read in the following order, where the last value assignment wins:

Experimental support for Device Code authentication flow

Experimental support for the Device Code authorization flow has been added to mix-cli. You can configure a Mix system for this authorization flow by answering "device" to the "Authentication flow?" question that now comes first when running the init command.

Retrieving the access token

With the relevant configuration in place, you first need to retrieve an access token before using any of the other cli commands. Simply type:

mix auth

mix-cli stores the access token in a file named "access-token" in the same directory it stores its central configuration. Like the configuration file, the access token file is only accessible to the user who executed the auth command.

Access tokens expire after 15 minutes. mix-cli takes care of refreshing the access token.

Choosing a command output format

Some commands offer up to 4 different types of output format.

Select the JSON or YAML output format to get the actual data returned the remote server. Note that some commands can only display a subset of the data available when "csv" output is chosen.

Sorting and filtering

Some commands offer the ability to filter and/or sort the output data. The filtering and sorting are done by the remote server when the functionality is supported by the endpoint. Otherwise, filtering and sorting are performed locally in mix-cli.

Autocompleting commands

Thanks to the oclif/plugin-autocomplete plugin, commands can be autocompleted when mix-cli is used with the bash or zsh shell. Type mix autocomplete bash or mix autocomplete zsh, follow the instructions and then launch a new shell. You will then get autocompletion of mix-cli commands by pressing the tab key.

Type mix autocomplete --refresh-cache to rebuild the autocompletion cache, which is useful when upgrading to a version of mix-cli that introduces new commands.

Finally, type mix autocomplete --help to get help on using the autocomplete setup command.

Providing defaults for often-used command arguments

Many commands require a project ID, organization ID and/or locale. mix-cli will default to the value contained in the following environment variables, if they exist, or if they are provided in the .env file:

Using the mix-cli client code

The client code used by mix-cli to communicate with the Mix V4 API can be reused to write other applications that make use of the Mix V4 API. You can view the API client documentation and there is a short example in the examples directory. Please consult the Mix V4 API documentation for additional information.

Learning more about Mix

Please visit the Mix product page and Mix documentation site to learn more about Mix.

Contributing

See our Contribution Guidelines.

Commands

mix autocomplete [SHELL]

display autocomplete installation instructions

USAGE
  $ mix autocomplete [SHELL] [-r]

ARGUMENTS
  SHELL  shell type

FLAGS
  -r, --refresh-cache  Refresh cache (ignores displaying instructions)

DESCRIPTION
  display autocomplete installation instructions

EXAMPLES
  $ mix autocomplete

  $ mix autocomplete bash

  $ mix autocomplete zsh

  $ mix autocomplete --refresh-cache

See code: @oclif/plugin-autocomplete

mix help [COMMANDS]

Display help for mix.

USAGE
  $ mix help [COMMANDS] [-n]

ARGUMENTS
  COMMANDS  Command to show help for.

FLAGS
  -n, --nested-commands  Include all nested commands in the output.

DESCRIPTION
  Display help for mix.

See code: @oclif/plugin-help