How to get accurate information about disk space used/available in Big Sur via the command line

Summary:

I would like to be able to tell how much disk space I have used and how much I have available (in GB) in Big Sur in a simple format suitable for parsing in a shell script or similar.

Details

Finder reports that my internal SSD is 995 GB and has 568 GB free.

Simple math tells us that means I have used 427 GB.

So… how can I get 568 GB and/or 427 GB from the command line?

Hint: The answer is not df

If I do df -H / I will get this result (truncated for readability and to just the parts of the output we care about):

Filesystem       Size   Used  Avail Capacity
/dev/disk3s1s1   995G    15G   528G     3%

15G might be how much the read-only volume takes up, but the “available” amount is off by 40G.

Of course we know that there’s now a separate ‘Data’ volume. So let’s check that using df -H /System/Volumes/Data:

Filesystem     Size   Used  Avail Capacity
/dev/disk3s5   995G   445G   528G    46%

445G used is relatively close to the actual amount of 427G but if you add up the “Used” (445G) and “Available” (528G) you get 973G.

There must be some way to do it…

I have noticed that other apps such as iStat Menus and MakeMKV are both able to display accurate information about the remaining disk space. So it’s not as if the system is incapable of revealing this information.

If there is another tool besides df that can do this, please let me know.

Bonus points if it comes standard with macOS (bash, zsh, python, ruby, whatever), but if it can be installed via brew or similar, I’ll take it.

What I’m asking for seems very simple, but I can’t figure out how to do it.

p.s. – yes, I’m aware of macOS’ features about “purgeable space” and all that. Not interested. I just want to be able to get the same numbers shown in Finder, iStat Menus, etc. from the command line.