qnap

A CLI for QNAP NAS management. It is designed for both interactive use and automation: human-friendly tables by default, stable JSON contracts on inspection commands, and a schema command for agent introspection.

Supported platforms: Linux and macOS.

Installation

cargo install qnap

# Or run from PyPI without installing
uvx qnap-cli --help

The PyPI package provides both qnap and qnap-cli as executable names.

Or build from source:

git clone https://github.com/rvben/qnap-cli
cd qnap-cli
make install

Quick Start

# Save connection settings and password
qnap login --host nas.local --username admin

# Inspect the NAS
qnap info
qnap status
qnap volumes
qnap shares
qnap files ls /Public

# Structured output for automation
qnap status --json
qnap files stat /Public/example.txt --json

Commands

Global Flags

These flags work on every authenticated command, including login.

Examples:

printf '%s\n' 'secret-password' | qnap --password-stdin info
qnap --host https://nas.local --username admin status
qnap --secure volumes --json

Authentication

qnap login [--host <HOST>] [--username <USERNAME>] [--insecure | --secure]

qnap login verifies the credentials before saving anything. Host, username, and the saved TLS verification preference are stored in config.toml. The password is stored separately in credentials.toml.

The CLI requires HTTPS. Plain http:// targets are rejected. If your NAS uses a self-signed certificate, use --insecure or QNAP_INSECURE=1 explicitly.

If you do not want local password persistence, skip qnap login and provide QNAP_HOST, QNAP_USERNAME, and QNAP_PASSWORD directly when running commands.

JSON Output

The following commands support --json with stable, typed output:

• info
• status
• volumes
• shares
• files ls
• files stat

Highlights:

• status --json uses numeric fields such as cpu_usage_pct, mem_total_mb, and temp_c.
• volumes --json includes status_code, pool_id, and per-disk temp_c.
• shares --json uses items_count as a number.
• files ls --json uses size_bytes and modified_epoch.
• files stat --json returns normalized fields plus a raw object for unnormalized QNAP metadata.

Use qnap schema for the full machine-readable command and output contract.

Environment Variables

Environment variables override local files.

Stored Files

config.toml stores host, username, and TLS verification preference. credentials.toml stores the password separately in plaintext on the local machine.

Security

• Passwords are never accepted as CLI flags.
• HTTPS is required for NAS connections.
• TLS verification is enabled by default.
• credentials.toml is written atomically.
• On Unix, credentials.toml is restricted to owner-only (0600) permissions.
• On Unix, the config directory is tightened to owner-only (0700) permissions.
• Symlink and non-regular-file credential targets are rejected.
• If you do not want local password persistence, use environment variables or --password-stdin.

Shell Completions

Generate and install completions for your shell:

# Zsh — add to ~/.zshrc or drop in a $fpath directory
qnap completions zsh > ~/.zfunc/_qnap
echo 'fpath=(~/.zfunc $fpath)' >> ~/.zshrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc

# Bash
qnap completions bash > /etc/bash_completion.d/qnap
# or for a user install:
qnap completions bash > ~/.local/share/bash-completion/completions/qnap

# Fish
qnap completions fish > ~/.config/fish/completions/qnap.fish

Compatibility

Tested against QTS 5.1.x and 5.2.x. The core authentication and file manager APIs have been stable since QTS 4.3, but qnap dump is the recommended way to capture compatibility issues from older or unusual firmware builds.

License

MIT

Releasing

Vership owns versioning, changelog generation, release commits, and tags. See the release runbook for the verified workflow and recovery policy.