Migration from Legacy CLI

Overview

Version 1.24.9 introduces compatibility-breaking changes to the CodeMRI command-line interface (CLI). These changes bring a number of benefits over the legacy (pre-1.24.9) CLI:

• Grouping of commands in a logically-consistent way.

• Support of multiple output formats: Human Readable, CSV, TSV, JSON.

• Simplified single-command syntax.

• More consistent handling of selection, ability to provide vault path and selection set via environment variables.

• Improved documentation.

Changes

Invocation

General

• The vault path can be provided either by the --vault option or CMRI_VAULT environment variable. If not provided, cmri will assume that the current directory is the vault.

• cmri no longer creates a vault on the first run. In order to create a vault, run cmri vault create.

• cmri no longer opens to the interactive console by default. See Interactive Shell for more information.

• Scripts no longer open the interactive shell when they complete. To open the interactive shell after a script, add shell at the end of the script.

• The help command has been removed, instead use <command> --help to display command help. Run cmri --help for a full command listing, as well as information about general invocation. Typing --help<return> by itself on the interactive shell is equivalent to running cmri --help.

Single Command

The default mode of operation for the new CLI is running a single command. To launch the CodeMRI CLI for a single command use the syntax:

cmri <command> [arguments...]

For example, to run the project add command directly from the shell, run:

cmri project add --name "MyProject" --vault /path/to/vault

CodeMRI can also read the vault path from an environment variable, eliminating the need for the --vault option:

Linux:

export CMRI_VAULT="/path/to/vault"
cmri project add --name "MyProject"

Windows:

SET CMRI_VAULT=C:\path\to\vault
cmri project add --name "MyProject"

Interactive Shell

To access the interactive shell, run cmri shell. Supply the vault path using the --vault option or CMRI_VAULT environment variable:

cmri shell --vault "/path/to/vault"

or:

export CMRI_VAULT="/path/to/vault"
cmri shell

using environment variable on Windows:

SET CMRI_VAULT=C:\path\to\vault
cmri shell

cmri will assume that the vault is in the current directory if it is not provided.

When invoking commands on the interactive shell, do not include the cmri prefix. For example, cmri system add becomes system add.

The shell must be pointed to an existing vault. If no vault exists in the provided location, create one first using the cmri vault create command.

Batch Scripts

To run batch scripts, use cmri batch run. Supply the vault path using the --vault option or CMRI_VAULT environment variable:

cmri batch run --vault "/path/to/vault" "/path/to/script"

or:

export CMRI_VAULT="/path/to/vault"
cmri batch run

using environment variable on Windows:

SET CMRI_VAULT=C:\path\to\vault
cmri batch run "C:\path\to\script"

Batch scripts consist of a series of commands, without the cmri prefix. CodeMRI now supports comments in batch scripts, any line whose first non-whitespace character is # will be treated as a comment.

Commands

Individual commands are relocated. Options for individual commands have changed. For more information, see command-specific documentation. Here is mapping of existing commands to new commands:

Selection

• project/system select have changed to a single select command.

• All commands can accept a command-scoped selection set via the --selection option. See CodeMRI CLI Reference for details.

Account and License Management

• login is now account login

• logout is now account logout

• license id is now machine-id generate

Vault Administration

• To create a vault, use vault create.

• list is now vault list.

• config is now vault config.

  • To get the value of a config property, use vault config get.

  • To set the value of a config property, use vault config set.

  • To list available config properties, use vault config list.

• project config is now project config.

  • To get the value of a config property, use project config get.

  • To set the value of a config property, use project config set.

  • To list available config properties, use project config list.

• system config is now system config.

  • To get the value of a config property, use system config get.

  • To set the value of a config property, use system config set.

  • To list available config properties, use system config list.

• Interactive prompts removed from project add.

• Interactive prompts removed from system add.

• project rename now renames a single selected project.

• system rename now renames a single selected system.

• project remove and system remove now require a --force option to remove more than one project or system at a time.

Job Processing

• Typing the job name alone on the console will no longer run jobs. Use job run instead.

• run is now job run.

• run with no-args no longer produces a list of jobs. Use job list to list jobs.

• help <job-name> is now job describe.

• clean is now job clean.

• check is now job check-complete.

Data Entry & Validation

• system components is now system component. Sub-commands have different options, see sub-commands in component for details about new syntax.

• Commands related to component relationships are now under system component-relationship.

• system components verify is now system architecture verify.

• system files is now system file list.

Query Interface

The file output options of the system query command have changed to use the standard output options available to all commands. Where previously to write a CSV, you would use:

system query component-relationships --out "/path/to/test.csv"

with the new version, the output format must be specified:

system query component-relationships --output-format csv --out "/path/to/test.csv"

The query interface now supports json as an output format. See the “Output Formats” section in CodeMRI CLI Reference for a complete list of supported formats. See system query for general information about the system query command.

Legacy Mode

To ensure a smooth transition to the new command-line interface, you can access the legacy CLI by setting the environment variable CMRI_LEGACY_CLI to 1.

On Linux via BASH:

export CMRI_LEGACY_CLI=1

On Windows via cmd:

SET CMRI_LEGACY_MODE 1

On Windows via PowerShell:

$env:CMRI_LEGACY_CLI=1

With legacy mode enabled, CodeMRI will display the following deprecation message: