DSim Cloud CLI execute command advanced topics

Introduction

Terminal windows are an advanced tool and some of their complexity, although useful, can appear to behave strangely for the unfamiliar. Certain switches (anything preceded with a -) and wildcards (such as *, $, ~) are read by terminal windows and treated in special ways. This behavior is called shell expansion and is worth becoming familiar with, certainly at least to the basic level of not triggering it unintentionally

However, know that when passing commands from your local terminal to remote execution, you have the flexibility and control to tell either side (local or remote) to interpret those characters to do something special.

For Windows users, we suggest using PowerShell as your terminal, and all examples will assume that is the shell you are using. You can find instructions on how to install PowerShell for Windows here.

Execution Methods

There are four main methods you can use to execute DSim Cloud CLI commands, the reasons to use each one are later discussed:

1. Single quotes (recommended)

mdc execute 'echo hello world'

2. Double quotes

mdc execute "echo hello world"

3. Double dash

mdc execute -- echo hello world

4. No qualifier

mdc execute echo hello world

In addition to these methods, an escape character (\) can avoid the interpretation of special characters. You can read more about special characters and escape characters here.

Single Quotes

When using single quotes around the command, the shell is instructed NOT to evaluate special characters. In this case, all special characters would be passed by mdc execute to be remotely evaluated. This is the easiest way to prevent your local shell from evaluating dashes (used as switches) and dollar signs (used as environment variables).

Double Quotes

When using double quotes around the command, the shell is instructed Not to evaluate special characters EXCEPT dollar signs ($). In this case, special characters such as dashes (used as switches) are passed to be remotely evaluated, but the local shell evaluates all environment variables. This is the easiest way to pass commands with special characters for remote execution but use local environment variables values.

Double Dash (--)

Adding a double dash inside an DSim Cloud command indicates the end of options, and all switches after that are treated as operands even if they start with a dash (-). This can be used if you rather not enclose your command with quotes but would like to send quotes for remote execution.

No Qualifier

The local shell will evaluate all special characters when not using any qualifier. It can be used when no special characters are used or if you rather escape them individually. Dashes can NOT be escaped.

Example(s)

For the following examples, we will be using a local environment variable. Please make sure to set it in your local terminal.

On Windows (Powershell):

>set local local_value
>echo $local
local_value

On Linux (bash) & macOS (zsh):

>local=local_value
>echo $local
local_value

Notes:

• On any other shell, please make sure to set the local variable before using the examples.
• The environment variable $pwd (current directory) is used in remote execution in the examples.
• The command seq 1 10 is used in the examples. This command generates a new line with numbers from 1 to 10.

Using a remote environment variable in the remote command

Correct:

mdc execute 'echo $pwd'
mdc execute "echo \$pwd"
mdc execute -- echo \$pwd
mdc execute echo \$pwd

Incorrect: ($pwd is evaluated by the local shell)

mdc execute "echo $pwd"
mdc execute -- echo $pwd
mdc execute echo $pwd

Passing a local environment variable to the remote command

Correct:

mdc execute "echo $local"
mdc execute -- echo $local
mdc execute echo $local

Incorrect: (local variable is not evaluated)

mdc execute 'echo $local'

Passing switches to a remote command

Correct:

mdc execute 'dsim -help'
mdc execute "dsim -help"
mdc execute -- dsim -help

Incorrect: (-help is evaluated by the local shell)

mdc execute dsim -help
mdc execute dsim \-help

Piping results to a local file

Correct:

mdc execute 'seq 1 10' > local.log
mdc execute "seq 1 10" > local.log
mdc execute -- seq 1 10 > local.log
mdc execute seq 1 10 > local.log

Incorrect: (piping to remote file)

mdc execute 'seq 1 10 > local.log'
mdc execute "seq 1 10 > local.log"

Piping results to a remote file

Correct:

mdc execute 'seq 1 10 > remote.log'
mdc execute "seq 1 10 > remote.log"
mdc execute -- seq 1 10 \> remote.log
mdc execute seq 1 10 \> remote.log

Incorrect: (piping to local file)

mdc execute 'dsim -help' > remote.log
mdc execute "dsim -help" > remote.log

Conditional local execution

Correct:

mdc execute 'seq 1 10' && hostname
mdc execute "seq 1 10" && hostname
mdc execute -- seq 1 10 && hostname
mdc execute seq 1 10 && hostname

Incorrect: (hostname command is executed remotely)

mdc execute 'seq 1 10 && hostname'
mdc execute "seq 1 10 && hostname"

Conditional remote execution

Correct:

mdc execute 'seq 1 10 && hostname'
mdc execute "seq 1 10 && hostname"
mdc execute -- seq 1 10 \&\& hostname
mdc execute seq 1 10 \&\& hostname

Incorrect: (hostname command is executed locally)

mdc execute 'seq 1 10' && hostname
mdc execute "seq 1 10" && hostname