Manta CLI Reference

Documentation version: this reference describes the CLI shipped with manta 2.0.0. For an older release, browse the repository at the matching git tag (e.g. v1.64.3 for the last v1 release).

Complete reference for all manta commands, subcommands, and flags.

Binary name: the CLI binary is manta (the Cargo package is manta-cli; the [[bin]] block in its manifest renames the produced executable). The HTTP API server is a separate binary (manta-server); see API.md for its endpoints and README.md for how to run it.

TL;DR

Every command takes one of the top-level verbs:

Verb	Purpose
`config`	Manage `~/.config/manta/cli.toml`
`get`	Read-only queries (sessions, configurations, nodes, groups, hardware, …)
`add`	Create resources (node, group, hardware components, boot/kernel params)
`apply`	Apply changes (SAT files, boot/kernel parameters, Redfish endpoints, hardware allocation, …)
`run`	Create and run jobs (configuration sessions)
`delete`	Remove resources
`backup`	Back up cluster state (virtual cluster)
`restore`	Restore cluster state from a backup
`migrate`	Move nodes between groups
`power`	Power on/off/reset nodes or groups
`log`	Stream CFS session logs (alias: `manta logs`)
`console`	Open a WebSocket console to a node or running CFS session
`gen-autocomplete`	Generate shell completion scripts
`gen-man`	Generate and install man pages
`upgrade`	Replace this `manta` binary with the latest release

Global flag (available on every command):

Flag	Description
`--site <SITE_NAME>`	Override the active site from config for this invocation. Accepted at any position on the command line — `manta --site alps get sessions` and `manta get sessions --site alps` both work.

Universal mutating-verb flag. Every backend-mutating verb (add, apply, backup, delete, migrate, power, restore, run) accepts -d/--dry-run. The CLI builds and prints the exact request that would have been sent, skips confirmation prompts, and exits without contacting the server. --dry-run invocations also bypass the read-only gate, so an operator with read_only = true in cli.toml can still preview what they would have run. See GUIDE.md §12 — Preview before mutating with --dry-run for the full semantics.

One short-alias caveat: manta add group reserves -d for --dry-run, so its --description short alias is -D (capital). Every other mutating verb uses -d for --dry-run consistently.

Migrating from earlier shapes

Several CLI shapes were renamed in the latest releases and the old forms have now been removed. The canonical names:

Removed form	Replacement
`manta apply session`	`manta run session`
`manta apply boot cluster`	`manta apply boot group`
`manta apply hardware cluster`	`manta apply hardware group`
`manta get cluster`	`manta get group-nodes`
`manta get hardware cluster`	`manta get hardware group`
`manta power on cluster`	`manta power on group`
`manta power off cluster`	`manta power off group`
`manta power reset cluster`	`manta power reset group`
`manta migrate vCluster backup`	`manta backup vcluster`
`manta migrate vCluster restore`	`manta restore vcluster`
`manta config gen-autocomplete`	`manta gen-autocomplete`
`manta update boot-parameters`	`manta apply boot-parameters`
`manta update redfish-endpoints`	`manta apply redfish-endpoint`
`manta add-nodes-to-groups`	`manta add nodes`
`manta remove-nodes-from-groups`	`manta delete nodes`
`manta get summary`	`manta get analysis image` (renamed via `manta get cache`)
`manta get cache`	`manta get analysis image`
`manta get group-hardware <GROUP>`	`manta get hardware group <GROUP>`
`manta config set parent-hsm <NAME>`	(removed; the `parent_hsm_group` key is gone — see MIGRATING.md §5.7)
`manta config unset parent-hsm`	(removed; see above)

The following flag renames are still in effect; the old spellings are kept as visible clap aliases on the canonical commands:

Old flag	New flag
`--target-cluster`	`--target-group`
`--parent-cluster`	`--parent-group`
`--create-hsm-group`	`--create-group`
`--delete-hsm-group`	`--delete-group`
`--create-target-hsm-group`	`--create-target-group`
`--delete-empty-parent-hsm-group`	`--delete-empty-parent-group`
`--hsm-group`	`--group`
`redfish-endpoint` (singular noun on `add` / `delete` / `apply`)	`redfish-endpoints` (plural)

Removed flag (no alias): manta apply sat-file --reboot was renamed to --create-bos-session and the old spelling is no longer accepted. Scripts passing --reboot to apply sat-file now error with clap's standard "unexpected argument". The wire field on POST /sat-file/session-templates was renamed in the same change (reboot → create_bos_session). See MIGRATING.md §5.8.

config

Manage the local manta configuration file (~/.config/manta/cli.toml).

config show

Print current configuration values, including a top-level read_only flag (from cli.toml) and a session block populated from the bearer token (username, name, is_admin, accessible_groups). Use this to inspect what the token grants the current user.

manta config show

JSON output (-o json) renders the session as a sub-object, with read_only at the top level:

{
  "config_file": "...",
  "current_site": "alps",
  "read_only": false,
  "session": {
    "username": "alice",
    "name": "Alice Smith",
    "is_admin": false,
    "accessible_groups": ["compute", "uan"]
  },
  ...
}

The session block is null when no site is selected (no token resolved).

config set hsm <HSM_GROUP_NAME>

Set the default target HSM group.

manta config set hsm compute

config set site <SITE_NAME>

Set the active site, persisted as site = "..." in cli.toml and sent as the X-Manta-Site header. The server validates it against its configured sites; the CLI does no local validation.

manta config set site cscs_prod

config set log <LOG_LEVEL>

Set log verbosity. Values: error, warn, info, debug, trace.

manta config set log debug

config unset hsm

Remove the default HSM group.

config unset auth

Remove the stored authentication token.

get

Retrieve information from the cluster.

get groups [VALUE]

List HSM groups, or show details for a single group.

Arg/Flag	Type	Required	Default	Description
`VALUE`	string	no	—	Group name; returns all groups if omitted
`-o/--output`	string	no	`table`	Output format: `table`, `json`

manta get groups
manta get groups my-cluster -o json

get hardware group <GROUP_NAME>

List hardware components in a group.

Arg/Flag	Type	Required	Default	Description
`GROUP_NAME`	string	yes	—	HSM group name
`-o/--output`	string	no	`summary`	Output format: `summary`, `details`, `pattern`, `json`

Output modes:

summary — aggregated table: hw component → total count across all nodes
details — per-node table with one column per unique hw component type
pattern — single line <group>:<component>:<qty>:...
json — raw JSON

manta get hardware group gpu-cluster -o details

get hardware nodes <VALUE>

Per-node hardware component breakdown for an explicit list of nodes. Equivalent to get hardware group --output details but scoped to specific nodes instead of an entire group.

Arg/Flag	Type	Required	Default	Description
`VALUE`	string	yes	—	Xnames/nids or hostlist expression
`-o/--output`	string	no	`table`	Output format: `table`, `json`

manta get hardware nodes 'x3000c0s1b0n[0-3]'
manta get hardware nodes x3000c0s1b0n0,x3000c0s1b0n1 -o json

get sessions

List CFS sessions with optional filters. Listed oldest first (newest last).

Flag	Type	Description
`-n/--name`	string	Exact session name
`-a/--min-age`	string	Minimum age, e.g. `1d`, `6h`
`-A/--max-age`	string	Maximum age
`-t/--type`	string	`image` or `runtime`
`-s/--status`	string	`pending`, `running`, `complete`
`-m/--most-recent`	flag	Return only the most recent session
`-l/--limit`	u8	Return the N most recent sessions (shown oldest first)
`-x/--xnames`	string	Comma-separated xnames to filter by
`-H/--group`	string	HSM group name to filter by
`-o/--output`	string	Output format: `json`

--group, --xnames, and --name are mutually exclusive.
--most-recent and --limit are mutually exclusive.

manta get sessions --group compute --status running
manta get sessions --most-recent -o json

get configurations

List CFS configurations, oldest first (newest last). Each row carries a Safe to delete verdict (yes when no CFS component lists the configuration as desired_config and no BSS-referenced image was built from it; no otherwise; ? when the server-side analysis fan-out failed and the verdict couldn't be computed for that row). The verdict is computed server-side using the same logic as manta get analysis configuration and arrives on a single /configurations response — no client-side fan-out. Safety enrichment is best-effort: if the analysis fan-out fails, the listing still returns with ? in the safety column instead of erroring.

Flag	Type	Description
`-n/--name`	string	Exact configuration name
`-p/--pattern`	string	Glob pattern for configuration name
`-m/--most-recent`	flag	Show only the most recent
`-l/--limit`	u8	Return the N most recent configurations (shown oldest first)
`-H/--group`	string	HSM group to filter by
`-o/--output`	string	Output format: `json` (table is the default). The JSON output gains a `safe_to_delete` bool per row.
`--only-safe-to-delete`	flag	Show only rows where `safe_to_delete == true`. Mutually exclusive with `--only-unsafe-to-delete`. Configurations whose safety verdict is unknown are excluded.
`--only-unsafe-to-delete`	flag	Show only rows where `safe_to_delete == false` (currently in use).

--group and --name are mutually exclusive.
--most-recent and --limit are mutually exclusive.
--only-safe-to-delete and --only-unsafe-to-delete are mutually exclusive.

manta get configurations --pattern "csm-config-*" --limit 5
manta get configurations --only-safe-to-delete
manta get configurations --only-unsafe-to-delete -o json | jq '.[].name'

get templates

List BOS session templates, sorted by name. BOS templates have no timestamp, so there is no recency order — --most-recent/--limit only cap the count.

Flag	Type	Default	Description
`-n/--name`	string	—	Template name
`-m/--most-recent`	flag	—	Return a single template (equivalent to `--limit 1`; not recency-based)
`-l/--limit`	u8	—	Return at most N templates
`-H/--group`	string	—	HSM group name
`-o/--output`	string	`table`	Output format: `table`, `json`

get group-nodes <GROUP_NAME>

Show node membership and status for an HSM group.

Arg/Flag	Type	Default	Description
`GROUP_NAME`	string	—	HSM group name
`-n/--nids-only-one-line`	flag	—	Print NIDs as a single comma-separated line
`-x/--xnames-only-one-line`	flag	—	Print xnames as a single comma-separated line
`-s/--status`	string	—	Filter by status: `OFF`, `ON`, `READY`, `STANDBY`, `PENDING`, `FAILED`, `CONFIGURED`
`-T/--summary-status`	flag	—	Print overall status summary
`-o/--output`	string	`table`	Output format: `table`, `table-wide`, `json`, `summary`

manta get group-nodes compute -o summary
manta get group-nodes compute --xnames-only-one-line

get nodes <VALUE>

Show details for specific nodes.

Arg/Flag	Type	Default	Description
`VALUE`	string	—	Comma-separated xnames/nids or hostlist expression
`-n/--nids-only-one-line`	flag	—	Print NIDs as a single line
`-s/--status`	string	—	Filter by status
`-T/--summary-status`	flag	—	Print status summary
`-S/--include-siblings`	flag	—	Include nodes sharing the same power supply
`-o/--output`	string	`table`	Output format: `table`, `table-wide`, `json`, `summary`

manta get nodes 'x3000c0s1b0n[0-3]'
manta get nodes nid001313,nid001314 -o json

get images

List IMS images, oldest first (newest last). Each row carries a Safe to delete verdict (yes when no BSS boot-parameter record references the image as its boot image; no otherwise; ? only on the rare race where an image appears in the listing but not in the deletion-safety analysis). The verdict is sourced from /analysis/images and computed identically to manta get analysis image.

Flag	Type	Description
`-i/--id`	string	Specific image ID
`-p/--pattern`	string	Glob pattern matched against image name (e.g. `csm-`, `-1.6.2-`). Uses globset syntax — `` matches any run of non-`/` characters, `?` a single character, `[abc]` a character class. Anchored to the full name.
`-s/--since`	date	Show only images created at or after this point. A bare `YYYY-MM-DD` starts at midnight; a full `YYYY-MM-DDTHH:MM:SS` is exact. Inclusive.
`-u/--until`	date	Show only images created at or before this point. A bare `YYYY-MM-DD` extends to `23:59:59` that day, so `--until 2026-03-01` covers March 1st through `23:59:59` (an image built in the final sub-second is excluded); a full `YYYY-MM-DDTHH:MM:SS` is exact. Inclusive.
`-m/--most-recent`	flag	Show most recent only
`-l/--limit`	u8	Return the N most recent images (shown oldest first)
`--only-safe-to-delete`	flag	Show only rows where `safe_to_delete == true`. Mutually exclusive with `--only-unsafe-to-delete`. Images whose safety verdict is unknown are excluded.
`--only-unsafe-to-delete`	flag	Show only rows where `safe_to_delete == false` (image is the boot image for at least one node).

--only-safe-to-delete and --only-unsafe-to-delete are mutually exclusive.

--since/--until filter on the Creation time column. IMS does not support date queries, so the filtering happens in manta-server after fetching the listing. A --since later than --until is rejected with a 400. Images whose creation date is missing or unreadable are omitted while either bound is set — they cannot be shown to satisfy the range.

# Images built this year, newest last
manta get images --since 2026-01-01

# Images built in a window, narrowed to compute nodes
manta get images --since 2026-01-01 --until 2026-03-01 --pattern 'compute-*'

Images built by manta apply sat-file carry CFS provenance under their metadata map: manta.image_session.base (source image id), manta.image_session.groups (JSON-encoded HSM group names), manta.image_session.configuration (CFS configuration name). See GUIDE.md §3.

get analysis image

One row per IMS image visible to the active site. Columns: image id, image name, image created timestamp, the CFS configuration the image was built with, and a Safe to delete verdict (yes when no BSS boot-parameter record references the image as its boot image; no otherwise — that image is currently a node's boot image and deleting it would break the next boot).

Flag	Type	Description
`-o/--output`	string	`table` (default) or `json`. JSON returns the same five fields.
`--only-safe-to-delete`	flag	Show only rows where `safe_to_delete == true`. Mutually exclusive with `--only-unsafe-to-delete`.
`--only-unsafe-to-delete`	flag	Show only rows where `safe_to_delete == false` (image is the boot image for at least one node).

manta get analysis image
manta get analysis image --only-safe-to-delete
manta get analysis image --only-unsafe-to-delete -o json | jq '.[].image_id'

Sorted by image_created ascending (oldest first); images without a created timestamp sink to the bottom; ties on the timestamp (or both None) break by image_id ascending. Calls GET /v2/analysis/images.

get analysis configuration

List every CFS configuration sorted by last_updated (oldest first), with a safe_to_delete verdict per row. A configuration is safe_to_delete: true iff no CFS component lists it as desired_config and no BSS-referenced image was built from it. Any single dependency on either surface flips it to false.

Flag	Type	Description
`-o/--output`	string	`table` (default) or `json`.
`--only-safe-to-delete`	flag	Show only rows where `safe_to_delete == true`. Mutually exclusive with `--only-unsafe-to-delete`.
`--only-unsafe-to-delete`	flag	Show only rows where `safe_to_delete == false` (configurations currently in use).

manta get analysis configuration
manta get analysis configuration --only-safe-to-delete
manta get analysis configuration --only-unsafe-to-delete -o json | jq '.[].name'

Calls GET /v2/analysis/configurations.

get boot-parameters

Get BSS boot parameters.

Flag	Type	Description
`-H/--group`	string	HSM group name
`-n/--nodes`	string	Comma-separated xnames/nids or hostlist expression

Pass one of --group or --nodes — clap doesn't enforce this for you, so omitting both returns the global set.

manta get boot-parameters --group compute

get kernel-parameters

Get kernel boot parameters for nodes.

Flag	Type	Default	Description
`-n/--nodes`	string	—	Comma-separated xnames/nids or hostlist
`-H/--group`	string	—	HSM group name
`-f/--filter`	string	—	Comma-separated parameter names to extract, e.g. `console,crashkernel`
`-o/--output`	string	`table`	Output format: `table`, `json`

One of --nodes or --group is required.

manta get kernel-parameters --group compute --filter console,loglevel

get redfish-endpoints

List registered Redfish endpoints (BMCs).

Flag	Type	Default	Description
`-i/--id`	string	—	Filter by xname
`-f/--fqdn`	string	—	Filter by FQDN
`-u/--uuid`	string	—	Filter by UUID
`-m/--macaddr`	string	—	Filter by MAC address
`-I/--ipaddress`	string	—	Filter by IP address
`-o/--output`	string	`table`	Output format: `table`, `json`

add

Create new resources.

add group

Create a new HSM group.

Flag	Type	Required	Description
`-l/--label`	string	yes	Group name
`-D/--description`	string	no	Group description
`-n/--nodes`	string	no	Initial members (xnames/nids/hostlist)
`-d/--dry-run`	flag	no	Simulate without changes (skips the confirmation prompt; previews both the `create_group` payload and, if `--nodes` was given, the follow-up `add_nodes_to_group` payload)
`-o/--output`	string	no	Output format: `table`, `json` (default `table`; honored on dry-run)

The -d short alias is reserved for --dry-run; use -D (capital) for --description.

manta add group --label my-cluster --description "GPU nodes" --nodes 'x3000c0s1b0n[0-7]'

add node

Flag	Type	Required	Description
`-i/--id`	string	yes	Node xname
`-g/--group`	string	yes	Group the node belongs to
`-H/--hardware`	path	no	File with hardware info
`-a/--arch`	string	no	Architecture: `X86`, `ARM`, `Other`
`-d/--disabled`	flag	no	Disable node on creation

add nodes

Add existing nodes to an HSM group's membership. Distinct from add node (singular), which registers a brand-new node in the inventory.

Replaces the removed manta add-nodes-to-groups top-level command.

Flag	Type	Required	Description
`-g/--group`	string	yes	Group to add the nodes to
`-n/--nodes`	string	yes	Nodes to add (xnames/nids/hostlist)
`-d/--dry-run`	flag	no	Simulate without changes
`-o/--output`	string	no	Output format: `table`, `json` (default `table`)

add hardware (WIP)

Add hardware components to an HSM group.

Flag names below are the canonical group-centric form; the old --target-cluster, --parent-cluster, --create-hsm-group spellings continue to work as visible aliases.

Flag	Type	Description
`-P/--pattern`	string	Hardware pattern, e.g. `a100:4:epyc:2`
`-t/--target-group`	string	Target group name
`-p/--parent-group`	string	Source group providing the hardware
`-d/--dry-run`	flag	Simulate without changes
`-c/--create-group`	flag	Create target group if it does not exist

add boot-parameters

Add BSS boot parameters for nodes.

Flag	Type	Required	Description
`-H/--hosts`	string	yes	Comma-separated xnames
`-n/--nids`	string	no	Comma-separated NIDs
`-m/--macs`	string	no	Comma-separated MAC addresses
`-p/--params`	string	no	Kernel parameters string
`-k/--kernel`	string	no	S3 path to kernel file
`-i/--initrd`	string	no	S3 path to initrd file
`-c/--cloud-init`	string	no	Cloud-init script
`-d/--dry-run`	flag	no	Simulate without changes
`-y/--assume-yes`	flag	no	Non-interactive mode

add kernel-parameters <VALUE>

Merge kernel parameters into existing values for nodes.

Arg/Flag	Type	Required	Description
`VALUE`	string	yes	Space-separated `key=value` pairs
`-n/--nodes`	string	no*	Target nodes (xnames/nids/hostlist)
`-H/--group`	string	no*	Target HSM group
`-O/--overwrite`	flag	no	Overwrite existing values
`-y/--assume-yes`	flag	no	Non-interactive mode
`--do-not-reboot`	flag	no	Skip node reboot after change
`-d/--dry-run`	flag	no	Simulate without changes

One of --nodes or --group is required.

manta add kernel-parameters "console=ttyS0,115200 loglevel=7" --group compute

add redfish-endpoint

Flag	Type	Required	Description
`-i/--id`	string	yes	Xname (physical location ID)
`-n/--name`	string	no	Human-readable name
`-H/--hostname`	string	no	Hostname portion of FQDN
`-d/--domain`	string	no	Domain portion of FQDN
`-f/--fqdn`	string	no	Full FQDN
`-e/--enabled`	flag	no	Enable the endpoint
`-u/--user`	string	no	BMC username
`-p/--password`	string	no	BMC password
`-U/--use-ssdp`	flag	no	Use SSDP for discovery
`-m/--mac-required`	flag	no	Require MAC for geolocation
`-M/--macaddr`	string	no	MAC address (colon-separated)
`-I/--ipaddress`	string	no	IP address (IPv4 or IPv6)
`-r/--rediscover-on-update`	flag	no	Trigger rediscovery on update
`-t/--template-id`	string	no	Discovery template ID

apply

Apply changes to the system.

apply sat-file

Process a SAT (System Admin Toolkit) file. This is the primary workflow for deploying configurations, building images, and applying session templates.

Flag	Type	Required	Default	Description
`-t/--sat-template-file`	path	yes	—	SAT file path (may be a Jinja2 template)
`-f/--values-file`	path	no	—	Jinja2 values file
`-V/--values`	string…	no	—	Inline Jinja2 values; overrides `--values-file`
`--create-bos-session`	flag	no	—	After each BOS session template is created, create a BOS session from it so its target nodes boot via the new template (typically a reboot)
`-v/--ansible-verbosity`	1–4	no	`2`	Ansible verbosity level
`-P/--ansible-passthrough`	string	no	—	Extra Ansible parameters (`--extra-vars`, `--forks`, etc.)
`-o/--overwrite-configuration`	flag	no	—	Overwrite existing CFS configurations
`-w/--watch-logs`	flag	no	—	Stream Ansible logs to stdout while each image builds (default: poll image-build status every 10s instead)
`-T/--timestamps`	flag	no	—	Include timestamps in log output
`-i/--image-only`	flag	no	—	Process only `configurations` + `images` sections
`-s/--sessiontemplate-only`	flag	no	—	Process only `configurations` + `session_templates` sections
`-p/--pre-hook`	string	no	—	Shell command to run before processing
`-a/--post-hook`	string	no	—	Shell command to run on success
`-y/--assume-yes`	flag	no	—	Non-interactive mode
`-d/--dry-run`	flag	no	—	Simulate without making changes

manta apply sat-file -t my-cluster.yaml -f values.yaml --watch-logs
manta apply sat-file -t deploy.yaml -i   # configurations + images only
manta apply sat-file -t deploy.yaml -s   # configurations + session templates only

No server-side pre-flight. Validation is client-side only: dangling image_ref references and image cycles fail before anything is sent. There is no whole-file check against live CFS / IMS / cray-product-catalog state — POST /sat-file/validate was removed in f9160d26. Anything that depends on live backend state surfaces on the first per-element call, which means a SAT file can fail partway through with earlier elements already applied.

When --dry-run is combined with --create-bos-session, the per-template apply now returns a mock BOS session (no status, name prefixed dry-run-) for each session_template so the operator can preview the BOS sessions that would have been kicked off — no real session is persisted.

After each image is built, manta auto-stamps the CFS provenance onto the IMS image's metadata map as manta.image_session.{base,groups,configuration}. See GUIDE.md §3 for details. Skipped on --dry-run.

apply template

Create a BOS session from an existing BOS session template.

Flag	Type	Required	Default	Description
`-t/--template`	string	yes	—	BOS session template name
`-l/--limit`	string	yes	—	Comma-separated nodes, groups, or roles
`-n/--name`	string	no	—	Session name
`-o/--operation`	string	no	`reboot`	`reboot`, `boot`, or `shutdown`
`-i/--include-disabled`	flag	no	—	Include disabled nodes
`-d/--dry-run`	flag	no	—	Simulate without changes

manta apply template -t my-template -l compute --operation reboot

apply boot group <GROUP_NAME>

Update boot parameters (image + runtime config + kernel parameters) for all nodes in an HSM group.

Arg/Flag	Type	Required	Description
`GROUP_NAME`	string	yes	HSM group name
`-i/--boot-image`	string	no*	Specific IMS image ID
`-b/--boot-image-configuration`	string	no*	CFS configuration name to derive boot image from
`-r/--runtime-configuration`	string	no	CFS configuration for post-boot configuration
`-k/--kernel-parameters`	string	no	Kernel parameters string
`-d/--dry-run`	flag	no	Simulate without changes
`-o/--output`	string	no	Output format: `table`, `json` (default `table`)

--boot-image and --boot-image-configuration are mutually exclusive.

manta apply boot group compute -b csm-config-2024 -r csm-config-2024

apply boot nodes <VALUE>

Update boot parameters for specific nodes.

Arg/Flag	Type	Required	Description
`VALUE`	string	yes	Comma-separated xnames/nids or hostlist expression
`-i/--boot-image`	string	no*	Specific IMS image ID
`-b/--boot-image-configuration`	string	no*	CFS configuration name
`-r/--runtime-configuration`	string	no	Post-boot CFS configuration
`-k/--kernel-parameters`	string	no	Kernel parameters
`-d/--dry-run`	flag	no	Simulate without changes

apply boot-parameters

Update existing BSS boot parameters for nodes — set the kernel command line, kernel image, and/or initrd that nodes use on next boot.

Flag	Type	Required	Description
`-H/--hosts`	string	yes	Comma-separated xnames
`-p/--params`	string	no	Kernel parameters
`-k/--kernel`	string	no	S3 path to kernel file
`-i/--initrd`	string	no	S3 path to initrd file
`-d/--dry-run`	flag	no	Simulate without changes

apply redfish-endpoint

Update an existing Redfish endpoint (network/auth/discovery fields). Accepts the same flags as add redfish-endpoint; -i/--id is required to identify the entry.

apply kernel-parameters <VALUE>

Replace kernel parameters for nodes (full replace, not merge).

Arg/Flag	Type	Required	Description
`VALUE`	string	yes	Space-separated `key=value` pairs
`-n/--nodes`	string	no*	Target nodes (xnames/nids/hostlist)
`-H/--group`	string	no*	Target HSM group
`-d/--dry-run`	flag	no	Simulate without changes

To merge parameters instead of replacing, use add kernel-parameters.

apply ephemeral-environment

Launch a temporary container environment from an IMS image, useful for image inspection and debugging.

Flag	Type	Required	Description
`-i/--image-id`	string	yes	IMS image ID to use as the container image
`-d/--dry-run`	flag	no	Simulate without changes (prints the `CreateEphemeralEnvRequest` payload; works without a TTY)
`-o/--output`	string	no	Output format: `table`, `json` (honored on dry-run)

apply hardware group (WIP)

Upscale or downscale hardware resources in an HSM group.

The old flag spellings (--target-cluster, --parent-cluster, --create-target-hsm-group, --delete-empty-parent-hsm-group) still work as visible aliases on the new flag names below.

Flag	Type	Required	Description
`-P/--pattern`	string	yes	Hardware pattern e.g. `a100:12:epyc:5`
`-t/--target-group`	string	yes	Group being reconfigured
`-p/--parent-group`	string	yes	Group offering or receiving freed resources
`-d/--dry-run`	flag	no	Simulate without changes
`-c/--create-target-group`	flag	no	Create target group if it does not exist
`-D/--delete-empty-parent-group`	flag	no	Delete parent group if it becomes empty
`-u/--unpin-nodes`	flag	no	Allow any available nodes instead of pinned ones
`-o/--output`	string	no	Output format: `table`, `json` (default `table`)

run

Create and run jobs against the backend.

run session

Create and run a CFS session from one or more local git repositories.

Flag	Type	Required	Default	Description
`-n/--name`	string	yes	—	Session name
`-r/--repo-path`	path…	yes	—	Path(s) to local git repos (repeatable)
`-H/--group`	string	one of†	—	Run the session against every node in this HSM group
`-l/--ansible-limit`	string	one of†	—	Limit to specific xnames (must be a subset of `--group` if both given)
`-p/--playbook-name`	string	no	`site.yml`	Ansible playbook filename
`-w/--watch-logs`	flag	no	—	Stream session logs
`-t/--timestamps`	flag	no	—	Show timestamps in logs
`-v/--ansible-verbosity`	0–4	no	`2`	Ansible verbosity
`-P/--ansible-passthrough`	string	no	—	Extra Ansible parameters
`-d/--dry-run`	flag	no	—	Simulate without changes (still runs `git2` on the local repos so the preview shows the resolved commit IDs; skips both confirmation prompts)
`-o/--output`	string	no	`table`	Output format: `table`, `json`

† At least one of --group / --ansible-limit must be set.

manta run session -n my-session -r ~/repos/csm-config --group compute
manta run session -n my-session -r ~/repos/csm-config -l x3000c0s1b0n0

delete

Remove resources from the system.

delete group <VALUE>

Delete an HSM group. The group must be empty first.

Arg/Flag	Type	Required	Description
`VALUE`	string	yes	Group name
`-f/--force`	flag	no	Force deletion

delete node <VALUE>

Remove a node from HSM entirely. Distinct from delete nodes (plural), which removes nodes from a group's membership without touching the inventory.

Arg/Flag	Type	Required	Description
`VALUE`	string	yes	Node xname

delete nodes

Remove nodes from an HSM group's membership. Distinct from delete node (singular), which removes the node from the system inventory entirely.

Replaces the removed manta remove-nodes-from-groups top-level command.

Flag	Type	Required	Description
`-g/--group`	string	yes	Group to remove the nodes from
`-n/--nodes`	string	yes	Nodes to remove (xnames/nids/hostlist)
`-d/--dry-run`	flag	no	Simulate without changes
`-o/--output`	string	no	Output format: `table`, `json` (default `table`)

delete configurations

Delete CFS configurations and all derivatives (sessions, BOS templates, IMS images).

Flag	Type	Description
`-n/--configuration-name`	string	Glob pattern for configuration name
`-s/--since`	date	Delete configs updated after this date (`YYYY-MM-DD`)
`-u/--until`	date	Delete configs updated before this date

--since and --until must be used together.
--configuration-name and date range are mutually exclusive.

manta delete configurations --configuration-name "old-config-*"
manta delete configurations --since 2024-01-01 --until 2024-06-01

delete session <SESSION_NAME>

Delete a CFS session. For image sessions, the associated IMS image is also deleted.

Arg/Flag	Type	Required	Description
`SESSION_NAME`	string	yes	Session name
`-y/--assume-yes`	flag	no	Non-interactive mode
`-d/--dry-run`	flag	no	Simulate without changes

delete images <IMAGE_LIST> (WIP)

Delete IMS images.

Arg/Flag	Type	Required	Description
`IMAGE_LIST`	string	yes	Comma-separated image IDs
`-d/--dry-run`	flag	no	Simulate without changes

delete kernel-parameters <VALUE>

Remove specific kernel parameters from nodes.

Arg/Flag	Type	Required	Description
`VALUE`	string	yes	Comma-separated parameter names to remove
`-n/--nodes`	string	no*	Target nodes (xnames/nids/hostlist)
`-H/--group`	string	no*	Target HSM group
`-d/--dry-run`	flag	no	Simulate without changes

One of --nodes or --group is required.

delete boot-parameters

Delete BSS boot parameters for nodes.

Flag	Type	Description
`-H/--hosts`	string	Comma-separated xnames

delete hardware (WIP)

Remove hardware components from a group, returning them to the parent pool.

Flag names below are the canonical group-centric form; the old --target-cluster, --parent-cluster, --delete-hsm-group spellings continue to work as visible aliases.

Flag	Type	Description
`-P/--pattern`	string	Hardware pattern
`-t/--target-group`	string	Group losing resources
`-p/--parent-group`	string	Group receiving freed resources
`-d/--dry-run`	flag	Simulate without changes
`-D/--delete-group`	flag	Delete the target group if it becomes empty

delete redfish-endpoint

Delete a registered Redfish endpoint.

Flag	Type	Required	Description
`-i/--id`	string	yes	Xname of the endpoint

migrate

Move compute nodes between HSM groups.

Backup/restore for virtual clusters has moved to the top-level backup and restore verbs. The old manta migrate vCluster backup / restore forms still work for one release but print a deprecation warning on use.

migrate nodes <XNAMES>

Move compute nodes from one HSM group to another.

Arg/Flag	Type	Required	Description
`XNAMES`	string	yes	Xnames/nids or hostlist expression
`-t/--to`	string	yes	Destination HSM group
`-f/--from`	string	no	Source HSM group
`-d/--dry-run`	flag	no	Simulate without changes

manta migrate nodes 'x3000c0s1b0n[0-3]' --to gpu-cluster --from nodes_free

backup

Back up cluster state. Replaces manta migrate vCluster backup.

backup vcluster

Backup a virtual cluster's full configuration (BOS, CFS, IMS image, HSM group).

Flag	Type	Description
`-b/--bos`	string	BOS session template name
`-d/--destination`	dir	Destination folder for backup files
`-p/--pre-hook`	string	Shell command to run before backup
`-a/--post-hook`	string	Shell command to run after backup
`-o/--output`	string	Output format: `table`, `json` (default `table`)

restore

Restore cluster state from a backup. Replaces manta migrate vCluster restore.

restore vcluster

Restore a virtual cluster from backup files.

Flag	Type	Description
`-b/--bos-file`	path	BOS session template backup file
`-c/--cfs-file`	path	CFS configuration backup file
`-j/--hsm-file`	path	HSM group description backup file
`-m/--ims-file`	path	IMS backup file
`-i/--image-dir`	dir	Directory containing image files
`-p/--pre-hook`	string	Shell command before restore
`-a/--post-hook`	string	Shell command after restore
`-o/--overwrite`	flag	Overwrite existing data
`-d/--dry-run`	flag	Simulate without changes (still validates hook permissions; skips hook execution and the POST)
`--output`	string	Output format: `table`, `json` (default `table`)

power

Manage node power state.

Every power on/off/reset invocation first POSTs to the manta server, which kicks off a PCS transition and returns the transition id immediately. The CLI then polls the snapshot endpoint every 3 seconds (up to 15 minutes) and prints a one-line progress summary on each poll (status: …, failed: …, in-progress: …, succeeded: …, total: …). The command exits non-zero if any task in the transition failed. Pass --no-wait to skip the polling — the transition id is printed and the command exits 0.

power on group <GROUP_NAME>

Power on all nodes in an HSM group.

Arg/Flag	Type	Default	Description
`GROUP_NAME`	string	—	HSM group name
`-R/--reason`	string	—	Reason for the power action
`-y/--assume-yes`	flag	—	Non-interactive mode
`--no-wait`	flag	—	Return the transition id immediately; don't poll for completion
`-d/--dry-run`	flag	—	Simulate without changes (skips both the confirmation prompt and the BMC dispatch)
`-o/--output`	string	`table`	Output format: `table`, `json`

power on nodes <VALUE>

Power on specific nodes.

Arg/Flag	Type	Default	Description
`VALUE`	string	—	Xnames/nids or hostlist expression
`-y/--assume-yes`	flag	—	Non-interactive mode
`--no-wait`	flag	—	Return the transition id immediately; don't poll for completion
`-d/--dry-run`	flag	—	Simulate without changes (skips both the confirmation prompt and the BMC dispatch)
`-o/--output`	string	`table`	Output format: `table`, `json`

power off group <GROUP_NAME> / power off nodes <VALUE>

Power off nodes.

Arg/Flag	Type	Description
`-g/--graceful`	flag	Graceful shutdown
`-R/--reason`	string	Reason for power-off (group only)
`-y/--assume-yes`	flag	Non-interactive mode
`--no-wait`	flag	Return the transition id immediately; don't poll for completion
`-d/--dry-run`	flag	Simulate without changes (skips both the confirmation prompt and the BMC dispatch)
`-o/--output`	string	Output format: `table`, `json`

power reset group <GROUP_NAME> / power reset nodes <VALUE>

Power-cycle nodes.

Arg/Flag	Type	Description
`-g/--graceful`	flag	Graceful reset
`-r/--reason`	string	Reason (group only)
`-y/--assume-yes`	flag	Non-interactive mode
`--no-wait`	flag	Return the transition id immediately; don't poll for completion
`-d/--dry-run`	flag	Simulate without changes (skips both the confirmation prompt and the BMC dispatch)
`-o/--output`	string	Output format: `table`, `json`

manta power off group compute --graceful --assume-yes
manta power on group compute
manta power reset nodes 'x3000c0s1b0n[0-3]' --graceful
# Fire-and-forget — useful when the operator wants to do other work
# while the cluster transitions and check back later:
manta power reset group compute --no-wait

log [VALUE]

Stream CFS session logs. Also available as the alias manta logs.

Arg/Flag	Type	Description
`VALUE`	string	Session name, group name, xname, or NID (interactive picker if omitted)
`-t/--timestamps`	flag	Show timestamps in log output

manta log my-session
manta log my-session --timestamps

console

console node <XNAME>

Open an interactive console to a node (identified by xname or NID).

manta console node x3000c0s1b0n0

console target-ansible <SESSION_NAME>

Open an interactive shell in the Ansible target container of a running CFS session. Useful for debugging in-progress sessions.

manta console target-ansible my-session

gen-autocomplete

Generate and install the shell completion script. By default the script lands in the shell's standard XDG user directory:

Shell	Default install path
bash	`$XDG_DATA_HOME/bash-completion/completions/manta`
zsh	`$XDG_DATA_HOME/zsh/site-functions/_manta`
fish	`$XDG_CONFIG_HOME/fish/completions/manta.fish`

Flag	Type	Description
`-s/--shell`	string	`bash`, `zsh`, `fish` (auto-detected from `$SHELL` if omitted)
`-p/--path`	dir	Override the default install directory
`--print`	flag	Emit to stdout instead of installing (mutually exclusive with `--path`)
`-o/--output {table,json}`	enum	Format the result message (default `table`)

manta gen-autocomplete --shell zsh                          # install to default
manta gen-autocomplete --shell bash --path /etc/bash_completion.d
manta gen-autocomplete --shell zsh --print > _manta         # capture to file
eval "$(manta gen-autocomplete --shell zsh --print)"        # load dynamically

For zsh the install message includes a $fpath setup hint — the directory needs to be on $fpath before compinit runs. bash (with bash-completion loaded) and fish auto-load from the XDG paths above, so no extra setup is required after install.

gen-man

Generate a single consolidated manta.1 man page from the running binary's clap tree and write it into a directory. Useful when you installed manta via the shell installer (or built from source) and want man manta to work locally without juggling source-tree paths. The page has a SUBCOMMANDS section with one entry per (sub)subcommand, so /<verb> inside the page jumps to the relevant flag table.

Flag	Type	Description
`-p/--path`	dir	Target directory; defaults to `$XDG_DATA_HOME/man/man1` (i.e. `~/.local/share/man/man1`) when omitted
`-o/--output {table,json}`	enum	Format the result message (default `table`)

manta gen-man
manta gen-man --path ~/.local/share/man/man1
manta gen-man --output json

On Linux the default user man directory (~/.local/share/man) is searched by man automatically. On macOS you may need to add it to MANPATH:

export MANPATH="$HOME/.local/share/man:$MANPATH"

upgrade

Replace this manta binary with the latest release. Fetches the highest v* workspace tag (filtered to the same major version as the running binary) from https://github.com/eth-cscs/manta/releases, compares against the running version, downloads the right platform tarball, and atomically swaps the binary in place. The manta-server is untouched — server installs are infrastructure-managed.

Flag	Description
`-c/--check`	Check for a newer version and print it, but don't apply
`-d/--dry-run`	Show what would happen without downloading or replacing
`-y/--assume-yes`	Skip the confirmation prompt
`-o/--output {table,json}`	Format the version-info output (default is a few human-readable lines; `json` emits the standard `{"status":"ok","message":"…","data":…}` envelope)

manta upgrade --check
manta upgrade --dry-run
manta upgrade -y --output json
manta upgrade

Default output looks like:

Already up to date (v2.0.0).
  current: v2.0.0
  latest:  v2.0.0
  target:  aarch64-apple-darwin

If you installed manta via Homebrew, prefer brew upgrade manta-cli — manta upgrade will warn (but not block) when it detects a Homebrew-managed install path.

Node expressions

Most commands that accept node lists support three formats interchangeably:

Format	Example
Single xname	`x3000c0s1b0n0`
Single NID	`nid001313`
Comma-separated	`x3000c0s1b0n0,x3000c0s1b0n1`
Hostlist expression	`x3000c0s1b0n[0-3]`, `nid00131[0-9]`

Uh oh!

FilesExpand file tree

CLI.md

Latest commit

History

CLI.md

File metadata and controls

Manta CLI Reference

TL;DR

Migrating from earlier shapes

config

config show

config set hsm <HSM_GROUP_NAME>

config set site <SITE_NAME>

config set log <LOG_LEVEL>

config unset hsm

config unset auth

get

get groups [VALUE]

get hardware group <GROUP_NAME>

get hardware nodes <VALUE>

get sessions

get configurations

get templates

get group-nodes <GROUP_NAME>

get nodes <VALUE>

get images

get analysis image

get analysis configuration

get boot-parameters

get kernel-parameters

get redfish-endpoints

add

add group

add node

add nodes

add hardware (WIP)

add boot-parameters

add kernel-parameters <VALUE>

add redfish-endpoint

apply

apply sat-file

apply template

apply boot group <GROUP_NAME>

apply boot nodes <VALUE>

apply boot-parameters

apply redfish-endpoint

apply kernel-parameters <VALUE>

apply ephemeral-environment

apply hardware group (WIP)

run

run session

delete

delete group <VALUE>

delete node <VALUE>

delete nodes

delete configurations

delete session <SESSION_NAME>

delete images <IMAGE_LIST> (WIP)

delete kernel-parameters <VALUE>

delete boot-parameters

delete hardware (WIP)

delete redfish-endpoint

migrate

migrate nodes <XNAMES>

backup

backup vcluster

restore

restore vcluster

power

power on group <GROUP_NAME>

power on nodes <VALUE>

power off group <GROUP_NAME> / power off nodes <VALUE>

power reset group <GROUP_NAME> / power reset nodes <VALUE>

log [VALUE]

console

console node <XNAME>

console target-ansible <SESSION_NAME>

gen-autocomplete

gen-man