github.com/pdmccormick/importable-docker-buildx@v0.0.0-20240426161518-e47091289030/docs/reference/buildx_ls.md (about)

     1  # buildx ls
     2  
     3  ```text
     4  docker buildx ls
     5  ```
     6  
     7  <!---MARKER_GEN_START-->
     8  List builder instances
     9  
    10  ### Options
    11  
    12  | Name                  | Type     | Default | Description       |
    13  |:----------------------|:---------|:--------|:------------------|
    14  | [`--format`](#format) | `string` | `table` | Format the output |
    15  
    16  
    17  <!---MARKER_GEN_END-->
    18  
    19  ## Description
    20  
    21  Lists all builder instances and the nodes for each instance.
    22  
    23  ```console
    24  $ docker buildx ls
    25  NAME/NODE           DRIVER/ENDPOINT                   STATUS    BUILDKIT   PLATFORMS
    26  elated_tesla*       docker-container
    27   \_ elated_tesla0    \_ unix:///var/run/docker.sock   running   v0.10.3    linux/amd64
    28   \_ elated_tesla1    \_ ssh://ubuntu@1.2.3.4          running   v0.10.3    linux/arm64*, linux/arm/v7, linux/arm/v6
    29  default             docker
    30   \_ default          \_ default                       running   v0.8.2     linux/amd64
    31  ```
    32  
    33  Each builder has one or more nodes associated with it. The current builder's
    34  name is marked with a `*` in `NAME/NODE` and explicit node to build against for
    35  the target platform marked with a `*` in the `PLATFORMS` column.
    36  
    37  ## Examples
    38  
    39  ### <a name="format"></a> Format the output (--format)
    40  
    41  The formatting options (`--format`) pretty-prints builder instances output
    42  using a Go template.
    43  
    44  Valid placeholders for the Go template are listed below:
    45  
    46  | Placeholder       | Description                                 |
    47  |-------------------|---------------------------------------------|
    48  | `.Name`           | Builder or node name                        |
    49  | `.DriverEndpoint` | Driver (for builder) or Endpoint (for node) |
    50  | `.LastActivity`   | Builder last activity                       |
    51  | `.Status`         | Builder or node status                      |
    52  | `.Buildkit`       | BuildKit version of the node                |
    53  | `.Platforms`      | Available node's platforms                  |
    54  | `.Error`          | Error                                       |
    55  | `.Builder`        | Builder object                              |
    56  
    57  When using the `--format` option, the `ls` command will either output the data
    58  exactly as the template declares or, when using the `table` directive, includes
    59  column headers as well.
    60  
    61  The following example uses a template without headers and outputs the
    62  `Name` and `DriverEndpoint` entries separated by a colon (`:`):
    63  
    64  ```console
    65  $ docker buildx ls --format "{{.Name}}: {{.DriverEndpoint}}"
    66  elated_tesla: docker-container
    67  elated_tesla0: unix:///var/run/docker.sock
    68  elated_tesla1: ssh://ubuntu@1.2.3.4
    69  default: docker
    70  default: default
    71  ```
    72  
    73  The `Builder` placeholder can be used to access the builder object and its
    74  fields. For example, the following template outputs the builder's and
    75  nodes' names with their respective endpoints:
    76  
    77  ```console
    78  $ docker buildx ls --format "{{.Builder.Name}}: {{range .Builder.Nodes}}\n  {{.Name}}: {{.Endpoint}}{{end}}"
    79  elated_tesla:
    80    elated_tesla0: unix:///var/run/docker.sock
    81    elated_tesla1: ssh://ubuntu@1.2.3.4
    82  default: docker
    83    default: default
    84  ```