I would go so far as to say that you're foolish if you don't do this on a Mac – it's a best-practice kind of thing.
Rule-of-the-thumb – always use $HOME-based (tilde) paths when possible – this makes them safer and more portable.
Keyboard Maestro's own actions understand the tilde-path notation perfectly well.
But...
If you're going to use the variable later in a shell script – always follow the Set Variable to Text action with with a Filter Variable ‘yourVariable’ with Expand Tilde In Path action.
When writing shell scripts that utilize a tilde-path with spaces in it the path string must be quoted appropriately:
~/'Downloads/test file with spaces in file name.txt'
You cannot quote the ~/ portion of the path string, but you can quote the entire string after that.
For me personally this reads much better than escaping the spaces.
The shell script:
myPathStr=~/'Downloads/test file with spaces in file name.txt'
echo "$myPath"
Outputs:
/Users/yourUserName/Downloads/test file with spaces in file name.txt
The shell interprets the tilde-path at the time the assignment of variable myPathStr takes place, so the variable itself never sees the tilde part of the string.
This interpolation cannot happen if the path string is already in a variable – as in the case of an assigned Keyboard Maestro variable.
So if your myPathStr variable in Keyboard Maestro is assigned a string like this:
~/Downloads/test file with spaces in file name.txt
cat "$KMVAR_myPathStr"
Will fail.
So use that tilde-expansion filter in your macro.
On the other hand if you just have to make the tilde-path work in the shell it can be done (in Bash at least) by using Bash parameter expansion (and other methods):
cat "${KMVAR_myPathStr/#\~/$HOME}"
For more information see:
How to manually expand a special variable (ex: ~ tilde) in bash
-Chris