# Amazon ParallelCluster CLI commands
Amazon ParallelCluster version 3 CLI commands

`pcluster` is the primary Amazon ParallelCluster CLI command. You use `pcluster` to launch and manage HPC clusters in the Amazon Web Services Cloud and to create and manage custom AMI images.

`pcluster3-config-converter` is used to convert cluster configurations in Amazon ParallelCluster version 2 format into Amazon ParallelCluster version 3 format.

```
pcluster [-h] ( build-image | configure | 
                create-cluster | dcv-connect | 
                delete-cluster | delete-cluster-instances | delete-image |
                describe-cluster | describe-cluster-instances | 
                describe-compute-fleet | describe-image |
                export-cluster-logs | export-image-logs | 
                get-cluster-log-events | get-cluster-stack-events | 
                get-image-log-events | get-image-stack-events |
                list-cluster-log-streams | list-clusters | 
                list-images | list-image-log-streams | list-official-images |
                ssh | update-cluster | 
                update-compute-fleet | version ) ...
pcluster3-config-converter [-h] [-t CLUSTER_TEMPLATE]
                [-c CONFIG_FILE]
                [--force-convert]
                [-o OUTPUT_FILE]
```

**Topics**
+ [

# `pcluster`
](pcluster-v3.md)
+ [

# `pcluster3-config-converter`
](pcluster3-config-converter.md)

# `pcluster`


`pcluster` is the primary Amazon ParallelCluster CLI command. You use `pcluster` to launch and manage HPC clusters in the Amazon Web Services Cloud.

`pcluster` writes logs of your commands to `pcluster.log.#` files in `/home/user/.parallelcluster/`. For more information, see [`pcluster` CLI logs](troubleshooting-v3-pc-cli-logs.md).

To use `pcluster`, you must have an IAM role with the [permissions](iam-roles-in-parallelcluster-v3.md#iam-roles-in-parallelcluster-v3-example-user-policies) required to run it.

```
pcluster [-h]
```

## Arguments


**`pcluster command`**  
Possible choices: [`build-image`](pcluster.build-image-v3.md) \$1 [`configure`](pcluster.configure-v3.md) \$1 [`create-cluster`](pcluster.create-cluster-v3.md) \$1 [`dcv-connect`](pcluster.dcv-connect-v3.md) \$1 [`delete-cluster`](pcluster.delete-cluster-v3.md) \$1 [`delete-cluster-instances`](pcluster.delete-cluster-instances-v3.md) \$1 [`delete-image`](pcluster.delete-image-v3.md) \$1 [`describe-cluster`](pcluster.describe-cluster-v3.md) \$1 [`describe-cluster-instances`](pcluster.describe-cluster-instances-v3.md) \$1 [`describe-compute-fleet`](pcluster.describe-compute-fleet-v3.md) \$1 [`describe-image`](pcluster.describe-image-v3.md) \$1 [`export-cluster-logs`](pcluster.export-cluster-logs-v3.md) \$1 [`export-image-logs`](pcluster.export-image-logs-v3.md) \$1 [`get-cluster-log-events`](pcluster.get-cluster-log-events-v3.md) \$1 [`get-cluster-stack-events`](pcluster.get-cluster-stack-events-v3.md) \$1 [`get-image-log-events`](pcluster.get-image-log-events-v3.md) \$1 [`get-image-stack-events`](pcluster.get-image-stack-events-v3.md) \$1 [`list-clusters`](pcluster.list-clusters-v3.md) \$1 [`list-cluster-log-streams`](pcluster.list-cluster-log-streams-v3.md) \$1 [`list-images`](pcluster.list-images-v3.md) \$1 [`list-image-log-streams`](pcluster.list-image-log-streams-v3.md) \$1 [`list-official-images`](pcluster.list-official-images-v3.md) \$1 [`ssh`](pcluster.ssh-v3.md) \$1 [`update-cluster`](pcluster.update-cluster-v3.md) \$1 [`update-compute-fleet`](pcluster.update-compute-fleet-v3.md) \$1 [`version`](pcluster.version-v3.md)

**Sub-commands:**

**Topics**
+ [

## Arguments
](#pcluster.arguments-v3)
+ [

# `pcluster build-image`
](pcluster.build-image-v3.md)
+ [

# `pcluster configure`
](pcluster.configure-v3.md)
+ [

# `pcluster create-cluster`
](pcluster.create-cluster-v3.md)
+ [

# `pcluster dcv-connect`
](pcluster.dcv-connect-v3.md)
+ [

# `pcluster delete-cluster`
](pcluster.delete-cluster-v3.md)
+ [

# `pcluster delete-cluster-instances`
](pcluster.delete-cluster-instances-v3.md)
+ [

# `pcluster delete-image`
](pcluster.delete-image-v3.md)
+ [

# `pcluster describe-cluster`
](pcluster.describe-cluster-v3.md)
+ [

# `pcluster describe-cluster-instances`
](pcluster.describe-cluster-instances-v3.md)
+ [

# `pcluster describe-compute-fleet`
](pcluster.describe-compute-fleet-v3.md)
+ [

# `pcluster describe-image`
](pcluster.describe-image-v3.md)
+ [

# `pcluster export-cluster-logs`
](pcluster.export-cluster-logs-v3.md)
+ [

# `pcluster export-image-logs`
](pcluster.export-image-logs-v3.md)
+ [

# `pcluster get-cluster-log-events`
](pcluster.get-cluster-log-events-v3.md)
+ [

# `pcluster get-cluster-stack-events`
](pcluster.get-cluster-stack-events-v3.md)
+ [

# `pcluster get-image-log-events`
](pcluster.get-image-log-events-v3.md)
+ [

# `pcluster get-image-stack-events`
](pcluster.get-image-stack-events-v3.md)
+ [

# `pcluster list-clusters`
](pcluster.list-clusters-v3.md)
+ [

# `pcluster list-cluster-log-streams`
](pcluster.list-cluster-log-streams-v3.md)
+ [

# `pcluster list-images`
](pcluster.list-images-v3.md)
+ [

# `pcluster list-image-log-streams`
](pcluster.list-image-log-streams-v3.md)
+ [

# `pcluster list-official-images`
](pcluster.list-official-images-v3.md)
+ [

# `pcluster ssh`
](pcluster.ssh-v3.md)
+ [

# `pcluster update-cluster`
](pcluster.update-cluster-v3.md)
+ [

# `pcluster update-compute-fleet`
](pcluster.update-compute-fleet-v3.md)
+ [

# `pcluster version`
](pcluster.version-v3.md)

# `pcluster build-image`


Create a custom Amazon ParallelCluster image in the specified Region.

```
pcluster build-image [-h]
                 --image-configuration IMAGE_CONFIGURATION 
                 --image-id IMAGE_ID
                [--debug]
                [--dryrun DRYRUN]
                [--query QUERY]
                [--region REGION]
                [--rollback-on-failure ROLLBACK_ON_FAILURE]
                [--suppress-validators SUPPRESS_VALIDATORS [SUPPRESS_VALIDATORS ...]]
                [--validation-failure-level {INFO,WARNING,ERROR}]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster build-image`.

**--image-configuration, -c *IMAGE\$1CONFIGURATION***  
Specifies the image configuration file as a YAML document.

**--image-id, -i *IMAGE\$1ID***  
Specifies the id of the image that will be built.

**--debug**  
Turn on debug logging.

**--dryrun *DRYRUN***  
When `true`, the command performs validation without creating any resources. You can use this to validate the image configuration. (Defaults to `false`.)

**--query *QUERY***  
JMESPath query to perform on output.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Amazon Web Services Region must be specified, using the [Region](image-builder-configuration-file-v3.md#yaml-build-image-Region) setting in the image configuration file, the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

**--rollback-on-failure *ROLLBACK\$1ON\$1FAILURE***  
When `true`, automatically initiates an image stack rollback on failure. (Defaults to `false`.)

**--suppress-validators * SUPPRESS\$1VALIDATORS* [*SUPPRESS\$1VALIDATORS ...*]**  
Identifies one or more config validators to suppress.  
Format: (`ALL`\$1`type:[A-Za-z0-9]+`)

**--validation-failure-level \$1`INFO`,`WARNING`,`ERROR`\$1**  
Specifies the minimum validation level that will cause the creation to fail. (Defaults to `ERROR`.)

**Example using Amazon ParallelCluster version 3.1.2:**

```
$ pcluster build-image --image-configuration image-config.yaml --image-id custom-alinux2-image
{
  "image": {
    "imageId": "custom-alinux2-image",
    "imageBuildStatus": "BUILD_IN_PROGRESS",
    "cloudformationStackStatus": "CREATE_IN_PROGRESS",
    "cloudformationStackArn": "arn:aws:cloudformation:us-east-1:123456789012:stack/custom-alinux2-image/1234abcd-56ef-78gh-90ij-abcd1234efgh",
    "region": "us-east-1",
    "version": "3.1.2"
  }
}
```

**Warning**  
`pcluster build-image` uses the default VPC. If the default VPC has been deleted, perhaps by using Amazon Control Tower or Amazon Landing Zone, then the subnet ID must be specified in the image configuration file. For more information, see [SubnetId](HeadNode-v3.md#yaml-HeadNode-Networking-SubnetId).

# `pcluster configure`


Begins an interactive configuration wizard for Amazon ParallelCluster version 3. For more information, see [Configure and create a cluster with the Amazon ParallelCluster command line interface](install-v3-configuring.md).

```
pcluster configure [-h]
                 --config CONFIG
                [--debug]
                [--region REGION]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster configure`.

**--config *CONFIG***  
Path to output the generated config file.

**--debug**  
Turn on debug logging.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Region must be specified, using the [Region](image-builder-configuration-file-v3.md#yaml-build-image-Region) setting in the image configuration file, the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

# `pcluster create-cluster`


Creates an Amazon ParallelCluster cluster.

```
pcluster create-cluster [-h]
                 --cluster-configuration CLUSTER_CONFIGURATION
                 --cluster-name CLUSTER_NAME
                [--debug]
                [--dryrun DRYRUN]   
                [--query QUERY]
                [--region REGION]
                [--rollback-on-failure ROLLBACK_ON_FAILURE]
                [--suppress-validators SUPPRESS_VALIDATORS [SUPPRESS_VALIDATORS ...]]                        
                [--validation-failure-level {INFO,WARNING,ERROR}]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster create-cluster`.

**--cluster-configuration, -c *CLUSTER\$1CONFIGURATION***  
Specifies the YAML cluster configuration file.

**--cluster-name, -n *CLUSTER\$1NAME***  
Specifies the name of the cluster to be created.  
The name must start with an alphabetical character. The name can have up to 60 characters. If Slurm accounting is enabled, the name can have up to 40 characters.  
Valid characters: a-z, A-Z, 0-9, and - (hyphen).

**--debug**  
Enables debug logging.

**--dryrun *DRYRUN***  
When `true`, the command performs validation without creating any resources. You can use this to validate the cluster configuration. (Defaults to `false`.)

**--query *QUERY***  
Specifies the JMESPath query to perform on the output.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Amazon Web Services Region must be specified, using the [`Region`](cluster-configuration-file-v3.md#yaml-Region) setting in the cluster configuration file, the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

**--rollback-on-failure *ROLLBACK\$1ON\$1FAILURE***  
When `true`, automatically initiates a cluster stack rollback on failures. (Defaults to `true`.)

**--suppress-validators *SUPPRESS\$1VALIDATORS* [*SUPPRESS\$1VALIDATORS* ...]**  
Identifies one or more config validators to suppress.  
 Format: (`ALL`\$1type:`[A-Za-z0-9]+`)

**--validation-failure-level \$1`INFO`,`WARNING`,`ERROR`\$1**  
Specifies the minimum validation level that will cause the creation to fail. (Defaults to `ERROR`.)

**Example using Amazon ParallelCluster version 3.1.4:**

```
$ pcluster create-cluster -c cluster-config.yaml -n cluster-v3
{
  "cluster": {
    "clusterName": "cluster-v3",
    "cloudformationStackStatus": "CREATE_IN_PROGRESS",
    "cloudformationStackArn": "arn:aws:cloudformation:us-east-1:123456789012:stack/cluster-v3/1234abcd-56ef-78gh-90ij-abcd1234efgh",
    "region": "us-east-1",
    "version": "3.1.4",
    "clusterStatus": "CREATE_IN_PROGRESS"
  }
}
```

# `pcluster dcv-connect`


Permits to connect to the head node through an interactive session by using Amazon DCV.

```
pcluster dcv-connect [-h]
                 --cluster-name CLUSTER_NAME 
                [--debug]
                [--key-path KEY_PATH]
                [--login-node-ip LOGIN_NODE_IP]
                [--region REGION]
                [--show-url]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster dcv-connect`.

**--cluster-name, -n *CLUSTER\$1NAME***  
Specifies the name of the cluster.

**--debug**  
Enables debug logging.

**--key-path *KEY\$1PATH***  
Specifies the path of the SSH key to use for the connection.

**--login-node-ip**  
Specifies the public or private IP address of a login node in the cluster. Using this argument allows connection to a login node in the cluster with DCV enabled.  
This argument is added in Amazon ParallelCluster version 3.11.0.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Amazon Web Services Region must be specified, using the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

**--show-url**  
Prints the URL that would be used for the DCV connection and exits.

**Example using Amazon ParallelCluster version 3.11**

```
$ pcluster dcv-connect -n cluster-3Dcv --login-node-ip 198.51.100.44 -r us-east-1 --key-path /home/user/.ssh/key.pem
```

 ![\[A screenshot of the DCV console.\]](http://docs.amazonaws.cn/en_us/parallelcluster/latest/ug/images/Dcv-image.png) 

# `pcluster delete-cluster`


Starts the deletion of a cluster.

```
pcluster delete-cluster [-h] 
                 --cluster-name CLUSTER_NAME
                [--debug]
                [--query QUERY]
                [--region REGION]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster delete-cluster`.

**--cluster-name, -n *CLUSTER\$1NAME***  
Specifies the name of the cluster.

**--debug**  
Enables debug logging.

**--query *QUERY***  
Specifies the JMESPath query to perform on the output.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Region must be specified, using the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

**Example using Amazon ParallelCluster version 3.1.4:**

```
$ pcluster delete-cluster -n cluster-v3
   {
  "cluster": {
    "clusterName": "cluster-v3",
    "cloudformationStackStatus": "DELETE_IN_PROGRESS",
    "cloudformationStackArn": "arn:aws:cloudformation:us-east-1:123456789012:stack/cluster-v3/1234abcd-56ef-78gh-90ij-abcd1234efgh",
    "region": "us-east-1",
    "version": "3.1.4",
    "clusterStatus": "DELETE_IN_PROGRESS"
  }
}
```

# `pcluster delete-cluster-instances`


Initiate the forced termination of all cluster compute nodes. This does not work with Amazon Batch clusters.

```
pcluster delete-cluster-instances [-h] 
                 --cluster-name CLUSTER_NAME
                [--debug]
                [--force FORCE]
                [--query QUERY]
                [--region REGION]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster delete-cluster-instances`.

**--cluster-name, -n *CLUSTER\$1NAME***  
Specifies the name of the cluster.

**--debug**  
Enables debug logging.

**--force *FORCE***  
When `true`, forces the deletion by ignoring validation errors. (Defaults to `false`.)

**--query *QUERY***  
Specifies the JMESPath query to perform on the output.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Amazon Web Services Region must be specified, using the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

```
$ pcluster delete-cluster-instances -n cluster-v3
```

# `pcluster delete-image`


Starts the deletion of the custom Amazon ParallelCluster image.

```
pcluster delete-image [-h] 
                 --image-id IMAGE_ID
                [--debug]
                [--force FORCE]
                [--query QUERY]
                [--region REGION]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster delete-image`.

**--image-id, -i *IMAGE\$1ID***  
Specifies the id of the image that will be deleted.

**--debug**  
Enables debug logging.

**--force *FORCE***  
When `true`, forces the deletion in case there are instances using the AMI or if the AMI is shared. (Defaults to `false`.)

**--query *QUERY***  
Specifies the JMESPath query to perform on the output.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Amazon Web Services Region must be specified, using the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

**Example using Amazon ParallelCluster version 3.1.4:**

```
$ pcluster delete-image --image-id custom-alinux2-image
{
  "image": {
    "imageId": "custom-alinux2-image",
    "imageBuildStatus": "DELETE_IN_PROGRESS",
    "region": "us-east-1",
    "version": "3.1.4"
  }
}
```

# `pcluster describe-cluster`


Get detailed information about a cluster.

```
pcluster describe-cluster [-h] 
                 --cluster-name CLUSTER_NAME
                [--debug]
                [--query QUERY]
                [--region REGION]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster describe-cluster`.

**--cluster-name, -n *CLUSTER\$1NAME***  
Specifies the name of the cluster.

**--debug**  
Enables debug logging.

**--query *QUERY***  
Specifies the JMESPath query to perform on the output.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Amazon Web Services Region must be specified, using the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

**Examples using Amazon ParallelCluster version 3.1.4:**

Describe cluster details:

```
$ pcluster describe-cluster -n cluster-v3
{
  "creationTime": "2022-07-12T17:19:16.101Z",
  "headNode": {
    "launchTime": "2022-07-12T17:22:21.000Z",
    "instanceId": "i-1234567890abcdef0",
    "publicIpAddress": "198.51.100.44",
    "instanceType": "t2.micro",
    "state": "running",
    "privateIpAddress": "192.0.2.0.196"
  },
  "loginNodes": [
      {
          "status": "active",
          "poolName": "pool1",
          "address": "cluster-v3-eMr9BYRKZVDa-e5bb34f40b24f51d.elb.us-east-1.amazonaws.com",
          "scheme": "internet-facing",
          "healthyNodes": 1,
          "unhealthyNodes": 0
      },
      {
          "status": "active",
          "poolName": "pool2",
          "address": "cluster-v3-PaQ7GgC27sic-aba10c890247b36b.elb.us-east-1.amazonaws.com",
          "scheme": "internet-facing",
          "healthyNodes": 1,
          "unhealthyNodes": 0
      }
  ],
  "version": "3.1.4",
  "clusterConfiguration": {
    "url": "https://parallelcluster-e5ca74255d6c3886-v1-do-not-delete..."
  },
  "tags": [
    {
      "value": "3.11",
      "key": "parallelcluster:version"
    }
  ],
  "cloudFormationStackStatus": "CREATE_COMPLETE",
  "clusterName": "cluster-v3",
  "computeFleetStatus": "RUNNING",
  "cloudformationStackArn": "arn:aws:cloudformation:us-east-1:123456789012:stack/cluster-v3/1234abcd-56ef-78gh-90ij-abcd1234efgh",
  "lastUpdatedTime": "2022-07-12T17:19:16.101Z",
  "region": "us-east-1",
  "clusterStatus": "CREATE_COMPLETE"
}
```

Use `describe-cluster` to retrieve the cluster configuration:

```
$ curl -o - $(pcluster describe-cluster -n cluster-v3 --query clusterConfiguration.url | xargs echo)
Region: us-east-1
Image:
  Os: alinux2
HeadNode:
  InstanceType: t2.micro
  Networking:
    SubnetId: subnet-abcdef01234567890
  Ssh:
    KeyName: adpc
  Iam:
    S3Access:
      - BucketName: cluster-v3-bucket
        KeyName: logs
        EnableWriteAccess: true
Scheduling:
  Scheduler: slurm
  SlurmQueues:
  - Name: queue1
    ComputeResources:
    - Name: t2micro
      InstanceType: t2.micro
      MinCount: 0
      MaxCount: 10
    Networking:
      SubnetIds:
      - subnet-021345abcdef6789
```

# `pcluster describe-cluster-instances`


Describe the instances in a cluster.

```
pcluster describe-cluster-instances [-h] 
                 --cluster-name CLUSTER_NAME
                [--debug]
                [--next-token NEXT_TOKEN]
                [--node-type {HeadNode,ComputeNode,LoginNode}]
                [--query QUERY]
                [--queue-name QUEUE_NAME]
                [--region REGION]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster describe-cluster-instances`.

**--cluster-name, -n *CLUSTER\$1NAME***  
Specifies the name of the cluster.

**--debug**  
Enables debug logging.

**--next-token *NEXT\$1TOKEN***  
The token for the next set of results.

**--node-type \$1`HeadNode`,`ComputeNode`,`LoginNode`\$1**  
Specifies the node types to list. Supported values are `HeadNode`, `ComputeNode` and `LoginNode`. If this parameter is not specified, the `HeadNode`, `ComputeNode` and `LoginNode`a instances are described.

**--query *QUERY***  
Specifies the JMESPath query to perform on the output.

**--queue-name *QUEUE\$1NAME***  
Specifies the name of the queue to list. If this parameter is not specified, instances in all queues are described.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Amazon Web Services Region must be specified, using the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

**Example using Amazon ParallelCluster version 3.1.4:**

```
$ pcluster describe-cluster-instances -n cluster-v3
{
  "instances": [
    {
      "launchTime": "2022-07-12T17:22:21.000Z",
      "instanceId": "i-1234567890abcdef0",
      "publicIpAddress": "198.51.100.44",
      "instanceType": "t2.micro",
      "state": "running",
      "nodeType": "HeadNode",
      "privateIpAddress": "192.0.2.0.196"
    },
    {
      "launchTime": "2022-07-12T17:37:42.000Z",
      "instanceId": "i-021345abcdef6789",
      "queueName": "queue1",
      "publicIpAddress": "198.51.100.44",
      "instanceType": "t2.micro",
      "state": "pending",
      "nodeType": "ComputeNode",
      "privateIpAddress": "192.0.2.0.196"
    },
    {
        "launchTime": "2022-07-12T17:37:42.000Z", 
        "instanceId": "i-021345abcdef6789", 
        "poolName": "pool1", 
        "publicIpAddress": "198.51.100.44", 
        "instanceType": "t2.micro", 
        "state": "pending", 
        "nodeType": "loginNode", 
        "privateIpAddress": "192.0.2.0.196" 
    }
  ]
}
```

# `pcluster describe-compute-fleet`


Describe the status of the compute fleet.

```
pcluster describe-compute-fleet [-h] 
                 --cluster-name CLUSTER_NAME
                [--debug]
                [--query QUERY]
                [--region REGION]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster describe-compute-fleet`.

**--cluster-name, -n *CLUSTER\$1NAME***  
Specifies the name of the cluster.

**--debug**  
Enables debug logging.

**--query *QUERY***  
Specifies the JMESPath query to perform on the output.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Amazon Web Services Region must be specified, using the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

**Example using Amazon ParallelCluster version 3.1.4:**

```
$ pcluster describe-compute-fleet -n pcluster-v3
{
  "status": "RUNNING",
  "lastStatusUpdatedTime": "2022-07-12T17:24:26.000Z"
}
```

# `pcluster describe-image`


Get detailed information about an image.

```
pcluster describe-image [-h] 
                 --image-id IMAGE_ID
                [--debug] 
                [--query QUERY]
                [--region REGION]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster describe-image`.

**--image-id, -i *IMAGE\$1ID***  
Specifies the ID of the image.

**--debug**  
Enables debug logging.

**--query *QUERY***  
Specifies the JMESPath query to perform on the output.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Amazon Web Services Region must be specified, using the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

**Example using Amazon ParallelCluster version 3.1.2:**

```
$ pcluster describe-image --image-id custom-alinux2-image
{  
  "imageConfiguration: {    
    "url": "https://parallelcluster-1234abcd5678-v1-do-not-delete.../configs/image-config.yaml"
  },
  "imageId": "custom-alinux2-image",
  "creationTime": "2022-04-05T20:23:07.000Z"
  "imageBuildStatus": "BUILD_COMPLETE", 
  "region": "us-east-1",
  "ec2AmiInfo": {
    "amiName": "custom-alinux2-image 2022-04-05T19-55-22.518Z",
    "amiId": "ami-1234abcd5678efgh",
    "description": "Amazon ParallelCluster AMI for alinux2, kernel-4.14.268-205.500.amzn2.x86_64, lustre-2.10.8-5.amzn2.x86_64, efa-1.14.2-1.amzn2.x86_64, dcv-2021.3.11591-1.el7.x86_64, slurm-21-08-6-1",
    "state": "AVAILABLE",
  "tags": [
      {
        "value": "arn:aws:imagebuilder:us-east-1:123456789012:image/parallelclusterimage-custom-alinux2-image/3.1.2/1",
        "key": "Ec2ImageBuilderArn"
      },
      {
        "value": "parallelcluster-1234abcd5678efgh-v1-do-not-delete",
        "key": "parallelcluster:amzn-s3-demo-bucket"
      },
      {
        "value": "custom-alinux2-image",
        "key": "parallelcluster:image_name"
      },
      {
        "value": "available",
        "key": "parallelcluster:build_status"
      },
      {
        "value": "s3://amzn-s3-demo-bucket/parallelcluster/3.1.2/images/custom-alinux2-image-1234abcd5678efgh/configs/image-config.yaml",
        "key": "parallelcluster:build_config"
      },
      {
        "value": "Amazon EC2 Image Builder",
        "key": "CreatedBy"
      },
      {
        "value": "arn:aws:logs:us-east-1:123456789012:log-group:/aws/imagebuilder/ParallelClusterImage-custom-alinux2-image",
        "key": "parallelcluster:build_log"
      },
      {
        "value": "4.14.268-205.500.amzn2.x86_64",
        "key": "parallelcluster:kernel_version"
      },
      {
        "value": "arn:aws:imagebuilder:us-east-1:444455556666:image/amazon-linux-2-x86/2022.3.16/1",
        "key": "parallelcluster:parent_image"
      },
      {
        "value": "3.1.2",
        "key": "parallelcluster:version"
      },
      {
        "value": "0.5.14",
        "key": "parallelcluster:munge_version"
      },
      {
        "value": "21-08-6-1",
        "key": "parallelcluster:slurm_version"
      },
      {
        "value": "2021.3.11591-1.el7.x86_64",
        "key": "parallelcluster:dcv_version"
      },
      {
        "value": "alinux2-image",
        "key": "parallelcluster:image_id"
      },
      {
        "value": "3.2.3",
        "key": "parallelcluster:pmix_version"
      },
      {
        "value": "parallelcluster/3.15.0/images/alinux2-image-abcd1234efgh56781234",
        "key": "parallelcluster:s3_image_dir"
      },
      {
        "value": "1.14.2-1.amzn2.x86_64",
        "key": "parallelcluster:efa_version"
      },
      {
        "value": "alinux2",
        "key": "parallelcluster:os"
      },
      {
        "value": "aws-parallelcluster-cookbook-3.1.2",
        "key": "parallelcluster:bootstrap_file"
      },
      {
        "value": "1.8.23-10.amzn2.1.x86_64",
        "key": "parallelcluster:sudo_version"
      },
      {
        "value": "2.10.8-5.amzn2.x86_64",
        "key": "parallelcluster:lustre_version"
      }
    ],
    "architecture": "x86_64"
  },
  "version": "3.1.2"
}
```

# `pcluster export-cluster-logs`


Export the logs of the cluster to a local `tar.gz` archive by passing through an Amazon S3 Bucket.

```
pcluster export-cluster-logs [-h]
                 --cluster-name CLUSTER_NAME
                [--bucket BUCKET_NAME]
                [--bucket-prefix BUCKET_PREFIX]
                [--debug]
                [--end-time END_TIME]
                [--filters FILTER [FILTER ...]]
                [--keep-s3-objects KEEP_S3_OBJECTS]
                [--output-file OUTPUT_FILE]
                [--region REGION]
                [--start-time START_TIME]
```

**Note**  
The `export-cluster-logs` command waits for CloudWatch Logs to complete the export of logs, so it is expected to experience a period of time without any output.

## Named arguments


**-h, --help**  
Shows the help text for `pcluster export-cluster-logs`.

**--bucket *BUCKET\$1NAME***  
Specifies the name of the Amazon S3 bucket to export cluster logs data to. It must be in the same Region as the cluster.  
+ You must add permissions to the Amazon S3 bucket policy to grant CloudWatch access. For more information, see [ Set permissions on an Amazon S3 bucket](https://docs.amazonaws.cn/AmazonCloudWatch/latest/logs/S3ExportTasks.html#S3Permissions) in the *CloudWatch Logs User Guide*.
+ Starting with Amazon ParallelCluster version **3.12.0**, the `--bucket` option is **optional**. If the option is not specified, either the Amazon ParallelCluster regional default bucket (`parallelcluster-hash-v1-DO-NOT-DELETE`) will be used, or if the Amazon S3 bucket pointed to by `CustomS3Bucket` is specified in the cluster configuration, that will be used. If you do not specify the `--bucket` option and you use the default Amazon ParallelCluster bucket, you cannot export logs to the `parallelcluster/` folder, because it is a protected folder reserved for internal use.
If the Amazon ParallelCluster default bucket is used, pcluster will take care of configuring the bucket policy. If you customized the bucket policy and then upgrade to Amazon ParallelCluster version **3.12.0**, the bucket policy will be overridden and you will need to reapply your changes.

**--cluster-name, -n *CLUSTER\$1NAME***  
Specifies the name of the cluster.

**--bucket-prefix *BUCKET\$1PREFIX***  
Specifies the path in the Amazon S3 bucket where exported logs data is to be stored.  
By default, the bucket-prefix is:  

```
cluster-name-logs-202209061743.tar.gz
```
`202209061743` is an example of the time in `%Y%m%d%H%M` format.  
Starting with Amazon ParallelCluster version **3.12.0**, if you don't specify the `--bucket` option and you use the default Amazon ParallelCluster bucket, you cannot export logs to the `parallelcluster/` folder, because it is a protected folder reserved for internal use.

**--debug**  
Enables debug logging.

**--end-time *END\$1TIME***  
Specifies the end of the time range to collect log events, expressed in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`, for example `2021-01-01T20:00:00Z`'). Events with a timestamp equal to or later than this time are not included. Time elements (e.g. minutes and seconds) may be omitted. The default value is the current time.

**--filters *FILTER* [*FILTER* ...]**  
Specifies filters for the log. Format: `Name=a,Values=1 Name=b,Values=2,3`. Supported filters are:    
`private-dns-name`  
Specifies the short form of the private DNS name of the instance (e.g. `ip-10-0-0-101`).  
`node-type`  
Specifies the node type, the only accepted value for this filter is `HeadNode`.

**--keep-s3-objects *KEEP\$1S3\$1OBJECTS***  
If `true`, the exported objects exports to Amazon S3 are kept. (Defaults to `false`.)

**--output-file *OUTPUT\$1FILE***  
Specifies the file path to save the log archive to. If this is provided, then the logs are saved locally. Otherwise they are uploaded to Amazon S3 with the URL returned in the output. Default is to upload to Amazon S3.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Amazon Web Services Region must be specified, using the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

**--start-time *START\$1TIME***  
Specifies the start of the time range, expressed in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`, for example `2021-01-01T20:00:00Z`). Log events with a timestamp equal to this time or later than this time are included. If not specified, the default is the time the cluster was created.

**Example using Amazon ParallelCluster version 3.1.4:**

```
$ pcluster export-cluster-logs --bucket cluster-v3-bucket -n cluster-v3
{
  "url": "https://cluster-v3-bucket..."
}
```

## Cannot retrieve the logs?


If you cannot retrieve the logs using the `export-cluster-logs` command, then do one of the following:
+ Retrieve the logs manually from the CloudWatch log group of the cluster.
+ If the log group is empty, SSH into cluster nodes and retrieve the logs listed in [Troubleshooting node initialization issues](troubleshooting-v3-scaling-issues.md#troubleshooting-v3-node-init).
+ If cluster nodes are not accessible because the cluster failed to create, then recreate the cluster with option `--rollback-on-failure false` and retrieve the logs from the nodes.

# `pcluster export-image-logs`


Export the logs of the image builder stack to a local `tar.gz` archive by passing through an Amazon S3 Bucket.

```
pcluster export-image-logs [-h]
                 --image-id IMAGE_ID
                [--bucket BUCKET]
                [--bucket-prefix BUCKET_PREFIX]
                [--debug]                         
                [--end-time END_TIME]
                [--keep-s3-objects KEEP_S3_OBJECTS]
                [--output-file OUTPUT_FILE]
                [--region REGION]
                [--start-time START_TIME]
```

**Note**  
The `export-image-logs` command waits for CloudWatch Logs to complete the export of logs, so it is expected to experience a period of time without any output.

## Named arguments


**-h, --help**  
Shows the help text for `pcluster export-image-logs`.

**--bucket *BUCKET\$1NAME***  
Specifies the Amazon S3 bucket name to export image build logs to. It must be in the same Region as the image.  
+ You must add permissions to the Amazon S3 bucket policy to grant CloudWatch access. For more information, see [ Set permissions on an Amazon S3 bucket](https://docs.amazonaws.cn/AmazonCloudWatch/latest/logs/S3ExportTasks.html#S3Permissions) in the *CloudWatch Logs User Guide*.
+ Starting with Amazon ParallelCluster version **3.12.0**, the `--bucket` option is **optional**. If the option is not specified, either the Amazon ParallelCluster regional default bucket (`parallelcluster-hash-v1-DO-NOT-DELETE`) will be used, or if the `CustomS3Bucket` is specified in the image configuration, that will be used.
If the Amazon ParallelCluster default bucket is used, pcluster will take care of configuring the bucket policy. If you customize the bucket policy before you upgrade to Amazon ParallelCluster version **3.12.0**, the bucket policy will be overridden and you will need to reapply the changes.

**--image-id, -i *IMAGE\$1ID***  
The image ID whose logs will be exported.

**--bucket-prefix *BUCKET\$1PREFIX***  
Specifies the path in the Amazon S3 bucket where exported logs data is to be stored.  
By default, the bucket-prefix is:  

```
ami-id-logs-202209061743.tar.gz
```
`202209061743` is the current time in `%Y%m%d%H%M` format.  
Starting with Amazon ParallelCluster version **3.12.0**, if you don't specify the `--bucket` option and use the default Amazon ParallelCluster bucket, you cannot export logs to the `parallelcluster/` folder, because it is a protected folder reserved for internal use.

**--debug**  
Enables debug logging.

**--end-time *END\$1TIME***  
Specifies the end of the time range to collect log events, expressed in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`, for example `2021-01-01T20:00:00Z`'). Events with a timestamp equal to or later than this time are not included. Time elements (e.g. minutes and seconds) may be omitted. The default value is the current time.

**--keep-s3-objects *KEEP\$1S3\$1OBJECTS***  
If `true`, the exported objects exports to Amazon S3 are kept. (Defaults to `false`.)

**--output-file *OUTPUT\$1FILE***  
Specifies the file path to save the log archive to. If this is provided, then the logs are saved locally. Otherwise they are uploaded to Amazon S3 with the URL returned in the output. Default is to upload to Amazon S3.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Amazon Web Services Region must be specified, using the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

**--start-time *START\$1TIME***  
Specifies the start of the time range, expressed in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`, for example `2021-01-01T20:00:00Z`). Log events with a timestamp equal to this time or later than this time are included. If not specified, the default is the time the cluster was created.

**Example using Amazon ParallelCluster version 3.1.4:**

```
$ pcluster export-image-logs --bucket image-v3-bucket --image-id ami-1234abcd5678efgh
{
  "url": "https://image-v3-bucket..."
}
```

# `pcluster get-cluster-log-events`


Retrieve the events associated with a log stream.

```
pcluster get-cluster-log-events [-h] 
                 --cluster-name CLUSTER_NAME
                 --log-stream-name LOG_STREAM_NAME
                [--debug]
                [--end-time END_TIME]
                [--limit LIMIT]
                [--next-token NEXT_TOKEN]
                [--query QUERY]
                [--region REGION]
                [--start-from-head START_FROM_HEAD]                                
                [--start-time START_TIME]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster get-cluster-log-events`.

**--cluster-name, -n *CLUSTER\$1NAME***  
Specifies the name of the cluster.

**--log-stream-name *LOG\$1STREAM\$1NAME***  
Specifies the name of the log stream. You can use the `list-cluster-log-streams` command to retrieve a log stream associated with an event or events.

**--debug**  
Enables debug logging.

**--end-time *END\$1TIME***  
Specifies the end of the time range, expressed in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`, for example `2021-01-01T20:00:00Z`). Events with a timestamp equal to or later than this time are not included.

**--limit *LIMIT***  
Specifies the maximum number of log events returned. If a value is not specified, the maximum is as many log events as can fit in a response size of 1 MB, up to 10,000 log events.

**--next-token *NEXT\$1TOKEN***  
The token for the next set of results.

**--query *QUERY***  
Specifies the JMESPath query to perform on the output.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Amazon Web Services Region must be specified, using the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

**--start-from-head *START\$1FROM\$1HEAD***  
If the value is `true`, the earliest log events are returned first. If the value is `false`, the most recent log events are returned first. (Defaults to `false`.)

**--start-time *START\$1TIME***  
Specifies the start of the time range, expressed in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`, for example `2021-01-01T20:00:00Z`). Events with a timestamp equal to this time or later than this time are included.

**Example using Amazon ParallelCluster version 3.1.4:**

```
$ pcluster get-cluster-log-events \
    -c cluster-v3 \
    -r us-east-1 \
    --log-stream-name ip-198-51-100-44.i-1234567890abcdef0.clustermgtd \
    --limit 3
{
  "nextToken": "f/36966906399261933213029082268132291405859205452101451780/s",
  "prevToken": "b/36966906399239632467830551644990755687586557090595471362/s",
  "events": [
    {
      "message": "2022-07-12 19:16:53,379 - [slurm_plugin.clustermgtd:_maintain_nodes] - INFO - Performing node maintenance actions",
      "timestamp": "2022-07-12T19:16:53.379Z"
    },
    {
      "message": "2022-07-12 19:16:53,380 - [slurm_plugin.clustermgtd:_maintain_nodes] - INFO - Following nodes are currently in replacement: (x0) []",
      "timestamp": "2022-07-12T19:16:53.380Z"
    },
    {
      "message": "2022-07-12 19:16:53,380 - [slurm_plugin.clustermgtd:_terminate_orphaned_instances] - INFO - Checking for orphaned instance",
      "timestamp": "2022-07-12T19:16:53.380Z"
    }
  ]
}
```

# `pcluster get-cluster-stack-events`


Retrieve the events associated with the stack for the specified cluster.

**Note**  
Starting in version 3.6.0, Amazon ParallelCluster uses nested stacks to create the resources associated with queues and compute resources. The `GetClusterStackEvents` API and the `pcluster get-cluster-stack-events` command only return the cluster main stack events. You can view the cluster stack events, including those related to queues and compute resources, in the CloudFormation console.

```
pcluster get-cluster-stack-events [-h] 
                 --cluster-name CLUSTER_NAME
                [--debug]
                [--next-token NEXT_TOKEN]
                [--query QUERY]
                [--region REGION]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster get-cluster-stack-events`.

**--cluster-name, -n *CLUSTER\$1NAME***  
Specifies the name of the cluster.

**--debug**  
Enables debug logging.

**--next-token *NEXT\$1TOKEN***  
The token for the next set of results.

**--query *QUERY***  
Specifies the JMESPath query to perform on the output.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Amazon Web Services Region must be specified, using the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

**Example using Amazon ParallelCluster version 3.1.4:**

```
$ pcluster get-cluster-stack-events \
    -n cluster-v3 \
    -r us-east-1 \
    --query "events[0]"
{
  "eventId": "1234abcd-56ef-78gh-90ij-abcd1234efgh",
  "physicalResourceId": "arn:aws:cloudformation:us-east-1:123456789012:stack/cluster-v3/1234abcd-56ef-78gh-90ij-abcd1234efgh",
  "resourceStatus": "CREATE_COMPLETE",
  "stackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/cluster-v3/1234abcd-56ef-78gh-90ij-abcd1234efgh",
  "stackName": "cluster-v3",
  "logicalResourceId": "cluster-v3",
  "resourceType": "AWS::CloudFormation::Stack",
  "timestamp": "2022-07-12T18:29:12.140Z"
}
```

# `pcluster get-image-log-events`


Retrieve the log events associated with an image build.

```
pcluster get-image-log-events [-h] 
                 --image-id IMAGE_ID                               
                 --log-stream-name LOG_STREAM_NAME
                [--debug]
                [--end-time END_TIME]
                [--limit LIMIT]
                [--next-token NEXT_TOKEN]                              
                [--query QUERY]                               
                [--region REGION]                              
                [--start-from-head START_FROM_HEAD]
                [--start-time START_TIME]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster get-image-log-events`.

**--image-id, -i *IMAGE\$1ID***  
Specifies the Id of the image.

**--log-stream-name *LOG\$1STREAM\$1NAME***  
Specifies the name of the log stream. You can use the `list-image-log-streams` command to retrieve a log stream associated with an event or events.

**--debug**  
Enables debug logging.

**--end-time *END\$1TIME***  
Specifies the end of the time range, expressed in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`, for example `2021-01-01T20:00:00Z`). Events with a timestamp equal to or later than this time are not included.

**--limit *LIMIT***  
Specifies the maximum number of log events returned. If a value is not specified, the maximum is as many log events as can fit in a response size of 1 MB, up to 10,000 log events.

**--next-token *NEXT\$1TOKEN***  
The token for the next set of results.

**--query *QUERY***  
Specifies the JMESPath query to perform on the output.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Amazon Web Services Region must be specified, using the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

**--start-from-head *START\$1FROM\$1HEAD***  
If the value is `true`, the earliest log events are returned first. If the value is `false`, the most recent log events are returned first. (Defaults to `false`.)

**--start-time *START\$1TIME***  
Specifies the start of the time range, expressed in ISO 8601 format (`YYYY-MM-DDThh:mm:ssZ`, for example `2021-01-01T20:00:00Z`). Events with a timestamp equal to or later than this time are included.

**Example using Amazon ParallelCluster version 3.1.2:**

```
$ pcluster get-image-log-events --image-id custom-alinux2-image --region us-east-1 --log-stream-name 3.1.2/1 --limit 3
   {
  "nextToken": "f/36778317771100849897800729464621464113270312017760944178/s",
  "prevToken": "b/36778317766952911290874033560295820514557716777648586800/s",
  "events": [
    {
      "message": "ExecuteBash: FINISHED EXECUTION",
      "timestamp": "2022-04-05T22:13:26.633Z"
    },
    {
      "message": "Document arn:aws:imagebuilder:us-east-1:123456789012:component/parallelclusterimage-test-1234abcd-56ef-78gh-90ij-abcd1234efgh/3.1.2/1",
      "timestamp": "2022-04-05T22:13:26.741Z"
    },
    {
      "message": "TOE has completed execution successfully",
      "timestamp": "2022-04-05T22:13:26.819Z"
    }
  ]
}
```

# `pcluster get-image-stack-events`


Retrieve the events associated with the stack for the specified image build.

```
pcluster get-image-stack-events [-h] 
                 --image-id IMAGE_ID
                [--debug]
                [--next-token NEXT_TOKEN]
                [--query QUERY]
                [--region REGION]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster get-image-stack-events`.

**--image-id, -i *IMAGE\$1ID***  
Specifies the ID of the image.

**--debug**  
Enables debug logging.

**--next-token *NEXT\$1TOKEN***  
The token for the next set of results.

**--query *QUERY***  
Specifies the JMESPath query to perform on the output.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Amazon Web Services Region must be specified, using the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

**Example using Amazon ParallelCluster version 3.1.2:**

```
$ pcluster get-image-stack-events --image-id custom-alinux2-image --region us-east-1 --query "events[0]"
   {
  "eventId": "ParallelClusterImage-CREATE_IN_PROGRESS-2022-04-05T21:39:24.725Z",
  "physicalResourceId": "arn:aws:imagebuilder:us-east-1:123456789012:image/parallelclusterimage-custom-alinux2-image/3.1.2/1",
  "resourceStatus": "CREATE_IN_PROGRESS",
  "resourceStatusReason": "Resource creation Initiated",
  "resourceProperties": "{\"InfrastructureConfigurationArn\":\"arn:aws:imagebuilder:us-east-1:123456789012:infrastructure-configuration/parallelclusterimage-1234abcd-56ef-78gh-90ij-abcd1234efgh\",\"ImageRecipeArn\":\"arn:aws:imagebuilder:us-east-1:123456789012:image-recipe/parallelclusterimage-custom-alinux2-image/3.1.2\",\"DistributionConfigurationArn\":\"arn:aws:imagebuilder:us-east-1:123456789012:distribution-configuration/parallelclusterimage-1234abcd-56ef-78gh-90ij-abcd1234efgh\",\"EnhancedImageMetadataEnabled\":\"false\",\"Tags\":{\"parallelcluster:image_name\":\"custom-alinux2-image\",\"parallelcluster:image_id\":\"custom-alinux2-image\"}}",
  "stackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/custom-alinux2-image/1234abcd-56ef-78gh-90ij-abcd1234efgh",
  "stackName": "custom-alinux2-image",
  "logicalResourceId": "ParallelClusterImage",
  "resourceType": "AWS::ImageBuilder::Image",
  "timestamp": "2022-04-05T21:39:24.725Z"
}
```

# `pcluster list-clusters`


Retrieve the list of existing clusters.

```
pcluster list-clusters [-h]
                [--cluster-status {CREATE_IN_PROGRESS,CREATE_FAILED,CREATE_COMPLETE,
                           DELETE_IN_PROGRESS,DELETE_FAILED,UPDATE_IN_PROGRESS,
                           UPDATE_COMPLETE,UPDATE_FAILED}
                           [{CREATE_IN_PROGRESS,CREATE_FAILED,CREATE_COMPLETE,
                             DELETE_IN_PROGRESS,DELETE_FAILED,UPDATE_IN_PROGRESS,
                             UPDATE_COMPLETE,UPDATE_FAILED} ...]]
                [--debug]
                [--next-token NEXT_TOKEN]
                [--query QUERY]
                [--region REGION]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster list-clusters`.

**--cluster-status \$1`CREATE_IN_PROGRESS`, `CREATE_FAILED`, `CREATE_COMPLETE`, `DELETE_IN_PROGRESS`, `DELETE_FAILED`, `UPDATE_IN_PROGRESS`, `UPDATE_COMPLETE`, `UPDATE_FAILED`\$1 [\$1`CREATE_IN_PROGRESS`, `CREATE_FAILED`, `CREATE_COMPLETE`, `DELETE_IN_PROGRESS`, `DELETE_FAILED`, `UPDATE_IN_PROGRESS`, `UPDATE_COMPLETE`, `UPDATE_FAILED`\$1 ...]**  
Specifies the list of cluster statuses to filter for. (Defaults to `all`.)

**--debug**  
Enables debug logging.

**--next-token *NEXT\$1TOKEN***  
The token for the next set of results.

**--query *QUERY***  
Specifies the JMESPath query to perform on the output.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Amazon Web Services Region must be specified, using the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

**Example using Amazon ParallelCluster version 3.1.4:**

```
$ pcluster list-clusters
{
  "clusters": [
    {
      "clusterName": "cluster-v3",
      "cloudformationStackStatus": "CREATE_COMPLETE",
      "cloudformationStackArn": "arn:aws:cloudformation:us-east-1:123456789012:stack/cluster-v3/1234abcd-56ef-78gh-90ij-abcd1234efgh",
      "region": "us-east-1",
      "version": "3.1.4",
      "clusterStatus": "CREATE_COMPLETE"
    }
  ]
}
```

# `pcluster list-cluster-log-streams`


Retrieve the list of log streams associated with a cluster.

```
pcluster list-cluster-log-streams [-h]
                 --cluster-name CLUSTER_NAME                              
                [--filters FILTERS [FILTERS ...]]
                [--next-token NEXT_TOKEN] [--debug]
                [--query QUERY]
                [--region REGION]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster list-cluster-log-streams`.

**--cluster-name, -n *CLUSTER\$1NAME***  
Specifies the name of the cluster.

**--debug**  
Enables debug logging.

**--filters *FILTERS* [*FILTERS* ...]**  
Specifies filters for the log streams. Format: `Name=a,Values=1 Name=b,Values=2,3`. Supported filters are:    
`private-dns-name`  
Specifies the short form of the private DNS name of the instance (e.g. `ip-10-0-0-101`).  
`node-type`  
Specifies the node type, the only accepted value for this filter is `HeadNode`.

**--next-token *NEXT\$1TOKEN***  
The token for the next set of results.

**--query *QUERY***  
Specifies the JMESPath query to perform on the output.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Amazon Web Services Region must be specified, using the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

**Example using Amazon ParallelCluster version 3.1.4:**

```
$ pcluster list-cluster-log-streams \
    -n cluster-v3 \
    -r us-east-1 \
    --query 'logStreams[*].logStreamName'
[
  "ip-172-31-58-205.i-1234567890abcdef0.cfn-init",
  "ip-172-31-58-205.i-1234567890abcdef0.chef-client",
  "ip-172-31-58-205.i-1234567890abcdef0.cloud-init",
  "ip-172-31-58-205.i-1234567890abcdef0.clustermgtd",
  "ip-172-31-58-205.i-1234567890abcdef0.slurmctld",
  "ip-172-31-58-205.i-1234567890abcdef0.supervisord",
  "ip-172-31-58-205.i-1234567890abcdef0.system-messages"
]
```

# `pcluster list-images`


Retrieve the list of existing custom images.

```
pcluster list-images [-h] 
                 --image-status {AVAILABLE,PENDING,FAILED}
                [--debug]
                [--next-token NEXT_TOKEN]
                [--query QUERY]
                [--region REGION]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster list-images`.

**--image-status \$1`AVAILABLE`,`PENDING`,`FAILED`\$1**  
Filter returned images by the status provided.

**--debug**  
Enables debug logging.

**--next-token *NEXT\$1TOKEN***  
The token for the next set of results.

**--query *QUERY***  
Specifies the JMESPath query to perform on the output.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Amazon Web Services Region must be specified, using the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

**Example using Amazon ParallelCluster version 3.1.2:**

```
$ pcluster list-images --image-status AVAILABLE
{
  "images": [
    {
      "imageId": "custom-alinux2-image",
      "imageBuildStatus": "BUILD_COMPLETE",
      "ec2AmiInfo": {
        "amiId": "ami-1234abcd5678efgh"
      },
      "region": "us-east-1",
      "version": "3.1.2"
    }
  ]
}
```

# `pcluster list-image-log-streams`


Retrieve the list of log streams associated with an image.

```
pcluster list-image-log-streams [-h] 
                 --image-id IMAGE_ID
                [--next-token NEXT_TOKEN] [--debug]
                [--query QUERY]
                [--region REGION]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster list-image-log-streams`.

**--image-id, -i *IMAGE\$1ID***  
Specifies the ID of the image.

**--debug**  
Enables debug logging.

**--next-token *NEXT\$1TOKEN***  
The token for the next set of results.

**--query *QUERY***  
Specifies the JMESPath query to perform on the output.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Amazon Web Services Region must be specified, using the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

**Example using Amazon ParallelCluster version 3.1.2:**

```
$ pcluster list-image-log-streams --image-id custom-alinux2-image --region us-east-1 --query 'logStreams[*].logStreamName'
[
  "3.0.0/1",
  "3.1.2/1"
]
```

# `pcluster list-official-images`


Describe official Amazon ParallelCluster AMIs.

```
pcluster list-official-images [-h]
                [--architecture ARCHITECTURE]
                [--debug]
                [--os OS]
                [--query QUERY]
                [--region REGION]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster list-official-images`.

**--architecture *ARCHITECTURE***  
Specifies the architecture to use to filter the results. If this parameter is not specified, all architectures are returned.

**--debug**  
Enables debug logging.

**--os *OS***  
Specifies the operating system to use to filter the results. If this parameter is not specified, all operating systems are returned.

**--query *QUERY***  
Specifies the JMESPath query to perform on the output.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Amazon Web Services Region must be specified, using the [Region](image-builder-configuration-file-v3.md#yaml-build-image-Region) setting in the image configuration file, the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

**Example using Amazon ParallelCluster version 3.1.2:**

```
$ pcluster list-official-images
{
  "images": [
    {
      "amiId": "ami-015cfeb4e0d6306b2",
      "os": "ubuntu2204",
      "name": "aws-parallelcluster-3.1.2-ubuntu-2204-lts-hvm-x86_64-202202261505 2022-02-26T15-08-34.759Z",
      "version": "3.1.2",
      "architecture": "x86_64"
    },
    {
      "amiId": "ami-036f23237ce49d25b",
      "os": "ubuntu2204",
      "name": "aws-parallelcluster-3.1.2-ubuntu-1804-lts-hvm-x86_64-202202261505 2022-02-26T15-08-17.558Z",
      "version": "3.1.2",
      "architecture": "x86_64"
    },
    {
      "amiId": "ami-09e5327e694d89ef4",
      "os": "ubuntu2204",
      "name": "aws-parallelcluster-3.1.2-ubuntu-2204-lts-hvm-arm64-202202261505 2022-02-26T15-08-45.736Z",
      "version": "3.1.2",
      "architecture": "arm64"
    },
    {
      "amiId": "ami-0b9b0874c35f626ae",
      "os": "alinux2",
      "name": "aws-parallelcluster-3.1.2-amzn2-hvm-x86_64-202202261505 2022-02-26T15-08-31.311Z",
      "version": "3.1.2",
      "architecture": "x86_64"
    },
    {
      "amiId": "ami-0d0de4f95f56374bc",
      "os": "alinux2",
      "name": "aws-parallelcluster-3.1.2-amzn2-hvm-arm64-202202261505 2022-02-26T15-08-46.088Z",
      "version": "3.1.2",
      "architecture": "arm64"
    },
    {
      "amiId": "ami-0ebf7bc54b8740dc6",
      "os": "ubuntu2204",
      "name": "aws-parallelcluster-3.1.2-ubuntu-1804-lts-hvm-arm64-202202261505 2022-02-26T15-08-45.293Z",
      "version": "3.1.2",
      "architecture": "arm64"
    }
  ]
}
```

# `pcluster ssh`


Runs a `ssh` command with the cluster user name and IP address pre-populated. Arbitrary arguments are appended to the end of the `ssh` command line.

```
pcluster ssh [-h]
                 --cluster-name CLUSTER_NAME
                [--debug]
                [--dryrun DRYRUN]
                [--region REGION]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster ssh`.

**--cluster-name, -n *CLUSTER\$1NAME***  
Specifies the name of the cluster to connect to.

**--debug**  
Enables debug logging.

**--dryrun *DRYRUN***  
When `true`, prints the command line that would be run and exits. (Defaults to `false`.)

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Amazon Web Services Region must be specified, using the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

Example:

```
$ pcluster ssh --cluster-name mycluster -i ~/.ssh/id_rsa
```

Runs an `ssh` command with the user name and IP address of the cluster pre-populated:

```
ssh ec2-user@1.1.1.1 -i ~/.ssh/id_rsa
```

# `pcluster update-cluster`


Updates an existing cluster to match the settings of a specified configuration file.

**Note**  
 The cluster update succeeds only if all cluster nodes have successfully applied the update. If the update fails, refer to the [Seeing `clusterStatus` is `UPDATE_FAILED` with `pcluster describe-cluster` command](troubleshooting-fc-v3-update-cluster.md#update-cluster-failure-v3) section for troubleshooting guidance. 

```
pcluster update-cluster [-h] 
                 --cluster-configuration CLUSTER_CONFIGURATION
                 --cluster-name CLUSTER_NAME
                [--debug]
                [--dryrun DRYRUN]
                [--force-update FORCE_UPDATE]
                [--query QUERY]
                [--region REGION]
                [--suppress-validators SUPPRESS_VALIDATORS [SUPPRESS_VALIDATORS ...]]
                [--validation-failure-level {INFO,WARNING,ERROR}]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster update-cluster`.

**--cluster-configuration, -c *CLUSTER\$1CONFIGURATION***  
Specifies the YAML cluster configuration file.

**--cluster-name, -n *CLUSTER\$1NAME***  
Specifies the name of the cluster.

**--debug**  
Enables debug logging.

**--dryrun *DRYRUN***  
When `true`, performs the validation without updating the cluster and creating any resources. It can be used to validate the image configuration and update requirements. (Defaults to `false`.)

**--force-update *FORCE\$1UPDATE***  
When `true`, forces the update by ignoring the update validation errors. (Defaults to `false`.)

**--query *QUERY***  
Specifies the JMESPath query to perform on the output.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Amazon Web Services Region must be specified, using the [`Region`](cluster-configuration-file-v3.md#yaml-Region) setting in the cluster configuration file, the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

**--suppress-validators * SUPPRESS\$1VALIDATORS* [*SUPPRESS\$1VALIDATORS ...*]**  
Identifies one or more config validators to suppress.  
Format: (`ALL`\$1`type:[A-Za-z0-9]+`)

**--validation-failure-level *\$1INFO,WARNING,ERROR\$1***  
Specifies the level of validation failures reported for update.

**Example using Amazon ParallelCluster version 3.1.4:**

```
$ pcluster update-cluster -c cluster-config.yaml -n cluster-v3 -r us-east-1
{
  "cluster": {
    "clusterName": "cluster-v3",
    "cloudformationStackStatus": "UPDATE_IN_PROGRESS",
    "cloudformationStackArn": "arn:aws:cloudformation:us-east-1:123456789012:stack/cluster-v3/1234abcd-56ef-78gh-90ij-abcd1234efgh",
    "region": "us-east-1",
    "version": "3.1.4",
    "clusterStatus": "UPDATE_IN_PROGRESS"
  },
  "changeSet": [
    {
      "parameter": "HeadNode.Iam.S3Access",
      "requestedValue": {
        "BucketName": "amzn-s3-demo-bucket1",
        "KeyName": "output",
        "EnableWriteAccess": false
      }
    },
    {
      "parameter": "HeadNode.Iam.S3Access",
      "currentValue": {
        "BucketName": "amzn-s3-demo-bucket2",
        "KeyName": "logs",
        "EnableWriteAccess": true
      }
    }
  ]
}
```

# `pcluster update-compute-fleet`


Updates the status of the cluster compute fleet.

```
pcluster update-compute-fleet [-h] 
                 --cluster-name CLUSTER_NAME
                 --status {START_REQUESTED,STOP_REQUESTED,ENABLED,DISABLED}                             
                [--debug]
                [--query QUERY]
                [--region REGION]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster update-compute-fleet`.

**--cluster-name, -n *CLUSTER\$1NAME***  
Specifies the name of the cluster.

**--status \$1START\$1REQUESTED,STOP\$1REQUESTED,ENABLED,DISABLED\$1**  
Specifies the status applied to the cluster compute fleet. The statuses `START_REQUESTED` and `STOP_REQUESTED` correspond to the Slurm scheduler while the statuses `ENABLED` and `DISABLED` correspond to the Amazon Batch scheduler.

**--debug**  
Enables debug logging.

**--query *QUERY***  
Specifies the JMESPath query to perform on the output.

**--region, -r *REGION***  
Specifies the Amazon Web Services Region to use. The Amazon Web Services Region must be specified, using the `AWS_DEFAULT_REGION` environment variable, the `region` setting in the `[default]` section of the `~/.aws/config` file, or the `--region` parameter.

**Example using Amazon ParallelCluster version 3.1.4:**

```
$ pcluster update-compute-fleet -n cluster-v3 --status STOP_REQUESTED
{
  "status": "STOP_REQUESTED",
  "lastStatusUpdatedTime": "2022-07-12T20:19:47.653Z"
}
```

# `pcluster version`


Displays the version of Amazon ParallelCluster.

```
pcluster version [-h] [--debug]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster version`.

**--debug**  
Enables debug logging.

**Example using Amazon ParallelCluster version 3.1.4:**

```
$ pcluster version
{
  "version": "3.1.4"
}
```

# `pcluster3-config-converter`


Reads a Amazon ParallelCluster version 2 configuration file and writes a Amazon ParallelCluster version 3 configuration file.

```
pcluster3-config-converter [-h]                            
                [-t CLUSTER_TEMPLATE]
                [-c CONFIG_FILE]
                [--force-convert]
                [-o OUTPUT_FILE]
```

## Named arguments


**-h, --help**  
Shows the help text for `pcluster3-config-converter`.

**-t *CLUSTER\$1TEMPLATE*, --cluster-template *CLUSTER\$1TEMPLATE***  
Specifies the [`[cluster]` section](https://docs.amazonaws.cn/parallelcluster/v2/ug/cluster-definition.html) of the configuration file to convert. If not specified the script will look for the [cluster-template](https://docs.amazonaws.cn/parallelcluster/v2/ug/global.html#cluster-template) parameter in the [`[global]` section](https://docs.amazonaws.cn/parallelcluster/v2/ug/global.html) or will search for `[cluster default]`.

**-c *CONFIG\$1FILE*, --config-file *CONFIG\$1FILE***  
Specifies the Amazon ParallelCluster version 2 configuration file to be read.

**--force-convert**  
Enables a conversion even if one or more settings is not supported and not recommended.

**-o *OUTPUT\$1FILE*, --output-file *OUTPUT\$1FILE***  
Specifies the Amazon ParallelCluster version 3 configuration file to be written. If this parameter is not specified, the configuration is written to stdout.

**Note**  
The `pcluster3-config-converter` command was added in Amazon ParallelCluster version 3.0.1.