DEFAULTS(1) System General Commands Manual DEFAULTS(1)
NAME
defaults - access the Mac OS X user defaults system
SYNOPSIS
defaults [currentHost | -host hostname] read [domain [key]]
defaults [currentHost | -host hostname] read-type domain key
defaults [currentHost | -host hostname] write domain { 'plist' | domain
key 'value' }
defaults [currentHost | -host hostname] rename domain old_key new_key
defaults [currentHost | -host hostname] delete [domain [key]]
defaults [currentHost | -host hostname] { domains | find word | help }
DESCRIPTION
Defaults allows users to read, write, and delete Mac OS X user defaults
from a command-line shell. Mac OS X applications and other programs use
the defaults system to record user preferences and other information that
must be maintained when the applications aren't running (such as default
font for new documents, or the position of an Info panel). Much of this
information is accessible through an application's Preferences panel, but
some of it isn't, such as the position of the Info panel. You can access
this information with defaults
Note: Since applications do access the defaults system while they're run-
ning, you shouldn't modify the defaults of a running application. If you
change a default in a domain that belongs to a running application, the
application won't see the change and might even overwrite the default.
User defaults belong to domains, which typically correspond to individual
applications. Each domain has a dictionary of keys and values represent-
ing its defaults; for example, "Default Font" = "Helvetica". Keys are
always strings, but values can be complex data structures comprising
arrays, dictionaries, strings, and binary data. These data structures are
stored as XML Property Lists.
Though all applications, system services, and other programs have their
own domains, they also share a domain named NSGlobalDomain. If a default
isn't specified in the application's domain, but is specified in
NSGlobalDomain, then the application uses the value in that domain.
The commands are as follows:
read Prints all of the user's defaults, for every domain, to standard
output.
read domain
Prints all of the user's defaults for domain to standard output.
read domain key
Prints the value for the default of domain identified by key.
write domain key 'value'
Writes value as the value for key in domain. value must be a
property list, and must be enclosed in single quotes. For exam-
ple:
defaults write com.companyname.appname "Default Color" '(255, 0, 0)'
sets the value for Default Color to an array containing the
strings 255, 0, 0 (the red, green, and blue components). Note
that the key is enclosed in quotation marks because it contains
a space.
write domain 'plist'
Overwrites the defaults information in domain with that given as
plist. plist must be a property list representation of a dic-
tionary, and must be enclosed in single quotes. For example:
defaults write com.companyname.appname '{ "Default Color" = (255, 0, 0);
"Default Font" = Helvetica; }';
erases any previous defaults for com.companyname.appname and
writes the values for the two names into the defaults system.
delete domain
Removes all default information for domain.
delete domain key
Removes the default named key from domain.
domains Prints the names of all domains in the user's defaults system.
find word
Searches for word in the domain names, keys, and values of the
user's defaults, and prints out a list of matches.
help Prints a list of possible command formats.
OPTIONS
-g When specifying a domain, '-g' may be used as a synonym for
NSGlobalDomain.
Specifying values for preference keys:
-array Allows the user to specify an array as the value for the
given preference key:
defaults write somedomain preferenceKey -array element1 element2 element3
The specified array overwrites the value of the key if the
key was present at the time of the write. If the key was not
present, it is created with the new value.
-array-add Allows the user to add new elements to the end of an array
for a key which has an array as its value. Usage is the same
as -array above. If the key was not present, it is created
with the specified array as its value.
-dict Allows the user to add a dictionary to the defaults database
for a domain. Keys and values are specified in order:
defaults write somedomain preferenceKey -dict key1 value1 key2 value2
The specified dictionary overwrites the value of the key if
the key was present at the time of the write. If the key was
not present, it is created with the new value.
-dict-add Allows the user to add new key/value pairs to a dictionary
for a key which has a dictionary as its value. Usage is the
same as -dict above. If the key was not present, it is cre-
ated with the specified dictionary as its value.
Specifying a host for preferences:
currentHost Operations on the defaults database may apply only to a spe-
cific host. Specifying 'currentHost' after the defaults com-
mand restricts the preferences operations to the host the
user is currently logged in on, rather than any host the
user may log in on.
BUGS
Defaults can be structured in very complex ways, making it difficult for
the user to enter them with this command.
HISTORY
First appeared in NeXTStep.
Mac 10 June 3, 2002 Mac 10