> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt
> Use this file to discover all available pages before exploring further.

# List Machines

> List, filter, and inspect hosted Nullspace machines from the CLI.

Use `nullspace machine list` to find running, paused, and historical machines.
List responses support state, template, metadata, pagination, and field
selection.

## Basic List

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine list
nullspace machine list --json
```

Use JSON output when another script or agent will parse the response.

## Filter By State

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine list --state running
nullspace machine list --state paused
nullspace machine list --state destroyed
```

The public API supports `creating`, `running`, `paused`, `destroyed`, and
`error` states.

## Filter By Template Or Metadata

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine list --template base
nullspace machine list --metadata team=eval
nullspace machine list --metadata-json '{"team":"eval","run":"smoke"}'
```

Metadata filters match key/value pairs attached at machine creation time.

## Paginate

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine list --limit 20 --json
nullspace machine list --limit 20 --next-token nt_...
```

Use the `next_token` returned by a JSON response to fetch the next page.

## Inspect One Machine

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine get mch_123
nullspace machine get mch_123 --json
nullspace machine metrics mch_123 --json
```

`get` returns the current machine record. `metrics` returns usage and runtime
metrics when the host has reported them.

## Common Follow-Ups

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine exec mch_123 --shell "pwd && ls -la"
nullspace machine url mch_123 8080
nullspace machine pause mch_123
nullspace machine kill mch_123
```

For SDK examples, see [Create, Connect, And List Machines](../machines/create-connect-list).