# List Workers

The [Octopus CLI](/docs/octopus-rest-api/octopus-cli) can be used to list all Workers.

```
Lists all workers.

Usage: octo list-workers [<options>]

Where [<options>] is any of:

Listing Workers:

      --workerPool=VALUE     Name of a worker pool to filter by. Can be
                             specified many times.
      --status=VALUE         [Optional] Status of Machines filter by (Online,
                             Offline, Unknown, NeedsUpgrade,
                             CalamariNeedsUpgrade, Disabled). Can be
                             specified many times.
      --health-status, --healthStatus=VALUE
                             [Optional] Health status of Machines filter by
                             (Healthy, Unavailable, Unknown, HasWarnings,
                             Unhealthy). Can be specified many times.
      --disabled=VALUE       [Optional] Disabled status filter of Machine.
      --calamari-outdated=VALUE
                             [Optional] State of Calamari to filter. By
                             default ignores Calamari state.
      --tentacle-outdated=VALUE
                             [Optional] State of Tentacle version to filter.
                             By default, ignores Tentacle state.

Common options:

      --help                 [Optional] Print help for a command.
      --helpOutputFormat=VALUE
                             [Optional] Output format for help, valid options
                             are Default or Json
      --outputFormat=VALUE   [Optional] Output format, valid options are
                             Default or Json
      --server=VALUE         [Optional] The base URL for your Octopus Server,
                             e.g., 'https://octopus.example.com/'. This URL
                             can also be set in the OCTOPUS_CLI_SERVER
                             environment variable.
      --apiKey=VALUE         [Optional] Your API key. Get this from the user
                             profile page. You must provide an apiKey or
                             username and password. If the guest account is
                             enabled, a key of API-GUEST can be used. This
                             key can also be set in the OCTOPUS_CLI_API_KEY
                             environment variable.
      --user=VALUE           [Optional] Username to use when authenticating
                             with the server. You must provide an apiKey or
                             username and password. This Username can also be
                             set in the OCTOPUS_CLI_USERNAME environment
                             variable.
      --pass=VALUE           [Optional] Password to use when authenticating
                             with the server. This Password can also be set
                             in the OCTOPUS_CLI_PASSWORD environment variable.
      --configFile=VALUE     [Optional] Text file of default values, with one
                             'key = value' per line.
      --debug                [Optional] Enable debug logging.
      --ignoreSslErrors      [Optional] Set this flag if your Octopus Server
                             uses HTTPS but the certificate is not trusted on
                             this machine. Any certificate errors will be
                             ignored. WARNING: this option may create a
                             security vulnerability.
      --enableServiceMessages
                             [Optional] Enable TeamCity or Team Foundation
                             Build service messages when logging.
      --timeout=VALUE        [Optional] Timeout in seconds for network
                             operations. Default is 600.
      --proxy=VALUE          [Optional] The URL of the proxy to use, e.g.,
                             'https://proxy.example.com'.
      --proxyUser=VALUE      [Optional] The username for the proxy.
      --proxyPass=VALUE      [Optional] The password for the proxy. If both
                             the username and password are omitted and
                             proxyAddress is specified, the default
                             credentials are used.
      --space=VALUE          [Optional] The name or ID of a space within
                             which this command will be executed. The default
                             space will be used if it is omitted.
      --logLevel=VALUE       [Optional] The log level. Valid options are
                             verbose, debug, information, warning, error and
                             fatal. Defaults to 'debug'.
```

## Basic examples

:::div{.success}
**Octopus Samples instance**

Many of the examples we use, reference the [samples instance](https://samples.octopus.app/app#/users/sign-in) of Octopus Deploy. If you'd like to explore the samples instance, you can log in as a guest.
:::

This example lists worker machines in the `Default worker pool` in the default space:
```
octo list-workers --workerPool="Default worker pool" --server="https://your-octopus-url" --apiKey="API-YOUR-KEY"
```

This example lists all workers in MyWorkerPool that are disabled:

```
octo list-workers --workerPool="MyWorkerPool" --server="https://your-octopus-url" --apiKey="API-YOUR-KEY" --disabled="true"
```

This example lists all workers with a status of `Unknown` in the [Target - NGINX](https://samples.octopus.app/app#/Spaces-104) space:

```
octo list-workers --workerPool="Default worker pool" --server="https://samples.octopus.com" --apiKey="API-YOUR-KEY" --space="Target - NGINX" --health-status="Unknown"
```

## Learn more

- [Octopus CLI](/docs/octopus-rest-api/octopus-cli)
- [Creating API keys](/docs/octopus-rest-api/how-to-create-an-api-key)
- [Workers](/docs/infrastructure/workers)