# How to Use nydusctl for Managing Nydus Resources: Complete CLI and API Guide

> Master nydusctl to manage Nydus resources effectively. Explore the complete CLI and API guide for daemon status, configuration, metrics, and mount operations.

- Repository: [dragonflyoss/nydus](https://github.com/dragonflyoss/nydus)
- Tags: how-to-guide
- Published: 2026-02-28

---

**`nydusctl` is a lightweight command-line interface that communicates with the nydusd daemon over Unix-domain sockets to query daemon status, modify runtime configuration, collect performance metrics, and manage filesystem mount operations.**

`nydusctl` serves as the primary management interface for the Nydus container image acceleration framework in the dragonflyoss/nydus repository. This Rust-based CLI translates user-friendly sub-commands into HTTP-like API calls against the daemon's REST interface, providing direct access to nydusd internals without requiring custom HTTP clients. Whether debugging performance issues or automating container workflows, understanding how to use `nydusctl` effectively is essential for production Nydus deployments.

## Architecture and Core Components

The `nydusctl` binary consists of three primary Rust modules that handle argument parsing, API communication, and command execution.

### CLI Entry Point and Command Dispatch

In [`src/bin/nydusctl/main.rs`](https://github.com/dragonflyoss/nydus/blob/main/src/bin/nydusctl/main.rs), the application uses **Clap** to parse global flags and sub-commands. The dispatcher instantiates command structs from [`commands.rs`](https://github.com/dragonflyoss/nydus/blob/main/commands.rs) based on user input, handling the `--sock` and `--raw` global options before executing the requested operation.

### The HTTP Client Layer

The [`src/bin/nydusctl/client.rs`](https://github.com/dragonflyoss/nydus/blob/main/src/bin/nydusctl/client.rs) module implements **NydusdClient**, a thin wrapper around hyper that constructs Unix-socket URIs targeting `/api/*` endpoints. All commands use `NydusdClient::new(sock_path)` to establish communication channels, supporting GET, PUT, POST, and DELETE operations via `hyperlocal::Uri::new`.

### Command Implementations

Concrete business logic resides in [`src/bin/nydusctl/commands.rs`](https://github.com/dragonflyoss/nydus/blob/main/src/bin/nydusctl/commands.rs), which implements:
- **CommandDaemon** – Daemon status and information queries
- **CommandBackend** – Storage backend metrics collection
- **CommandCache** – Cache performance statistics
- **CommandFsStats** – Filesystem-level metrics
- **CommandMount** – Filesystem mounting operations
- **CommandUmount** – Filesystem unmounting operations

## Essential nydusctl Commands and Usage Patterns

The general invocation pattern requires specifying the daemon socket and optionally requesting raw JSON output:

```bash
nydusctl --sock <socket_path> [--raw] <subcommand> [options]

```

### Connecting to the Daemon (--sock)

The `--sock` (or `-S`) parameter specifies the Unix-domain socket path where nydusd listens for API requests. While defaults vary by installation, system-wide daemons typically use `/var/run/nydusd.sock`. This path is passed to `NydusdClient::new()` in [`client.rs`](https://github.com/dragonflyoss/nydus/blob/main/client.rs) to establish the connection.

### Querying Daemon State with info

The `info` sub-command queries the `v1/daemon` endpoint to retrieve version information, current state, and lists of mounted instances. Implemented in `CommandDaemon` within [`commands.rs`](https://github.com/dragonflyoss/nydus/blob/main/commands.rs), this command requires no additional arguments:

```bash
nydusctl -S /var/run/nydusd.sock info

```

### Runtime Configuration with set

Use the `set` sub-command to adjust daemon parameters at runtime without restarting. Currently, this supports modifying the **log-level** through the `CommandDaemon` implementation:

```bash
nydusctl -S /var/run/nydusd.sock set log-level debug

```

Valid log levels include `trace`, `debug`, `info`, `warn`, and `error`.

### Monitoring Performance with metrics

The `metrics` sub-command retrieves runtime statistics through three distinct categories implemented in separate command structs:

- **backend** (`CommandBackend`) – Storage backend latency and throughput metrics
- **cache** (`CommandCache`) – Prefetch statistics and cache hit rates
- **fsstats** (`CommandFsStats`) – Filesystem operation counters

For backend metrics, use the `--interval` (or `-I`) flag to enable periodic polling:

```bash

# Single query

nydusctl -S /var/run/nydusd.sock metrics cache

# Periodic backend monitoring every 5 seconds

nydusctl -S /var/run/nydusd.sock metrics backend -I 5

```

### Managing Filesystems with mount and umount

The `mount` sub-command creates new Nydus filesystem instances by posting configuration to the daemon API:

```bash
nydusctl -S /var/run/nydusd.sock mount \
    --source registry:docker.io/library/busybox:latest \
    --config /etc/nydus/rafs.json \
    --mountpoint /mnt/rafs \
    --type rafs

```

Key parameters include:
- `--source` (or `-s`) – Backend source URI (e.g., `registry:`, `oss:`)
- `--config` (or `-c`) – JSON configuration file path for the backend
- `--mountpoint` (or `-m`) – Target directory for the mount
- `--type` (or `-t`) – Filesystem type: `rafs` (Registry Accelerated File System) or `passthrough_fs`

To remove a filesystem, use `umount` with the mountpoint:

```bash
nydusctl -S /var/run/nydusd.sock umount --mountpoint /mnt/rafs

```

## Practical Workflow Examples

A typical management session combines multiple `nydusctl` operations to verify daemon health, adjust logging, monitor performance, and manage workloads:

```bash

# Verify daemon responsiveness

nydusctl -S /var/run/nydusd.sock info

# Enable verbose logging for debugging

nydusctl -S /var/run/nydusd.sock set log-level trace

# Monitor cache performance during workload

nydusctl -S /var/run/nydusd.sock metrics cache

# Mount a production image

nydusctl -S /var/run/nydusd.sock mount \
    -s registry:myimage:latest \
    -c /etc/nydus/rafs-config.json \
    -m /mnt/nydus \
    -t rafs

# Poll backend bandwidth every 3 seconds

nydusctl -S /var/run/nydusd.sock metrics backend -I 3

# Cleanup after workload completion

nydusctl -S /var/run/nydusd.sock umount -m /mnt/nydus

```

## Programmatic Integration with NydusdClient

For automation beyond shell scripts, import `nydusctl` as a library to interact with the daemon directly from Rust:

```rust
use nydusctl::client::NydusdClient;
use anyhow::Result;

#[tokio::main]
async fn main() -> Result<()> {
    // Initialize client with socket path
    let client = NydusdClient::new("/var/run/nydusd.sock");
    
    // Query daemon information via v1/daemon endpoint
    let info = client.get("v1/daemon").await?;
    println!("Daemon state: {}", info["state"]);
    
    Ok(())
}

```

This approach leverages the same [`client.rs`](https://github.com/dragonflyoss/nydus/blob/main/client.rs) implementation used by the CLI, ensuring consistent API behavior.

### Shell Script Automation

Integrate `nydusctl` into bash workflows for health checks and conditional logic:

```bash
#!/usr/bin/env bash
SOCK="/var/run/nydusd.sock"

# Enable debug logging

nydusctl -S "$SOCK" set log-level debug

# Wait for daemon to reach Running state

while true; do
    STATE=$(nydusctl -S "$SOCK" info --raw | grep -o '"state":"[^"]*"' | cut -d'"' -f4)
    if [[ "$STATE" == "Running" ]]; then
        break
    fi
    sleep 1
done
echo "Nydusd is ready for mount operations"

```

## Summary

- **`nydusctl`** communicates with nydusd via Unix-domain sockets specified by `--sock`, defaulting to paths like `/var/run/nydusd.sock`.
- **Five primary sub-commands** manage the daemon lifecycle: `info` (status), `set` (configuration), `metrics` (monitoring), `mount` (filesystem creation), and `umount` (filesystem removal).
- **Raw JSON output** is available via the `--raw` flag, while default output provides human-readable tables formatted in [`commands.rs`](https://github.com/dragonflyoss/nydus/blob/main/commands.rs).
- **Three metrics categories** (`backend`, `cache`, `fsstats`) expose performance data, with backend metrics supporting interval-based polling via `-I`.
- **Programmatic access** is possible through the `NydusdClient` struct in [`src/bin/nydusctl/client.rs`](https://github.com/dragonflyoss/nydus/blob/main/src/bin/nydusctl/client.rs), which handles HTTP-like requests over Unix sockets using hyper.

## Frequently Asked Questions

### What socket path does nydusctl use by default?

While `nydusctl` requires explicit socket paths via `--sock` or `-S`, system-wide nydusd installations typically create `/var/run/nydusd.sock`. Containerized deployments may use alternative paths like `/nydus/api.sock` depending on volume mounts. Always verify the socket path matches your nydusd startup configuration.

### How do I view raw JSON output instead of formatted tables?

Append the `--raw` flag to any command to display the unprocessed JSON response from the daemon API. This bypasses the formatting logic in [`commands.rs`](https://github.com/dragonflyoss/nydus/blob/main/commands.rs) and outputs the exact `serde_json::Value` returned by endpoints like `v1/daemon` or the metrics API.

### Can nydusctl manage multiple daemon instances simultaneously?

Yes, by specifying different socket paths with `--sock` for each command invocation. Each `nydusctl` execution creates an independent `NydusdClient` connection, allowing you to query or configure multiple nydusd processes running on different sockets from the same host.

### What metrics categories are available in nydusctl?

The `metrics` sub-command accepts three category arguments implemented in [`commands.rs`](https://github.com/dragonflyoss/nydus/blob/main/commands.rs): `backend` (storage I/O latency and bandwidth), `cache` (prefetch statistics and hit ratios), and `fsstats` (filesystem operation counters). Only the `backend` category supports the `--interval` flag for continuous polling.