pytruenas 0.3.0

A typed, Pythonic client and CLI for the TrueNAS middleware API

pytruenas

A typed, Pythonic client and CLI for the TrueNAS middleware API.

pytruenas speaks the middleware's JSON-RPC 2.0 websocket protocol directly — over wss:///ws:// to a remote host, or over the local unix socket (ws+unix://) when running on the NAS itself. It exposes the whole API surface through an attribute-style namespace, adds convenience helpers for the common create/update/upsert patterns, a remote-filesystem abstraction, an optional typings generator, and a small CLI for scripting host configuration.

Running commands and reading files is delegated to hostctl: a client is a hostctl host, so run() and path() pick whichever transport a target actually offers rather than assuming one.

Install

pip install pytruenas

Optional extras:

Extra	Enables
pytruenas[ssh]	SSH commands + the SFTP filesystem leg (asyncssh)
pytruenas[config]	YAML config/targets file for the CLI (pyyaml)
pytruenas[codegen]	generate-typings command (jinja2)

Quickstart

from pytruenas import TrueNASClient

# Remote host (api key, or "user:password", or a token)
client = TrueNASClient("nas.example.com", "1-<64-char-api-key>", sslverify=False)

# Attribute-style access to any API namespace/method:
for user in client.api.user.query():
    print(user["username"])

# Convenience helpers for common DB patterns:
client.api.user._upsert("username", username="svc", full_name="Service", group_create=True)

# Running on the NAS itself talks to the local unix socket, no auth:
local = TrueNASClient()            # ws+unix:///var/run/middleware/middlewared.sock
print(local.api.system.info())

Commands and files

run() and path() are inherited from hostctl, which selects a transport rather than assuming one:

client = TrueNASClient("nas.example.com", api_key, shell="ssh://[e-mail]")

client.run("zpool status", capture_output="stdout", encoding="utf-8").stdout
client.path("/mnt/tank/notes.txt").read_text()

client.capabilities      # {"run", "path"} -- what this target can actually do
client.last_selection    # which transport served the last run(), and why

target	commands	files
on the NAS	local (plain subprocess)	local
remote, SSH configured	ssh, then webshell	sftp, then tnasws
remote, no SSH	webshell	tnasws

webshell runs commands over /websocket/shell — the same PTY the web UI's Shell page uses — so a host reachable on the API port but not on 22 (NAT, a firewall allowing only 443) can still run commands. Name providers explicitly with executor= / path= to force or exclude one.

Credentials

TrueNASClient(target, credentials) accepts, for the second argument:

• an API key string "<id>-<64 chars>",
• "user:password" (optionally "user:password\n<otp>"),
• a token string,
• a (user, password) tuple,
• None / omitted → local socket auth.

Credentials.from_env() reads TN_CREDS. Credentials may also travel in the target (wss://root:secret@nas); an OTP follows the password after a newline, percent-encoded in a URI as %0A.

CLI

pytruenas --help
pytruenas query user -f username=root nas.example.com
pytruenas call system.info nas.example.com          # any method by dotted name
pytruenas dump-api nas.example.com > api.json
pytruenas generate-typings --path typings --api-version v26.0.0 nas.example.com
pytruenas deploy nas.example.com                    # install pytruenas ON the host

The target host(s) are the trailing positional arguments — a command's own positionals (like query's namespace) come first, then the hosts. Each target may be comma-separated and supports [A-Z]/[0-9] range expansion (e.g. 'nas[1-3].example.com'); with no target the command runs against localhost. --parallel N runs several targets concurrently. Filter query with -f/--filter KEY=VALUE (repeatable).

Running on the appliance

TrueNAS has a read-only root and no pip, so deploy bootstraps instead: it asks the target which distributions it already has, bundles only the difference, and copies that over. In practice that is five pure-Python packages under a megabyte — the appliance already ships requests, websocket-client, pyyaml, asyncssh and jinja2.

pytruenas deploy nas.example.com                 # a single executable .pyz
pytruenas deploy --mode dir nas.example.com      # an unpacked bin/ + lib/ tree
pytruenas deploy nas.example.com -- call system.info   # install, then run there

Everything after -- runs on the target once it is installed. The default destination is under /var/db/system, which is a dataset on a data pool and so survives an update — unlike /var/db itself, /root or /data, which live in the boot environment and are replaced by one. A digest is recorded beside the payload, so redeploying verifies instead of re-copying; --force overrides.

When pytruenas is a dependency of your own tool rather than the thing being deployed, name yours as the root: --pkg-root mytool (or PYTRUENAS_PKG_ROOT), and your package ships with pytruenas bundled underneath it.

Typings generator

generate-typings turns a host's API definition into a package of .pyi stubs so editors and type checkers understand client.api.<namespace>.<method>(...). It is validated against the full real API (every version in a live dump).

pytruenas generate-typings --path truenasapi_typings/current nas.example.com

Development

py -3.14 -m venv .venv/3.14-nt-amd64
.venv/3.14-nt-amd64/Scripts/python -m pip install -e ".[dev,ssh,config,codegen]"
.venv/3.14-nt-amd64/Scripts/python -m pytest

Supports Python 3.9+. The run() tests need a POSIX shell and skip on Windows, so verify anything touching command or path dispatch on a real target.

License

MIT — see LICENSE.