defaults write on Mac: -bool 1 Fails, -int abc Writes 0

I ran defaults write cc.picklog.probe k -bool 1 on macOS 26.4.1. It printed the whole 44-line usage text to standard output, exited with code 255, and left the key unchanged. A minute later defaults write ... -int abc exited 0 and stored the integer 0. The first command looks like it should work, the second looks like it should fail, and they do the opposite.

The defaults write command on Mac is the tool behind half the "hidden setting" tips on the internet, and most of those tips are one line long with no exit code checked. So I wrote a throwaway preferences domain, cc.picklog.probe, and tried every value type, path form and edit path I could think of on a Mac mini M4 with /usr/bin/defaults from Foundation-4424.1.402. Here is what it actually stores, and why a setting you wrote sometimes does nothing.

What gets stored for each value

Without a type flag, defaults parses the value as an old-style property list. Almost everything becomes a string, but brackets and XML fragments do not:

Command (value part)	Exit	read-type	Stored
k 1, k yes, k true, k 1.5	0	string	the text as typed
k '(a, b)'	0	array	two strings, a and b
k '{a = b;}'	0	dictionary	a = "b"
k '<integer>7</integer>'	0	integer	7
-bool yes, YES, true, TRUE	0	boolean	1 (no, false: 0)
-bool 1, -bool maybe	255	(unchanged)	usage text on stdout
-int 3.7	0	integer	3
-int abc, -float abc	0	integer / float	0
-int 99999999999999999999	0	integer	9223372036854775807
-date 2026-10-16	0	date	2026-10-16 12:00:00 +0000
-date garbage, -data xyz	255	(unchanged)	usage text on stdout
-data 4865f (odd digit count)	0	data	3 bytes, 0x04865f
-dict a 1 b 2	0	dictionary	values are strings "1" and "2"
-dict a -int 1	0	dictionary	a = 1 (integer)
-dict a -array 1 2	1	(unchanged)	"Cannot nest composite types"

Three things in that table cause most of the trouble. First, a numeric setting written without -int is a string, and an app that asks for an integer gets nothing useful; check with defaults read-type, which prints Type is string. Second, the bad-input checks are uneven: a bad boolean, date or hex string is rejected, but a bad number is silently stored as 0, and a number too large for 64 bits is clamped. Third, a date with no time is stored at noon UTC, not midnight local time.

The 255 failures also print usage to standard output, not standard error, so 2>/dev/null does not hide them and a script capturing the output gets 44 lines of help text.

One failure was my own. In zsh, opts="-bool yes"; defaults write $D z $opts passes -bool yes as a single argument, because zsh does not split unquoted variables the way bash does. The command exited 0 and stored the string "-bool yes". If you build defaults arguments in a variable, use an array or ${=opts}.

Where the plist actually lands

The usage text says a domain can be "a path to a file omitting the '.plist' extension". On this Mac the extension rule is looser and the path rule is stricter than that:

• defaults write /Users/me/work/pf k v created /Users/me/work/pf.plist, and /Users/me/work/pf2.plist created pf2.plist, not pf2.plist.plist. Both forms read back.
• defaults write ./pf4 k v, run inside my work folder, did not write there. It created ~/Library/Preferences/./pf4.plist. Only a path starting with / is treated as a file.
• defaults write pf5/sub k v created a pf5 folder inside ~/Library/Preferences.
• defaults -currentHost write wrote to ~/Library/Preferences/ByHost/cc.picklog.probe.661AC032-....plist, named with the hardware UUID, and a plain defaults read of the same key said it did not exist.
• defaults delete cc.picklog.probe removed every key but left a 42-byte empty plist file behind.

For editing a standalone plist file, plutil is the better tool anyway. The man page on this machine, dated November 3, 2003, ends with a warning that defaults "will be changed in an upcoming major release to only operate on preferences domains". It does not document import or export at all, though the usage text does.

Why a setting you wrote does nothing

A common explanation online is that cfprefsd caches preferences, so editing the plist file directly is ignored and you must killall cfprefsd. On 26.4.1 that was only half true. I changed the file four ways: plutil -replace, cat over it (same inode), cp over it, and mv a new file in (new inode). After each one, defaults read returned the new value on the very next command. Deleting the file made defaults read report the key as missing.

The cache that does bite is inside a running app. I compiled a 9-line Swift program that opens UserDefaults(suiteName: "cc.picklog.probe") and prints a key once a second. When I edited the file with plutil three seconds in, defaults read showed the new value but the program kept printing the old one for the remaining 14 seconds of its run. When I instead ran defaults write, the program printed the new value within about a second. And when the program wrote its own key afterwards, my hand edit survived; the write merged at the key level rather than replacing the file.

So a running app can see a defaults write, but whether it acts on it is up to the app. The Dock and Finder pick up many of their settings only at launch, which is why tips end with killall Dock; my killall Dock notes time how long each one takes to come back. On the 2016 Ask Different question Update Dock after defaults write without killall restart, the two answers are sending the Dock a HUP signal and "In a word, no": kill it and let it respawn.

Undoing a defaults write

There is no history. defaults delete domain key removes the key so the app falls back to its built-in default, which is usually what "undo" means. If you want a real restore point, export first, and know that import merges:

defaults export com.example.app ~/before.plist   # binary plist
defaults write com.example.app added -string b
defaults import com.example.app ~/before.plist  # 'added' is still there
defaults delete com.example.app                 # clear the domain first
defaults import com.example.app ~/before.plist  # now it matches the backup

I ran that sequence three times; each time the plain import left the added key in place and the delete-then-import restored the exact backup. Two more traps: defaults write domain '{a = 1;}' with no key replaces the entire domain with that one entry, and defaults delete domain nokey on a domain that exists answers "Domain (cc.picklog.probe) not found", which reads like the wrong domain name when it is really the wrong key.

I would not run defaults find or a bare defaults read over SSH on a headless Mac. They walk every domain, including app containers behind privacy protection, and on this machine a listing of a protected folder has already hung a shell for hours with nobody at the screen to answer the prompt. On a headless box like the one in my Mac mini server setup guide, read single keys by name.

What people ask about defaults write

I pulled every question with "defaults write" in the title from Ask Different (32) and Super User (3) through the Stack Exchange API: 35 questions with 142,376 views between them, grouped by me.

Theme	Questions	Example
A specific setting has no effect	14	tap to click after Sierra, Chrome policies, menu bar
Syntax, quoting and types	8	parens in a value, YES/NO vs TRUE/FALSE, nested dicts
Undo or find what I changed	7	the most viewed: 25,037 views
Finding available settings	3	lists of hidden commands
Applying without a restart	2	Dock, LaunchServices handlers
Pushing to many Macs	1	server clients

The top question, Can I undo changes made via "defaults write"?, has one answer, accepted with 34 votes: use defaults delete. It does not mention export or import, so the merge trap above is not covered there. The parens question is the array row in my first table: an unquoted ( turns the value into an array. And the 2016 Super User question YES/NO or TRUE/FALSE has a short answer from the probe: with -bool, both work; without it, both are strings. Apple's own API for these values is UserDefaults, which is what the Swift program above used. For the settings that matter on an always-on machine, see how I disable automatic updates on a Mac and read the keys back.

FAQ

How do I undo a defaults write command on Mac?

Run defaults delete with the same domain and key, for example defaults delete com.apple.dock autohide. The app then uses its built-in default. macOS keeps no history of changes, so for a full restore export the domain first with defaults export, and before importing it back run defaults delete on the domain, because defaults import merges and keeps keys added since the backup.

Should I use YES, true or 1 with defaults write -bool?

yes, YES, true, TRUE, no, false and FALSE all store a real boolean on macOS 26.4.1. -bool 1 and any other word are rejected with exit code 255 and the usage text printed to standard output. Without the -bool flag, yes and true are stored as strings, which many apps ignore.

Why doesn't my defaults write change anything?

Most apps read their settings at launch, so quit and reopen the app, or run killall Dock or killall Finder for those. Also check the type with defaults read-type: a number written without -int is a string. Editing the plist file directly is worse, because an app that is already running never sees the edit.

How this was checked: every command ran on 2026-10-16 on a Mac mini M4 with macOS 26.4.1 (25E253) and /usr/bin/defaults from Foundation-4424.1.402, against a throwaway domain, cc.picklog.probe, which I deleted along with its ByHost file afterwards. No system or app domain was written. The running-app test used a Swift program compiled with the Command Line Tools that read the domain once a second for 17 seconds, run twice. The 35 questions are every Stack Exchange API result with "defaults write" in the title on Ask Different and Super User, grouped by me. Probe scripts and raw output are in my research folder.