7. Command line reference

The vipu command line has the following syntax:

vipu [GlobalOptions] command ResourceType arguments [LocalOptions]

7.1. Resource types

As a user, you have access to a set of resource types to run commands against. These serve as the base objects in the V-IPU world.

Resource type	Description
`agent`	An agent runs on an IPU host device and helps set up IPUs for the Poplar application execution. Typically, an agent represents four IPUs.
`allocation`	An allocation is a logical representation of one or more agents bundled together. Users assigned to an allocation have access to the underlying IPUs managed by the agents tied to that particular allocation.
`ipu`	An IPU managed by an agent.
`partition`	A partition is a group of IPUs from an allocation assigned to do computational work (such as TensorFlow or Poplar applications) and configured such that the IPUs are able to communicate with one another. IPUs within a partition are “occupied” until the partition is deleted.

7.2. Global options

Global options work with all vipu commands. You can also pass global options as environment variables or in a config file.

Table 7.1 Global options
Option	Description
`--api-access-key string`	API access key
`--api-allocation-id string`	Allocation ID to use for partition operations
`--api-host string`, `-H string`	Controller hostname or IP address
`--api-port int`, `-P int`	Controller port number (default 8090)
`--api-user-id string`	API user ID
`--config string`	Choose a configuration file explicitly; do not look in the default locations
`--help`, `-h`	Show help for the `vipu` command
`--quiet`, `-q`	Set quiet mode for the utility
`--secure`	Connect to the V-IPU controller in secure mode
`--server-socket string` `-S string`	Choose the local Unix socket to connect to the V-IPU controller. If this option is used the `--api-host` option is ignored
`--server-version`	Show version of the remote server
`--showjson`	Select JSON output
`--timeout int`	Set the time-out for client calls in seconds (default 200)
`--tls-cert-dir string`	Directory for the TLS certificates (default `VIPU_HOME/vipu-certs/client`)
`--version`, `-v`	Show version

7.2.1. Using a configuration file

All the global options listed in Table 7.1 can be overridden with a vipu-cli configuration file. The option names in the configuration file are identical but without the leading hyphens. For example, if you run vipu with the following command from the shell:

$ vipu --api-host my-host --api-port 8100 list agents

The corresponding options can be overridden in a configuration file that looks like this:

// vipu utility will try to connect to the API endpoint at myhost:8100
api-host = "my-host"
api-port = "8100"

The command line utility (vipu) will look for a configuration file in the following ordered list of directories and will load the first configuration file found:

Configuration file provided with the --config option
./.vipu-cli.hcl
$HOME/.vipu-cli.hcl
/etc/vipu/vipu-cli.hcl

7.2.2. Using environment variables

All the options listed in Table 7.1 can be overridden using environment variables using the syntax: VIPU_CLI_OPTION_NAME.

Everything should be upper case without the leading hyphens. The remaining hyphens (-) should be replaced by underscores (_). For example, if you run vipu with the following command from the shell:

$ vipu --api-host my-host --api-port 8100 list agents

The corresponding options can be overridden with the following environment variables:

$ export VIPU_CLI_API_HOST="my-host"
$ export VIPU_CLI_API_PORT="8100"

7.3. Create partition

Creates an instance of a partition in the V-IPU controller.

7.3.1. Syntax

vipu [GlobalOptions] create partition [PARTITION_NAME] [LocalOptions]

7.3.2. Examples

# Create a partition "prt-0" of 4 IPUs
$ vipu create partition prt-0 --size 4

# Create a partition and specify output dir for configuration file
$ vipu create partition prt-0 --size 4 -s /path/to/confdir

7.3.3. Options

Table 7.2 Partition creation options
Option	Description
`--all`	Show all possible partitions
`--cluster string`	Specify a cluster ID
`--gw-routing string`	Routing to use for GW-Links: “default” (default) or “ring”
`--help`, `-h`	Help with syntax and options
`--index int`	Choose a partition from the list returned by `--options`
`--ipuof-config-attrs boolean`	Enable or disable writing attributes to IPUoF config file (default true)
`--ipuof-config-enable boolean`	Enable or disable writing IPUoF config file (default true)
`--ipuof-config-location string`, `-s string`	Directory to write IPUoF config file to (default `$HOME/.ipuof.conf.d`)
`--ipuof-config-ports boolean`	Enable or disable support for IPUoF with non-default ports (default true)
`--options`	Get a list of all possible partitions that could be created
`--reconfigurable`	Enables reconfiguration for fabric multi-IPU partitions
`--routing string`	Routing to use for IPU-Links: “dnc” (default), “btnc”, “swnc” or “ringswnc”
`--size int`	Desired size (number of IPUs) of the new partition (must be a power of 2)

7.4. Get partition

Get information about a partition instance.

7.4.1. Syntax

vipu [GlobalOptions] get partition [PARTITION_NAME] [LocalOptions]

7.4.2. Examples

# Get info about partition prt-0
$ vipu get partition prt-0
----------------------------------------------------------------------------
Partition ID         | prt-0
Cluster              | cl0
GW-Link Routing      | DEFAULT
IPU-Link Routing     | DNC
Number of ILDs       | 1
Number of IPUs       | 4
Number of GCDs       | 1
Reconfigurable       | false
State                | ACTIVE
Provisioning State   | IDLE
Intra-GCD Sync (GS1) | Replicas=1
Inter-GCD Sync (GS2) | UNDEFINED
Last Error           |
IPUs                 | 0=agent-00:0 1=agent-00:1 2=agent-00:2 3=agent-00:3
----------------------------------------------------------------------------

7.4.3. Options

Option	Description
`--ipuof-configs`	Returns only IPUoF configurations
`--help`, `-h`	Help with syntax and options

7.5. List allocation

Lists allocations a user has access to.

7.5.1. Syntax

vipu [GlobalOptions] list allocation [LocalOptions]

7.5.2. Examples

# List allocations fernando has access to
$ vipu list allocation --api-user-id fernando --api-access-key ******
-----------------------------------
  Allocation ID | Agents
-----------------------------------
  al0           | agent-00
  al1           | agent-01 agent-02
-----------------------------------

7.5.3. Options

Option	Description
`--help`, `-h`	Help with syntax and options

7.6. List agents

Lists agents from all allocations a user has access to.

7.6.1. Syntax

vipu [GlobalOptions] list agents [LocalOptions]

7.6.2. Examples

# List agents from allocations the user fernando can access
$ vipu list agent --api-user-id fernando --api-access-key ******

  Agent       | Host      | Port  | Status | Agent Version      | IPUs | Last Error
-----------------------------------------------------------------------------------
  agent-00    | 10.1.2.3  | 38525 | Up     | 1.5                | 4/4  |
  agent-01    | 10.1.2.4  | 36807 | Up     | 1.5                | 4/4  |
  agent-02    | 10.1.2.5  | 47793 | Up     | 1.5                | 4/4  |
-----------------------------------------------------------------------------------

7.6.3. Options

Option	Description
`--help`, `-h`	Help with syntax and options

7.7. List partition

Lists all partition instances in the allocations a user has access to.

7.7.1. Syntax

vipu [GlobalOptions] list partition [LocalOptions]

7.7.2. Examples

# List partitions the user fernando has access to
$ vipu list partition --api-user-id fernando --api-access-key ******

  Partition   | Cluster | ILDs | GW Routing | ILD Routing | Size | GCDs | State
  --------------------------------------------------------------------------------
   prt-0       | cl0     | 1    | DEFAULT    | DNC         | 2    | 1    | ACTIVE
   prt-1       | cl0     | 1    | DEFAULT    | DNC         | 2    | 1    | ACTIVE
   prt-2       | cl0     | 1    | DEFAULT    | DNC         | 2    | 1    | ACTIVE
   prt-3       | cl0     | 1    | DEFAULT    | DNC         | 2    | 1    | ACTIVE
  --------------------------------------------------------------------------------

7.7.3. Options

Option	Description
`--help`, `-h`	Help with syntax and options

7.8. Remove a partition

Removes an instance of a partition.

7.8.1. Syntax

vipu [GlobalOptions] remove partition [PARTITION_NAME] [LocalOptions]

7.8.2. Examples

# Remove partition prt-3
$ vipu remove partition prt-3

# Remove partitions prt-1 and prt-2
$ vipu remove partition prt-1 prt-2

7.8.3. Options

Option	Description
`--help`, `-h`	Help with syntax and options
`--ipuof-config-location string` `-s string`	Directory to check for removing IPUoF config files (default `/home/$USER/.ipuof.conf.d`)
`--force`, `-f`	Force the removal of the partition ignoring errors

7.9. Reset partition

Recreates a partition instance with the same specifications.

7.9.1. Syntax

vipu [GlobalOptions] reset partition [PARTITION_NAME] [LocalOptions]

7.9.2. Examples

# Reset/recreate partition prt-0
$ vipu reset partition prt-0

# Reset all partitions
$ vipu reset partition --all

7.9.3. Options

Option	Description
`--help`, `-h`	Help with syntax and options
`--all`	Reset all partitions

7.10. Bash completion

Generates an auto-completion script for the Bash shell.

7.10.1. Syntax

vipu [GlobalOptions] bash-completion [LocalOptions]

7.10.2. Examples

# Generate a bash-completion script and show it in stdout
$ vipu bash-completion

# Generate script and store it as file .vipu-auto-comp
$ vipu bash-completion > .vipu-auto-comp

7.10.3. Options

Option	Description
`--help`, `-h`	Help with syntax and options

7.11. Zsh completion

Generates an auto-completion script for the Zsh shell.

7.11.1. Syntax

vipu [GlobalOptions] zsh-completion [LocalOptions]

7.11.2. Examples

# Generate a zsh-completion script and show it in stdout
$ vipu zsh-completion

# Generate script and store it as file .vipu-auto-comp
$ vipu zsh-completion > .vipu-auto-comp

7.11.3. Options

Option	Description
`--help`, `-h`	Help with syntax and options