Skip to main content
Pure1 Support Portal

Purity CLI Overview

The Purity command line interface (CLI) is a non-graphical, command-driven interface used to query and administer the FlashArray. The Purity CLI is comprised of built-in commands specific to the Purity operating environment.

This chapter covers general Purity CLI concepts and conventions.

CLI Command Syntax and Conventions

Purity CLI commands have the general form:

command subcommand --options OBJECT-LIST
        

The parts of a command are:

COMMAND

Type of FlashArray object to be acted upon, prefixed by "pure". For example, the purevol command acts on Purity virtual storage volumes.

Run the purehelp command to see a list of Purity CLI commands.

SUBCOMMAND

Action to be performed on the specified object. Most CLI subcommands are common to some or all object types.

For example, purehost list lists all hosts on the array, while purevol list lists all volumes on the array.

The following subcommands are common to most or all object types:

create

Creates and names one or more FlashArray objects.

delete

Deletes one or more specified objects.

list

Lists information about one or more objects. To list information for all objects, do not specify the object in the command.

listobj

Creates whitespace-separated lists of objects or attributes related to one or more objects. For example, purevol listobj --type host creates a list of the hosts to which volumes have connections. The listobj subcommand is primarily used to create lists of object and attribute names for scripting purposes.

rename

Changes the name of the specified object. Purity identifies the object name in administrative operations and displays. The new name is effective immediately and the old name is no longer recognized in Purity GUI and CLI interactions. In the Purity GUI, the new name appears upon page refresh. Hardware object names cannot be changed.

setattr

Changes the attribute values of the specified objects.

OPTIONS

Options that specify attribute values or modify the action performed by the subcommand.

For example, in the following command, the --addvollist option adds volumes VOL1, VOL2, and VOL3 to protection group PGROUP1:

purepgroup setattr --addvollist VOL1,VOL2,VOL3 PGROUP1
                

Some options, such as --hostlist, inherently apply only to a single object. Other options, such as --size, can be set for multiple objects in a single command.

Some options can be multi-valued. For example, in the following command, the --hostlist option associates multiple hosts (HOST1, HOST2, and HOST3) with the host group HGROUP1.

purehgroup setattr --hostlist HOST1,HOST2,HOST3 HGROUP1
                

OBJECT-LIST

Object or list of objects upon which the command is to be operated.

If a subcommand changes the object state, then at least one object must be specified. Examples of subcommands that change the object state include create, delete, and setattr. For example, purehost create HOST1 creates host HOST1. In the command synopses, OBJECT specifications that are not enclosed in square brackets (for example, "HOST") represent ones that are required.

Passive subcommands, such as list, which do not change object state, do not require object specification. Leaving out the object is equivalent to specifying all objects of the type. For example, purevol list with no volumes specified displays information about all volumes in an array. In the command synopses, OBJECT specifications enclosed in square brackets (for example, "[HOST]") represent ones that are optional.

Most subcommands act on a single object. For example, in the following command, the setattr subcommand can only be run on a single host group to change the attributes of that host group.

purehgroup setattr --addhostlist HOST1 HGROUP1
                

Certain subcommands can operate on multiple objects. For example, the following command connects volume VOL1 to host groups HGROUP1 and HGROUP2.

purehgroup connect --vol VOL1 HGROUP2 HGROUP2
                

In the command synopses, OBJECT specifications that are followed by ellipses (for example, HGROUP...) indicate that multiple objects can be entered.

The following list describes the conventions used in CLI help documentation:

  • Text in fixed-width (Courier) font must be entered exactly as shown. For example, purehost list.

  • Text not enclosed in brackets represents mandatory text.

  • Text inside square brackets (“[ ]”) represents optional items. Do not type the brackets.

  • Text inside curly braces (“{ }”) represents text, where one (and only one) item must be specified. Do not type the braces.

  • The vertical bar (|) separates mutually exclusive items.

  • Uppercase italic text represents entered text whose value is based on the nature of the subcommand or option. For example, --size SIZE, where SIZE represents the value to be entered, such as 100g.

CLI Output

Various Purity CLI subcommands, including list and monitor, generate list outputs. With the ability to create and manage hundreds of volumes and snapshots, list outputs can become very long.

The Purity CLI includes options to control the way a list output is displayed and formatted. The CLI also includes sort, filter, and limit options to control the results you see and the order in which you see them.

Interactive Paging

Pagination divides a large output into discrete pages. Pagination is disabled by default and is only in effect if the --page option is specified and the number of lines in the list output exceeds the size of the window.

To interactively move through a paginated list output:

  • Press the [Right Arrow] key or space bar to move to the next page.

  • Press the [Left Arrow] key to move to the previous page.

To quit interactive paging and exit the list view, press q .

With pagination, each page of the CLI list output begins with the column titles. To suppress the column titles, run the command with the --notitle option.

Using Wildcards

The asterisk (*) symbol denotes a wildcard character used in list or monitor operations to represent zero or more characters in an object name. The object name can include multiple asterisks.

When performing a list or monitor operation, include the asterisk in the name argument to expand the list results. For example, the purehost list *cat* command displays a list of all hosts that contain "cat", such as cat, catnap, happycats, and lolcat. If the asterisks were not included, only the host named cat would be returned. As another example, the purevol list *vol* command displays a list of all volumes that contain "vol", including ones that begin or end with "vol".

$ purevol list *vol*
Name      Size  Source  Created
Myvol     100G  -       2016-04-11 10:18:07 PDT
MyVol-01  100G  -       2016-04-11 10:18:07 PDT
vol       1G    -       2016-04-11 11:19:19 PDT
vol01     100G  -       2016-04-11 10:17:23 PDT
Volume    100G  -       2016-04-11 10:17:23 PDT
          

If Purity cannot find matches for the wildcard argument specified, an error message appears.

Asterisks are also allowed in Purity CLI options that take a list of object names. For example, the purevol list --snap --pgrouplist *pg* command displays a list of all volume snapshots that are created as part of a protection group snapshot with "pg" in the protection group name. As another example, the following command displays a list of volume snapshots for all volumes that end with "01" and are created as part of a protection group snapshot with "pg" in the protection group name.

$ purevol list --snap --pgrouplist *pg* *01
Name                    Size  Source  Created
pgroup01.001.vol01      100G  vol01   2016-04-13 11:44:46 PDT
pgroup01.123.vol01      100G  vol01   2016-04-13 11:44:46 PDT
pgroup01.abc.vol01      100G  vol01   2016-04-13 11:44:46 PDT
pgroup01.backup.vol01   100G  vol01   2016-04-13 11:44:45 PDT
pgroup01.snap001.vol01  100G  vol01   2016-04-13 11:44:45 PDT
pgroup01.snap002.vol01  100G  vol01   2016-04-13 11:44:42 PDT
pgroup01.suffix.vol01   100G  vol01   2016-04-13 11:44:46 PDT
          

Formatting

Format options control the way list outputs are displayed. The following format options are common to most list and monitor subcommands:

--cli

Displays output in the form of CLI commands that can be issued to reproduce the current configuration. The --cli output is not meaningful when combined with immutable attributes.

--csv

Lists information in comma-separated value (CSV) format. The --csv output can be used for scripting purposes and imported into spreadsheet programs.

--notitle

Lists information without column titles.

--nvp

Lists information in name-value pair (NVP) format, in the form ITEMNAME=VALUE. Argument names and information items are displayed flush left. The --nvp output is designed both for convenient viewing of what might otherwise be wide listings, and for parsing individual items for scripting purposes.

--page

Turns on interactive paging.

--raw

Displays the unformatted version of column titles and data. For example, in the purearray monitor output, the unformatted version of column title us/op (read) is usec_per_read_op. The --raw output is used to sort and filter list results.

Here is a comparison between the purehost list output with formatted column titles and data, and the same output with unformatted column titles and data:

$ purehost list --space
Name  Size  Thin Provisioning  Data Reduction  ...
H001  60T   57%                1.5 to 1        ...

$ purehost list --space --raw
name  size            thin_provisioning  data_reduction  ...
H001  65970697666560  0.5712341          1.5123          ...

Sorting

When running a list or monitor operation, include the --sort option to sort a column of the output in ascending or descending order. The following commands support the --sort option: purehgroup, purehost, purepgroup, pureport, and purevol.

The sort option adheres to the following syntax:

--sort SORT

SORT represents a comma-separated list of columns to sort. Use the unformatted title name (--raw) of the column to represent each column listed. To sort a column in descending order, append the minus (-) sign to the column name.

For example, run the following commands to get the unformatted column titles in the purehost list output, and then sort the same output by host group in descending order:

$ purehost list --raw
name                       ...  hgroup
ESXi-GRP-Cluster02-H0001   ...  ESXi-GRP-Cluster02-HG003
ESXi-GRP-Cluster02-H0002   ...  ESXi-GRP-Cluster02-HG003
ESXi-IT-Cluster01-H0001    ...  ESXi-IT-Cluster01-HG001
ESXi-IT-Cluster02-H0001    ...  ESXi-IT-Cluster02-HG002
ESXi-STG-Cluster03-H0001   ...  ESXi-STG-Cluster03-HG005

$ purehost list --sort hgroup-
Name                       ...  Host Group
ESXi-STG-Cluster03-H0001   ...  ESXi-STG-Cluster03-HG005
ESXi-IT-Cluster02-H0001    ...  ESXi-IT-Cluster02-HG002
ESXi-IT-Cluster01-H0001    ...  ESXi-IT-Cluster01-HG001
ESXi-GRP-Cluster02-H0002   ...  ESXi-GRP-Cluster02-HG003
ESXi-GRP-Cluster02-H0001   ...  ESXi-GRP-Cluster02-HG003

If multiple columns are specified, the output is sorted by the order of the columns listed.

If a sorted column contains non-unique values and a secondary sort argument is not specified, Purity automatically performs a secondary sort using the default sort criteria (typically by Name).

Examples

Example 1: Display a list of volumes sorted in descending order by physical space occupied.

$ purevol list --space --sort "total-"

Example 2: Display a list of protection groups sorted in ascending order by source array name.

$ purepgroup list --sort "source"

Example 3: Display a list of volumes that are sorted in descending order by volume size. If any of volumes are identical in size, sort those volumes in descending order by physical space occupied.

$ purevol list --space --sort size-,total-

Filtering

When running a list or monitor operation, include the --filter option to narrow the results of the output to only the rows that meet the filter criteria. The following commands support the --filter option: purehgroup, purehost, purepgroup, pureport, and purevol. Filtering can be performed on any column of the list output.

Filtering with Operators

When filtering with operators, use the following syntax:

--filter "RAW_TITLE OPERATOR VALUE"

RAW_TITLE represents the unformatted title name of the column by which to filter. Run the list or monitor operation with the --raw option to get the unformatted title name.

OPERATOR represents the type of filter match (=, !=, <, >, <=, or >=) used to compare RAW_TITLE to VALUE.

VALUE represents the value (number, date, or string) that determines the results to be included in the list output. Literal strings must be wrapped in quotes.

Filtering supports the following operators:

OperatorDescription
=Equals
!=Does not equal
<Less than
>Greater than
<=Less than or equal to
>=Greater than or equal to

Filtering supports the asterisk wildcard character. For example, the value "*esx*" in the purepgroup list --filter "hosts=*esx*" command displays a list of all protection groups with hosts members that contain "esx" in the host name.

The AND and OR operators can be used to further refine your filter. The AND operator displays only the results that meet all of the filter criteria in the command. The OR operator displays the results that meet at least one of the filter criteria in the command.

Examples

Example 1: Display a list of protection groups configured on source array pure-001.

$ purepgroup list --filter "source = 'pure-001'"

Example 2: Display a list of volumes that were created on or before 2016-05-23 13:09:39.

$ purevol list --filter "created <= '2016-05-23 13:09:39 PDT'"

Example 3: Display a list of volume snapshots that are greater than 2 gigabytes in size.

$ purevol list --space --snap --filter "snapshots > '2G'"

Example 4: Display a list of volumes that are currently inactive.

$ purevol monitor --filter "output_per_sec=0 and input_per_sec=0"

Example 5: Display a list of volumes that begin with "vol10" or are greater than 100 gigabytes in size.

$ purevol list --filter "name = 'vol0*' or size > '100G'"

Filtering with Functions

The filter option supports the CONTAINS and NOT functions.

--filter FUNCTION(PARAMETERS)

FunctionDescription
contains(raw_title,string)

Contains the enclosed string.

Takes exactly two parameters, where raw_title represents the unformatted title name of the column by which to filter and string represents the string to search within the column. Run the list or monitor operation with the --raw option to get the unformatted title name.

not(expression) Inverse of the enclosed expression.

Examples

Example 1: Get a list of all volumes that include "cluster03" in the volume name.

$ purevol list --filter "contains(name, 'cluster03')"
  

Example 2: Get a list of all hosts that are associated with host groups with "PROD" in the host group name.

$ purehost list --filter "contains(hgroup, 'PROD')"
  

Example 3: Get a list of all hosts that are not associated with host groups with "PROD" in the host group name.

$ purehost list --filter "not(contains(hgroup, 'GRP'))"
  

Existence Checks

The Purity CLI supports existence checks. For example, the purevol list --filter "name" command checks to see if the "name" column exists in the volume list output.

Examples

Example 1: Get a list of all hosts associated with a host group.

$ purehost list --filter "hgroup"
  

Example 2: Get a list of all volumes that were not created from another source.

$ purevol list --filter "not(source)"
  

Example 3: Get a list of all hosts that are not associated with Fibre Channel WWNs.

$ purehost list --filter "not(wwn)"
  

Setting Limits

When running a list or monitor operation, include the --limit option to restrict the result size to the limit specified. The following commands support the --limit option: purehgroup, purehost, purepgroup, pureport, and purevol.

The limit option adheres to the following syntax:

--limit ROWS

ROWS represents the maximum number of rows to return.

For example, run the following command to list only the first 5 rows of the purevol list output:

$ purevol list --limit 5
Name                   Size  Source  Created                  Serial
ESXi-Cluster01-vol001  100G  -       2016-05-23 13:09:40 PDT  B143778B8ACE487B00011021
ESXi-Cluster01-vol002  100G  -       2016-05-23 13:09:40 PDT  B143778B8ACE487B0001101D
ESXi-Cluster01-vol003  100G  -       2016-05-23 13:09:40 PDT  B143778B8ACE487B00011024
ESXi-Cluster01-vol004  100G  -       2016-05-23 13:09:40 PDT  B143778B8ACE487B00011018
ESXi-Cluster01-vol005  100G  -       2016-05-23 13:09:40 PDT  B143778B8ACE487B00011025

Combining Sorting, Filtering, and Limit Options

The --sort, --filter, and --limit options can all be combined together.

Examples

Example 1: Display the top 10 volumes that occupy the largest amount of physical space and include "esx" in the volume name.

$ purevol list --space --sort "total-" --limit 10 --filter "name = '*esx*'"

Example 2: Display the top 10 volumes that have the largest physical space occupied by data unique to one or more snapshots.

purevol list --space --sort "snapshots-" --limit 10

Example 3: Display the top 10 volumes with the highest data reduction ratios.

$ purevol list --space --sort "data_reduction-" --limit 10

Example 4: Display the top 10 volumes that use the most read bandwidth.

$ purevol monitor --sort "output_per_sec-" --limit 10

Example 5: Display the top 10 volumes with the largest provisioned sizes and have shared connections to host groups with "PROD" in the host group name.

$ purevol list --connect --filter "hgroup = '*PROD*'" --sort size- --limit 10

CLI Login

Log in to the Purity CLI to query and administer the FlashArray. Logging in to the Purity CLI requires a virtual IP address or fully-qualified domain name (FQDN) and a login username and password; this information is determined during the FlashArray installation. The CLI has been tested with the following remote access packages:

  • SSH (all common UNIX and Linux distributions)

  • PuTTY

Logging in to the Purity CLI

To log in to the Purity CLI, select one of the following two options:

  • UNIX. Start a secure shell (SSH) session, and then connect to the array using the login username and password obtained during the FlashArray installation.

  • Windows. Start a remote terminal emulator (such as PuTTY), and then connect to the array using the login username and password obtained during the FlashArray installation.

Type exit or logout to log out of Purity and exit the shell or terminal emulator.

CLI Help

The Purity CLI includes documentation for how to invoke and use each Purity CLI command. Two types of interactive help are available through the Purity CLI:

  • The built-in Purity CLI command help facility provides brief descriptions and usage information for each Purity CLI command, subcommand, and option.

  • The Purity CLI man pages (or manual pages) is a more formal version of documentation that provides detailed information for each Purity CLI command.

Run the purehelp command to see a list of Purity CLI commands.

Purity CLI Command Help

CLI command help is available at both the command and subcommand levels. To use it, type the Purity CLI command or subcommand followed by -h or --help. Type the Purity CLI command with the -h or --help switch to display usage information, supported syntax, and a list of subcommands for the specified command.

COMMAND -h
  

For example (truncated for brevity),

$ purevol -h
usage: purevol [-h]
       {connect,copy,create,destroy,disconnect,eradicate,
        list,listobj,monitor,recover,rename,setattr,snap,truncate}
       ...
positional arguments:
{connect,copy,create,destroy,disconnect,eradicate,
list,listobj,monitor,recover,rename,setattr,snap,truncate}
connect             connect one or more volumes to a host
copy                copy a volume or snapshot to one or more volumes
create              create one or more volumes
destroy             destroy one or more volumes or snapshots
disconnect          disconnect one or more volumes from a host
eradicate           eradicate one or more volumes or snapshots
...
optional arguments:
-h, --help            show this help message and exit
  

Type the Purity CLI subcommand with -h or --help switch to display usage information, supported syntax, and a list of options for the specified subcommand.

COMMAND SUBCOMMAND -h
  

For example,

$ purevol create -h
usage: purevol create [-h] --size SIZE VOL ...

positional arguments:
VOL          volume name

optional arguments:
-h, --help   show this help message and exit
--size SIZE  virtual size as perceived by hosts (e.g., 100M, 10G, 1T)
  

Purity CLI Man Pages

CLI man pages display extensive help for each CLI command. To display the man page for a Purity CLI command, run the pureman command with the Purity CLI command or subcommand name.

pureman COMMAND
  

or

pureman COMMAND-SUBCOMMAND
  

For example (truncated for brevity),

$ pureman purevol
PUREVOL(1)                  Purity CLI Man Pages                  PUREVOL(1)

NAME
purevol, purevol-copy, purevol-create, purevol-destroy,
purevol-eradicate
...
- manage the creation, naming, and destruction of Purity
virtual storage volumes and snapshots of their contents,
as well as the reclamation of physical storage occupied
by the data in them
purevol-monitor - monitor volume I/O performance

SYNOPSIS
purevol copy [--overwrite] SOURCE TARGETVOL
purevol create --size SIZE VOL...
purevol destroy VOL...
purevol eradicate VOL...
...

ARGUMENTS
SOURCE
Volume or snapshot from where data is copied.
The data is copied to the TARGETVOL volume.
TARGETVOL
Volume to where data is copied.
The data is copied from the SOURCE volume or snapshot.
VOL
Volume to be created, destroyed, eradicated, recovered,
or snapped.
...

OPTIONS
--interval SECONDS (purevol monitor only)
Sets the number of seconds between displays of data.
At each interval, the system displays a point-in-time snapshot
of the performance data.
If omitted, the interval defaults to every 5 seconds.

--overwrite
Allows purevol copy to overwrite an existing volume.
Without this option, if the target volume already exists,
the command fails.
...
DESCRIPTIONS
This page describes management of volumes. The purevol create command...

EXAMPLES
Example 1
purevol create --size 100G vol1 vol2 vol3

Creates three volumes called vol1, vol2, and vol3, each
with a host-visible capacity of 100 gigabytes (10^2 * 2^30 bytes).
...

SEE ALSO
purevol-list(1), purevol-setattr(1), purehgroup(1),
purehgroup-connect(1), purehost(1), purehost-connect(1)

AUTHOR
Pure Storage Inc.