CLI Reference

The nf CLI is the primary interface for managing NodeFoundry from the command line. Install it on any machine with network access to the master node.

Installation

macOS / Linux

$ curl -fsSL https://get.nodefoundry.io/cli | bash

Homebrew

$ brew install nodefoundry/tap/nf

Authentication

Authenticate by running nf auth login. This stores a token in ~/.config/nf/credentials.

Shell

$ nf auth login --host https://api.nodefoundry.io
Enter API key: nf_sk_live_...
✓ Authenticated as ben@example.com

Commands

cluster

nf cluster list

List all clusters. Add --json for machine-readable output.

nf cluster create

Create a new Ceph cluster.

Flag	Description
`--name`	Cluster name (required)
`--nodes`	Comma-separated node names or IDs (required)
`--version`	Ceph version: `reef`, `squid` (required)
`--failure-domain`	`host` (default), `rack`, `zone`
`--wait`	Block until deployment completes

nf cluster health <name>

Show health summary for a cluster.

Flag	Description
`--verbose`	Show per-OSD and per-PG detail
`--watch`	Refresh every 2 seconds (like `watch`)

nf cluster upgrade <name>

Trigger a rolling upgrade.

Flag	Description
`--ceph-version`	Target Ceph version
`--os-packages`	Also update OS packages on all nodes
`--max-concurrent`	Nodes to upgrade at once (default: `1`)
`--dry-run`	Print what would happen without executing

node

nf node list

List all registered nodes. Use --cluster <name> to filter.

nf node inspect <name>

Show full hardware inventory for a node: CPU, RAM, drives, NICs, SMART data, and IPMI status.

nf node reboot <name>

Reboot a node via IPMI after draining active OSDs.

Flag	Description
`--hard`	Force power cycle (skips graceful shutdown)
`--no-drain`	Skip OSD drain (use only in emergencies)

nf node maintenance <name>

Put a node in maintenance mode. Drains OSDs and suppresses alerts while hardware work is in progress.

pool

nf pool list <cluster>

List all pools in a cluster with capacity and PG counts.

nf pool create <cluster>

Flag	Description
`--name`	Pool name (required)
`--type`	`replicated` (default) or `erasure`
`--replication-factor`	Replicated pool size (default: `3`)
`--erasure-profile`	Named erasure code profile
`--application`	`rbd`, `cephfs`, or `rgw`

log

nf log search

Search indexed OSD, monitor, and service logs across all nodes.

Flag	Description
`--since`	Start time, e.g. `1h`, `2026-03-01`
`--until`	End time
`--node`	Filter to a specific node
`--level`	`debug`, `info`, `warn`, `error`

image

nf image list

List available OS images stored on the master node.

nf image upload <path>

Upload a new OS image to the master node for use with iPXE boot.

nf image set-default <name>

Set the image served to newly booting nodes.