# CLI Reference

`tt-fabric-manager-cli` is a thin client over the controller's
[`FabricManagerService`](api-overview.md).

```
tt-fabric-manager-cli [OPTIONS] <command> [COMMAND_ARGS]
```

## Running CLI in Docker

Currently the most convenient way to obtain a pre-built FM CLI is via the official
FM image. For example:

```bash
alias tt-fabric-manager-cli='docker run --rm --net=host \
  -e FABRIC_MANAGER_ENDPOINT=ttfm.example.com:80 \
  -v $(pwd):$(pwd) \
  -w $(pwd) \
  ghcr.io/tenstorrent/tt-fabric-manager:latest-cli tt-fabric-manager-cli'
```

## Connecting to a controller

The endpoint is resolved from the following sources, highest priority first:

1. `--endpoint <addr>`
2. `FABRIC_MANAGER_ENDPOINT` environment variable
3. `/etc/fabric-manager/config.yaml` (`controller.listen_address` or `controller.endpoint`)
4. `~/.fabric-manager/config`
5. `/etc/fabric-manager/client.conf`
6. Built-in default, `localhost:50051`

Config files are YAML. A lightweight client-only file needs just two keys:

```yaml
endpoint: localhost:50052
timeout_seconds: 30
```

The full server config is also accepted, in which case the endpoint is read from
`controller.endpoint` or `controller.listen_address` and the timeout from
`controller.timeout_seconds`.

## Global options

| Option | Default | Description |
|--------|---------|-------------|
| `--endpoint <addr>` | `localhost:50051` | Controller address |
| `--timeout <sec>` | `600` | gRPC deadline for the call |
| `--verbose`, `-v` | off | Diagnostics to stderr, prefixed `[tt-fabric-manager-cli]` |
| `--help`, `-h` | | Print usage and exit |

The long timeout default is deliberate: a placement query on a large fabric can
take minutes, and FSD-sourced placements additionally rediscover every host.

Several options are shared by more than one command: `--host-id <id>` (repeatable,
filters by host), `--output <path>` / `-o` (write payload to a file instead of
inlining it in the JSON), and `--source <psd|fsd>` (see
[topology sources](api-overview.md#topology-sources-psd-and-fsd)).

## Commands

### `query-physical-topology`

Fetches the aggregated `PhysicalSystemDescriptor` via `QueryPhysicalTopology`.

| Option | Description |
|--------|-------------|
| `--host-id <hostname>` | Restrict to these hosts (repeatable) |
| `--source <psd\|fsd>` | Connectivity source. Default `psd` |
| `--output <path>` | Write the descriptor as textproto to `path` instead of embedding it in the JSON |

```bash
# Whole fabric, as JSON
tt-fabric-manager-cli query-physical-topology

# Two hosts, golden-state wiring, saved as textproto
tt-fabric-manager-cli query-physical-topology \
  --host-id host-a --host-id host-b --source fsd -o topology.textproto
```

Exits non-zero if the query fails. The `trim_links_outside_filter` request field
is not exposed by the CLI; use the [HTTP API](web-ui.md) or the SDK for that.

### `query-factory-descriptor`

Fetches the controller's configured FSD files via
`QueryFactorySystemDescriptor`.

| Option | Description |
|--------|-------------|
| `--host-id <hostname>` | Filter the FSD to these hostnames (repeatable) |
| `--output <path>` | Write the serialized FSD to a file. With multiple files, they are suffixed `path.0`, `path.1`, … |

Requires the controller to be configured with
`controller.factory_system_descriptor_search_path`.

### `get-valid-placements-mgd`

Maps a Mesh Graph Descriptor onto the fabric via `GetValidPlacementsMGD`, and can
emit launcher configuration for a chosen placement.

| Option | Default | Description |
|--------|---------|-------------|
| `--mgd-file <path>` | **required** | MGD in textproto form |
| `--host-id <id>` | | Restrict placement to these hosts (repeatable) |
| `--source <psd\|fsd>` | `psd` | Connectivity source |
| `--placement-index <n>` | `0` | Which returned placement the launcher outputs describe |
| `--rank-bindings-out <path>` | | Also write a rank bindings YAML (`TT_VISIBLE_DEVICES` built from chip IDs) |
| `--rankfile-out <path>` | | Also write an OpenMPI rankfile |
| `--mesh-graph-desc-path <path>` | value of `--mgd-file` | Value written to the rank bindings file's `mesh_graph_desc_path` field |

```bash
tt-fabric-manager-cli get-valid-placements-mgd \
  --mgd-file examples/mgd.2x4.textproto \
  --rank-bindings-out rank_bindings.yaml \
  --rankfile-out rankfile
```

The command exits non-zero unless the status is `PLACEMENT_MGD_SUCCESS`, so it
can gate a job launch directly.

```{warning}
Only textproto MGDs are accepted — the file must end in `.textproto` or `.txt`.
Binary `.pb` files are rejected with a message pointing at `protoc`; convert
first. (The built-in `--help` text still claims `.pb` is supported.)
```

### `show-topology`

The one human-oriented command: renders an ASCII summary of hosts and cross-host
connectivity from `QueryTopologySummary`. Output width follows the terminal, or
`COLUMNS` when it cannot be detected. Errors go to stderr.

| Option | Description |
|--------|-------------|
| `--source <psd\|fsd\|combined>` | Build the view from the discovered PSD (default), the FSD, or the union of both. `combined` also tags each host with its source and FSD data-centre location |
| `--validate` | Ask the controller to diff PSD against FSD and report missing and unexpected cross-host links per host. Requires a configured FSD |

```bash
tt-fabric-manager-cli show-topology --source combined --validate
```