ICM Commands and Options

The first table that follows lists the commands that can be executed on the ICM command line. Each of the commands is covered in detail in the “Using ICM” chapter.

The second table lists the options that can be used with commands. Command-line options serve two purposes, as follows:

To provide required or optional arguments to commands. For example, to list the run state of only the InterSystems IRIS containers in your deployment, you could use this command:
```
icm ps -container iris
```
To execute a command to open a shell inside the container deployed on node ANDY-DM-TEST, you could use this command:
```
icm exec -command bash -machine ANDY-DM-TEST -interactive
```
To override a field’s default or configuration file value, in one of two ways:
- The -image, –namespace, and -iscpassword options can be used to override the values of the DockerImage, Namespace, and ISCPassword fields, respectively, in any command, including icm provision.
- Following the provisioning phase, the -overrides option can be used to override the values of one or more fields for the current command only. For example, assume your defaults file includes the following fields:
```
"DockerUsername": "prodriguez",
"DockerPassword": "xxxxxxx",
"DockerRegistry": "https://containers.intersystems.com",
"DockerImage": "containers.intersystems.com/intersystems/iris:2022.1.0.223.0",
```
  When executing the icm provision command you could override the Dockermage field using the -image option, but not to use an image from a different registry, because you could not override the registry location and credentials. In the icm upgrade command, however, you could specify an image from a different registry by using the -overrides option to override all three fields, for example:
```
icm upgrade -overrides '{"DockerUsername":"mwyszynska","DockerPassword":"xxxxxx",
  "DockerRegistry":"docker.io"}' -image docker.io/acme/iris:latest-em
```
  Note:
  
  When -overrides is used with the icm run, icm install, or icm upgrade commands to specify field values that are intended to persist, these should be updated in the instances.json file so they won't be reverted during a subsequent reprovisioning operation. Following the icm upgrade command above, for example, the DockerImage, DockerRegistry, DockerUsername, and DockerPassword fields should be updated in the instances file. (The -image, –namespace, and -iscpassword options automatically do this.)

Both tables include links to relevant text.

Note:

The command table does not list every option that can be used with each command, and the option table does not list every command that can include each option.

ICM Commands

Command	Description	Important Options
provision	Provisions host nodes	n/a
inventory	Lists provisioned host nodes	-machine, -role, -json, -options
unprovision	Destroys host nodes	-stateDir, -cleanup, -force
merge	Merges infrastructure provisioned in separate regions or provider platforms into a new definitions file for multiregion or multiprovider deployment	-options, -localPath
ssh	Executes an operating system command on one or more host nodes	-command, -machine, -role
scp	Copies a local file to one or more host nodes	-localPath, -remotePath, -machine, -role
run	Deploys a container on host nodes	-image, -container, -namespace, -options, -iscPassword, -command, -machine, -role, –override
ps	Displays run states of containers deployed on host nodes	-container, -json
stop	Stops containers on one or more host nodes	-container, -machine, -role
start	Starts containers on one or more host nodes	-container, -machine, -role
pull	Downloads an image to one or more host nodes	-image, -container, -machine, -role
rm	Deletes containers from one or more host nodes	-container, -machine, -role
upgrade	Replaces containers on one or more host nodes	-image, -container, -machine, -role, –override
exec	Executes an operating system command in one or more containers	-container, -command, -interactive, -options, -machine, -role
session	Opens an interactive session for an InterSystems IRIS instance in a container or executes an InterSystems IRIS ObjectScriptScript snippet on one or more instances	-namespace, -command, -interactive, -options, -machine, -role
cp	Copies a local file to one or more containers	-localPath, -remotePath, -machine, -role
sql	Executes a SQL statement on the InterSystems IRIS instance	-namespace, -command, -machine, -role
install	Installs InterSystems IRIS instances from a kit in containerless mode	-machine, -role, –override
uninstall	Uninstalls InterSystems IRIS instances installed from a kit in containerless mode	-machine, -role
docker	Executes a Docker command on one or more host nodes	-container, -machine, -role

ICM Command-Line Options

Option	Description	Default	Described in
-help	Display command usage information and ICM version		---
-version	Display ICM version		---
-verbose	Show execution detail	false	(can be used with any command)
-force	Don't confirm before unprovisioning	false	Unprovision the Infrastructure
-cleanUp	Delete state directory after unprovisioning	false	Unprovision the Infrastructure
-machine regexp	Machine name pattern match used to specify the node or nodes for which the command is run	(all)	icm inventory, icm ssh, icm run, icm exec, icm session
-role role	Role of the InterSystems IRIS instance or instances for which a command is run, for example DATA or AM	(all)	icm inventory, icm ssh, icm run, icm exec, icm session
-namespace namespace	Namespace to create on deployed InterSystems IRIS instances and set as default execution namespace for the session and sql commands	IRISCLUSTER	The Definitions File, icm run, icm session, icm sql
-image image	Docker image to deploy; must include repository name	DockerImage value in definitions file	icm run, icm upgrade
-override '{"field":"value",...}	Field value(s) to override for this command.	none	ICM Commands and Options
-options options	Docker options to include in the command	none	icm inventory, icm run, icm exec, icm session, Deploying Across Multiple Regions or Providers, Using ICM with Custom and Third-Party Containers
-container name	Name of the container	icm ps command: (all) other commands: iris	icm run, icm ps
-command cmd	Command or query to execute	none	icm ssh, icm run, icm exec, icm session, icm sql
-interactive	Redirect input/output to console for the exec and ssh commands	false	icm ssh, icm exec, icm sql ,
-localPath path	File or directory path on a node’s local file system (icm cp) or within the ICM container (icm scp)	none	icm cp, icm scp, Containerless Deployment, Remote Script Invocation
-remotePath path	File or directory path within a container (icm cp) or on a node’s local file system (icm scp)	/home/SSHUser (value of SSHUser field)	icm cp, icm scp, Containerless Deployment, Remote Script Invocation
-iscPassword password	Password for deployed InterSystems IRIS instances	iscPassword value in configuration file	icm run
-json	Enable JSON response mode	false	Using JSON Mode

Important:

Use of the -verbose option, which is intended for debugging purposes only, may expose the value of iscPassword and other sensitive information, such as DockerPassword. When you use this option, you must either use the -force option as well or confirm that you want to use verbose mode before continuing.

ICM Configuration Parameters