8. Command line reference

The vipu command line has the following syntax:

vipu [GlobalOptions] command ResourceType arguments [LocalOptions]

8.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.

8.2. Global options

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

Table 8.1 Global options
Option	Description
`--api-access-key string`	API access key
`--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

8.2.1. Using a configuration file

All the global options listed in Table 8.1 can be overridden with a V-IPU 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 partition

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 V-IPU configuration file in the following directories, in this order, and will load the first file found:

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

If you include credentials in the configuration file, then make sure that only your account has access to it (for example, chmod 0600 .vipu.hcl).

8.2.2. Using environment variables

All the global options listed in Table 8.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 allocation

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

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

8.3. Create partition

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

8.3.1. Syntax

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

8.3.2. Examples

# Create a partition "prt-0" of 4 IPUs in the user's default allocation
$ vipu create partition prt-0 --size 4

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

8.3.3. Options

Table 8.2 Partition creation options
Option	Description
`--all`	Show all possible partitions, including those that have already been used
`--allocation string`	Specify an allocation ID (creates the partition in the user’s default allocation when not specified)
`--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 configuration file (default true)
`--ipuof-config-enable boolean`	Enable or disable writing IPUoF configuration file (default true)
`--ipuof-config-location string`, `-s string`	Directory to write IPUoF configuration file to (default `$HOME/.ipuof.conf.d`)
`--ipuof-config-ports boolean`	Enable or disable support for IPUoF with non-default ports (default true)
`--max-partition-options uint32`	Specify the maximum number of partition options to be returned. Used in conjunction with `--options` (0 returns all options, default 10)
`--num-gcds uint32`	Specify the number of GCDs in the partition (default 1)
`--options`	Get a list of all possible partitions that could be created
`--reconfigurable`	Enables reconfiguration for fabric multi-IPU partitions
`--relocatable`	Enables relocatable flag for the partition. A relocatable partition can be relocated to a different set of IPUs by the V-IPU controller, if needed.
`--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)
`--sync-type string`	Sync type for the partition: “pod-native-default” (default), “c2-compatible” (default if `--reconfigurable` is set), “independent-rails”, “pod-native-repgraph”
`--total-num-replicas uint32`	Specify the total number of replicas across all GCDs (default: 1 replica per GCD)

8.4. Get partition

Get information about a partition instance.

8.4.1. Syntax

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

8.4.2. Examples

# Get info about partition prt-0
$ vipu get partition prt-0
----------------------------------------------------------------------------
Partition                | prt-0
Cluster                  | cl0
Allocation               | project1
GW-Link Routing          | DEFAULT
IPU-Link Routing         | DNC
Number of ILDs           | 1
Number of IPUs           | 4
Number of GCDs           | 1
Reconfigurable           | false
State                    | ACTIVE
IPUoF Server version     | latest
Provisioning State       | IDLE
Sync Type                | POD_NATIVE_DEFAULT
Number of Replicas       | Replicas=1
Last Error               | N/A
Max Auto-Reset Retries   | 10
Current Auto-Reset Count | 0
Last Auto-Reset Time     | N/A
IPUs                     | 0=agent-00:0 1=agent-00:1 2=agent-00:2 3=agent-00:3
----------------------------------------------------------------------------

8.4.3. Options

Option	Description
`--gcd id`	Only output information for the specified GCD.
`--ipuof-configs`	Outputs only IPUoF configuration information. The IPUoF information for each GCD is output in JSON format (as used in IPUoF configuration files). For a multi-GCD partition, the output will only be valid JSON if the `--gcd id` option is also used.
`--help`, `-h`	Help with syntax and options.

8.5. List allocation

Lists allocations a user has access to.

8.5.1. Syntax

vipu [GlobalOptions] list allocation [LocalOptions]

8.5.2. Examples

# List allocations fernando has access to
$ vipu list allocation --api-user-id fernando --api-access-key ******

--------------------------------------------------------------------------------------------------
 Cluster ID | Allocation ID | Agents
--------------------------------------------------------------------------------------------------
 cl0        |  project1     | agent-00
 cl0        |  project2     | agent-01 agent-02
--------------------------------------------------------------------------------------------------

8.5.3. Options

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

8.6. List IPU attributes

$ ./vipu list ipu-attrs [options]

List IPU attributes from agents in allocations the user has access to.

8.6.1. Supported options

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

8.7. List partition

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

8.7.1. Syntax

vipu [GlobalOptions] list partition [LocalOptions]

8.7.2. Examples

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

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

8.7.3. Options

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

8.8. Remove a partition

Removes an instance of a partition.

8.8.1. Syntax

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

8.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

8.8.3. Options

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

8.9. Reset partition

Recreates a partition instance with the same specifications.

8.9.1. Syntax

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

8.9.2. Examples

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

# Reset all partitions
$ vipu reset partition --all

8.9.3. Options

Option	Description
`--all`	Reset all partitions
`--relocatable`	Enable relocatable flag for the partition. Existing flag will be overridden.
`--help`, `-h`	Help with syntax and options

8.10. Bash completion

Generates an auto-completion script for the Bash shell.

8.10.1. Syntax

vipu [GlobalOptions] bash-completion [LocalOptions]

8.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

8.10.3. Options

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

8.11. Zsh completion

Generates an auto-completion script for the Zsh shell.

8.11.1. Syntax

vipu [GlobalOptions] zsh-completion [LocalOptions]

8.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

8.11.3. Options

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

Search help