CLI Reference

tt-fabric-manager-cli is a thin client over the controller’s FabricManagerService.

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:

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:

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

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

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).

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

# 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 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

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

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