truenas-middleware

name

truenas-middleware

description

Discover and use the live TrueNAS middleware method surface instead of guessing. Use this whenever a TrueNAS task needs a midclt method that is not in capabilities/truenas.md, whenever Evan asks about the TrueNAS API, the middleware, midclt, "what can the API do", available methods, or method parameters, or whenever a midclt call fails with an unknown-method or bad- argument error. Trigger this to look up the real methods, their exact names, and their parameter schemas on THIS box rather than relying on the static catalog. Prefer this over guessing method names for anything beyond the common operations already documented.

TrueNAS middleware introspection

capabilities/truenas.md is the fast path for common work. This skill is for everything beyond it: the middleware exposes many hundreds of methods, and their names, parameters, and return shapes vary by TrueNAS version. Do not guess. Read them off the actual box.

All commands run through the broker, e.g. hh run truenas "<command>". midclt talks to the middleware and is the preferred way to read and change TrueNAS: it covers pools, datasets, disks, apps, shares, and more. TrueNAS ships python3 (the middleware is python), so python3 is the reliable JSON parser; jq may or may not be present, so check with command -v jq before relying on it.

List the methods that actually exist

# every method name on this box, sorted
midclt call core.get_methods | python3 -c "import json,sys;[print(k) for k in sorted(json.load(sys.stdin))]"

# only a namespace you care about (e.g. everything under 'pool')
midclt call core.get_methods | python3 -c "import json,sys;[print(k) for k in sorted(json.load(sys.stdin)) if k.startswith('pool')]"

Namespaces are regular: pool.*, pool.dataset.*, pool.snapshottask.*, app.*, service.*, interface.*, sharing.smb.*, replication.*, disk.*, system.*, virt.instance.*, and so on. Filter by the prefix that matches the task.

Inspect a method BEFORE you call it

For any state-changing method, look up its accepts schema so you pass the right arguments, then confirm with Evan before running it.

# description + accepted arguments + return shape for one method
midclt call core.get_methods | python3 -c "import json,sys,pprint;pprint.pprint(json.load(sys.stdin).get('pool.dataset.create'))"

The accepts field is the JSON schema for the arguments; returns is what comes back. Read accepts to build the call correctly.

Calling methods

Arguments are passed as JSON positional args:

# read-only query with a filter (safe)
midclt call pool.dataset.query '[["name","=","tank/media"]]'

# a method that takes an object argument
midclt call service.restart '"cifs"'

Long-running operations are jobs. Add -j so midclt waits for completion and returns the result instead of just a job id:

midclt call -j pool.scrub '{"pool": "tank", "action": "START"}'

Read vs write

Safe to run freely (read-only): anything ending in .query, .config, .get_instance, .info, and the core.get_* introspection methods.

State-changing (inspect the schema first, then confirm before running): verbs like .create, .update, .delete, .start, .stop, .restart, .scrub, .export, .replace, .wipe. Treat pool, dataset, disk, and replication writes as high-risk and never run them without an explicit go-ahead, per the house rules in CLAUDE.md.

Fallbacks

If core.get_methods is unavailable on a given version, midclt call core.get_services lists service namespaces, and the box also serves interactive API docs at https://<truenas-host>/api/docs for a human to browse. Stay on the SSH + midclt path; do not add API keys or network API calls.

Credentials stay off-limits

As always, never read, print, or exfiltrate credentials, and never target the vault. Introspection is about methods, not secrets.