Mac Developer Library Developer
Search

 

This manual page is for Mac OS X version 10.9

If you are running a different version of Mac OS X, view the documentation locally:

  • In Terminal, using the man(1) command

Reading manual pages

Manual pages are intended as a quick reference for people who already understand a technology.

  • To learn how the manual is organized or to learn about command syntax, read the manual page for manpages(5).

  • For more information about this technology, look for other documentation in the Apple Developer Library.

  • For general information about writing shell scripts, read Shell Scripting Primer.




DEFAULTS(1)               BSD 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' | 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 appli-cation's application's
     cation'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 running, you shouldn't modify the
     defaults of a running application. If you change a default in a domain that belongs to a running appli-cation, application,
     cation, 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 representing 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 speci-fied specified
     fied 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.

     read-type domain key
                  Prints the plist type for the given 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 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.

     write domain 'plist'
                  Overwrites the defaults information in domain with that given as plist.  plist must be a
                  property list representation 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 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
     Specifying domains:

     domain    If no flag is specified, domain is a domain name of the form com.companyname.appname.  Exam-ple: Example:
               ple:

                     defaults read com.apple.TextEdit

     -app application
               The name of an application may be provided instead of a domain using the -app flag. Example:

                     defaults read -app TextEdit

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

                     defaults read ~/Library/Containers/com.apple.TextEdit/Data/Library/Preferences/com.apple.TextEdit.plist

               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.

     -g | -globalDomain | NSGlobalDomain
               Specify the global domain. '-g' and '-globalDomain' may be used as synonyms for
               NSGlobalDomain.

     Specifying value types for preference keys:

                 If no type flag is provided, defaults will assume the value is a string. For best results,
                 use one of the type flags, listed below.

     -string     Allows the user to specify a string as the value for the given preference key.

     -data       Allows the user to specify a bunch of raw data bytes as the value for the given preference
                 key.  The data must be provided in hexidecimal.

     -int[eger]  Allows the user to specify an integer as the value for the given preference key.

     -float      Allows the user to specify a floating point number as the value for the given preference
                 key.

     -bool[ean]  Allows the user to specify a boolean as the value for the given preference key.  Value must
                 be TRUE, FALSE, YES, or NO.

     -date       Allows the user to specify a date as the value for the given preference key.

     -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 created
                 with the specified dictionary as its value.

     Specifying a host for preferences:

     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.

     -currentHost
               Restricts preferences operations to the host the user is currently logged in on.

     -host 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

Reporting Problems

The way to report a problem with this manual page depends on the type of problem:

Content errors
Report errors in the content of this documentation with the feedback links below.
Bug reports
Report bugs in the functionality of the described tool or API through Bug Reporter.
Formatting problems
Report formatting mistakes in the online version of these pages with the feedback links below.

Feedback