Manual Pages for UNIX Darwin command on man defaults

DEFAULTS(1) BSD General Commands Manual DEFAULTS(1)

NAME

ddeeffaauullttss - access the Mac OS X user defaults system

SYNOPSIS

ddeeffaauullttss [-ccuurrrreennttHHoosstt | -hhoosstt hostname] read [domain [key]]

ddeeffaauullttss [-ccuurrrreennttHHoosstt | -hhoosstt hostname] read-type domain key

ddeeffaauullttss [-ccuurrrreennttHHoosstt | -hhoosstt hostname] write domain { 'plist' | key

'value' }

ddeeffaauullttss [-ccuurrrreennttHHoosstt | -hhoosstt hostname] rename domain oldkey newkey

ddeeffaauullttss [-ccuurrrreennttHHoosstt | -hhoosstt hostname] delete [domain [key]]

ddeeffaauullttss [-ccuurrrreennttHHoosstt | -hhoosstt hostname] { domains | find word | help }

DESCRIPTION

DDeeffaauullttss 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 ddeeffaauullttss

NNoottee:: 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 NNSSGGlloobbaallDDoommaaiinn. If a default isn't specified in the application's domain, but is specified in NNSSGGlloobbaallDDoommaaiinn, then the application uses the value in that domain. The commands are as follows:

rreeaadd Prints all of the user's defaults, for every domain, to

standard output.

rreeaadd domain Prints all of the user's defaults for domain to standard

output. rreeaadd domain key Prints the value for the default of domain identified by key.

rreeaadd-ttyyppee domain key

Prints the plist type for the given domain identified by key. wwrriittee 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 example:

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. wwrriittee domain 'plist'

Overwrites the defaults information in domain with that

given as plist. plist must be a property list representa-

tion of a dictionary, 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 sys-

tem. ddeelleettee domain Removes all default information for domain. ddeelleettee domain key Removes the default named key from domain.

ddoommaaiinnss Prints the names of all domains in the user's defaults sys-

tem. ffiinndd word Searches for word in the domain names, keys, and values of

the user's defaults, and prints out a list of matches.

hheellpp Prints a list of possible command formats. OOPPTTIIOONNSS SSppeecciiffyyiinngg ddoommaaiinnss:: domain If no flag is specified, domain is a domain name of the form com.companyname.appname. Example:

defaults read com.apple.TextEdit

-aapppp application

The name of an application may be provided instead of a domain

using the -aapppp flag. Example:

defaults read -app TextEdit

filepath Domains may also be specified as a path to an arbitrary plist file, omitting the '.plist' extension. For example:

defaults read ~/Library/Preferences/com.apple.TextEdit

normally gives the same result as the two previous examples. In the following example:

defaults write ~/Desktop/TestFile foo bar

will write the key 'foo' with the value 'bar' into the plist file 'TestFile.plist' that is on the user's desktop. If the file does not exist, it will be created. If it does exist, the

key-value pair will be added, overwriting the value of 'foo' if

it already existed.

WARNING: The defaults command will be changed in an upcoming

major release to only operate on preferences domains. General plist manipulation utilities will be folded into a different

command-line program.

-gg | -gglloobbaallDDoommaaiinn | NNSSGGlloobbaallDDoommaaiinn

Specify the global domain. '-gg' and '-gglloobbaallDDoommaaiinn' may be used

as synonyms for NNSSGGlloobbaallDDoommaaiinn. SSppeecciiffyyiinngg vvaalluuee ttyyppeess ffoorr pprreeffeerreennccee kkeeyyss:: If no type flag is provided, ddeeffaauullttss will assume the value is a string. For best results, use one of the type flags, listed below.

-ssttrriinngg Allows the user to specify a string as the value for the

given preference key.

-ddaattaa Allows the user to specify a bunch of raw data bytes as the

value for the given preference key. The data must be pro-

vided in hexidecimal.

-iinntt[[eeggeerr]] Allows the user to specify an integer as the value for the

given preference key.

-ffllooaatt Allows the user to specify a floating point number as the

value for the given preference key.

-bbooooll[[eeaann]] Allows the user to specify a boolean as the value for the

given preference key. Value must be TRUE, FALSE, YES, or NO.

-ddaattee Allows the user to specify a date as the value for the given

preference key.

-aarrrraayy 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.

-aarrrraayy-aadddd 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.

-ddiicctt 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.

-ddiicctt-aadddd 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. SSppeecciiffyyiinngg aa hhoosstt ffoorr pprreeffeerreenncceess::

Operations on the defaults database normally apply to any host the user

may log in on, but may be restricted to apply only to a specific host. If no host is provided, preferences operations will apply to any host the user may log in on.

-ccuurrrreennttHHoosstt

Restricts preferences operations to the host the user is cur-

rently logged in on.

-hhoosstt hostname

Restricts preferences operations to hostname.

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 OS X Nov 3, 2003 Mac OS X