CLI Command Syntax

With few exceptions, CLI commands follow a simple syntax:

dsv <object> <action> [<args>]

For example, the CLI command that creates a new role looks like this:

dsv role create --name "my-role" --desc "role for example"

Objects

Workflows

A workflow is a series of questions that guides the user through the create or update process. For many objects, if the action is create or update, then adding no flags will start a workflow.

Workflow supported commands include:

• dsv init
• dsv config auth-provider
• dsv policy
• dsv siem
• dsv pki
• dsv user
• dsv group
• dsv role

If the object doesn't support a workflow, then the flag --help is assumed.

Parameters

Parameters can be:

• strings or numerics
• Boolean
• JSON data
• file path

Strings

Most commands take strings as parameters, quoted or unquoted. For example, the username uses quotes but the password does not. Both are valid string parameter values.

dsv user create --username "admin1" --password BadP@ssword

If a string value has spaces, it must be wrapped in quotes. For example, when creating a Role, the description should be quoted.

dsv role create --name test-role --desc "a test role"

Boolean

Some parameters are simple Boolean flags controlling whether or not something applies. For example, use --plain to not beautify the JSON output.

dsv secret read --path example:bash-json --plain

JSON Data and OS-Specific Syntax

In some cases the parameter expects JSON. For example, the --data parameter on a dsv secret create command expects JSON data.

JSON parameter formatting depends on the OS and shell program.

• Linux: wrap the JSON in a single quote (')
• PowerShell: wrap the JSON in a single quote (') and inside the JSON escape each double quote (") with a backslash (\)
• cmd.exe: wrap the JSON in a double quote (") and inside the JSON escape each double quote (") with a backslash (\)

dsv secret create --path example:bash-json --data '{"password":"bash-secret"}'

PS C:> dsv secret create --path example:ps-json --data '{\"password\":\"powershell-secret\"}'

C:> dsv secret create --path example:cmd-json --data "{\"password\":\"cmd-secret\"}"

File Path and OS-Specific Syntax

Passing JSON as a parameter remains practical only as long as the JSON remains short. Instead of passing JSON as a parameter, you can pass it as a file, using the @ prefix to specify the path to the file.

For instance, here the command is to create a Secret using a local file named secret.json. The examples show the minor variations among operating systems and shells.

dsv secret create --path example:bash-json --data @secret.json

PS C:> dsv secret create --path example:ps-json --data '@secret.json'

C:> dsv secret create --path example:cmd-json --data @secret.json

For passing a file as data, only Powershell requires the file path and name to be wrapped in quote marks, in this case single-quote marks.

Output Modifiers

DSV offers global flags that combine with most commands to format or redirect output.

• --encoding, -e specify the output format as either JSON or YAML
• --filter, -f filter to output only a specific JSON attribute; this feature uses the jq library
• --out, -o control the output destination; valid values: stdout, clip, and file:[file-name], with stdout the default
• --plain do not beautify JSON or YAML output

Encoding

dsv secret read --path servers:us-east:server01 -e yaml

Outputs:

attributes: null
data:
  host: server01
  password: Secretp@ssword
  username: administrator
id: c5239a6c-422e-4f57-b3a6-5167656af852
path: servers:us-east:server01

Filter

The filter modifier relies on a lightweight, flexible command line JSON processor, the jq library. Visit the JQ GitHub repo to learn more about how to use JQ.

The following code block illustrates:

dsv secret read --path resources:server01:mysql

Outputs:

{
  "attributes": {
    "tag1": "this is a tag"
  },
  "created": "2019-07-17T21:33:35Z",
  "createdBy": "users:ben",
  "data": {
    "foo": ["bar2", "blah"],
    "password": "root-password",
    "username": "blah"
  },
  "id": "59f2ab72-7f51-4f0e-8ffd-35cb94b818fb",
  "lastModified": "2019-07-17T21:36:01Z",
  "lastModifiedBy": "users:ben",
  "path": "resources:server01:mysql",
  "version": "1"
}

dsv secret read --path resources:server01:mysql --filter data.password

Outputs:

root-password

The command without the filter produced the entire Secret, while the command with the filter read out only the password value.

Out

The -o modifier allows output to be redirected to a file.

dsv secret read --path servers:us-east:server01 -o file:Secret.json
\$ nano Secret.json

Contents of Secret.json:

{
  "attributes": null,
  "data": {
    "host": "server01",
    "password": "Secretp@ssword",
    "username": "administrator"
  },
  "id": "c5239a6c-422e-4f57-b3a6-5167656af852",
  "path": "servers:us-east:server01"
}

Using -o clip puts the command output on the OS clipboard.

Output Piping

Output piping takes advantage of a common coding practice in which the value of a parameter passed to a command is itself a command or set of commands. When the outer command receiving the parameter executes, it evaluates the parameter, which requires it to run the command that was passed as a parameter. The output of that command becomes the parameter value for the outer command, which then continues to execute.

As an example, you can save any DSV CLI output into an environment variable by piping the output from the standard output into an environment variable.

export MYSecret=$(dsv secret read --path Secret1)

$MYSecret=dsv secret read --path Secret1

Both of the preceding would create an environment variable named MYSecret that would store the Secret data. To view the data you would use:

echo $MYSecret