dscl

Directory Service command line utility
General-purpose utility for operating on Directory Service directory nodes. Its commands allow one to create, read, and manage Directory Service data. If invoked without any commands, dscl runs in an interactive mode, reading commands from standard input. Interactive pro- cessing is terminated by the quit command.

SYNTAX
      dscl [options] datasource [command]

Options
   -p	        Prompt for password
   -u user	Authenticate as user
   -P password  Authentication password
   -raw	        Don't strip off prefix from DirectoryService API constants		     
   -url	        Print record attribute values in URL-style encoding
   -q	        quiet - no interactive prompt

commands:
		-read [path [key ...]]
		-list path
		-search path key val
		-create record_path [key [val ...]]
		-append record_path key val ...
		-merge record_path key val ...
		-delete path [key [val ...]]
		-change record_path key old_val new_val
		-changei record_path key val_index new_val
		-passwd user_path [new_password | old_password new_password]

Available only in interactive mode:
		-cd dir
		-pushd [dir]
		-popd
		-auth [user [password]]
		-quit

Leading dashes ("-") are optional for all commands.

dscl operates on a datasource specified on the command line. This may be a node name or a Mac OS X Server (10.2 or later) host specified by DNS hostname or IP address. Node names may be absolute paths beginning with a slash ("/"), or relative domain paths beginning with a dot (".") character, which specifies the local domain, or "..", specifying the local domain's parent. If the hostname or IP address form is used then the user must specify the -u option and either the -P of -p options to specify an administrative user and password on the remote host to authenticate with to the remote host. The exception to this is if "localhost" is specified.

PATH SPECIFICATION

     There are two modes of operation when specifying paths to operate on. The
     two modes correspond to whether the datasource is a node or a host. In
     the case of specifying a node, the top level of paths will be record
     types. Example top level paths would be:

	   /Users/alice
	   /Groups/admin

     In the case of specifying a host as a data source, the top level of paths
     correspond to Open Directory plug-ins and Search Paths. One can specify
     the plug-in to traverse to a node name, after which the paths are equiva-
     lent to the former usage. The following might be the equivalent paths as
     the above paths:

	   /NetInfo/root/Users/alice
	   /LDAPv3/10.0.1.42/Groups/admin

     If path components contain keys or values with embedded slash characters,
     the slash characters must be escaped with a leading backslash character.
     Since the shell also processes escape characters, an extra backslash is
     required to correctly specify an escape.  For example, to read a mount
     record with the name "ldapserver:/Users" in the "/Mounts" path, the fol-
     lowing path would be used:

	   dscl	 . -read /Mounts/ldaphost:\\/Users

     All pathnames are case-sensitive.

COMMANDS

     The action of each command is described below.  Some commands have
     aliases.  For example, "cat" and "." are aliases for "read".  Command
     aliases are listed in parentheses.

   read (cat .)
     Usage: read [path [key ...]]

     Prints a directory.  Each of the properties are printed one per line.
     The property key is followed by a colon, then a space-separated list of
     the values for that property.  Note that a value which contains embedded
     spaces will appear identical to a pair of values.

     If The -raw flag for raw output has been given, then read prints the full
     DirectoryService API constant for record and attribute types.

     If the -url flag has been specified then printed record path attribute
     values are encoded in the style of URLs. This is useful if a script or
     program is trying to process the output since values will not have any
     spaces or other control characters.

   list (ls)
     Usage: list path

     Lists the subdirectories of the given directory.  Subdirectories are
     listed one per line.  In the case of listing a search path, the names are
     preceded by an index number that can act as a shortcut and used in place
     of the name when specifying a path.

     When used in interactive mode, the path is optional.  With no path given,
     the current directory will be used.

   search
     path key val

     Searches for records that match a pattern.	 The search is rooted at the
     given path.  The path may be a node path or a record type path.  Valid
     keys are Directory Service record attribute types.

   create (mk)
     Usage: create record_path [key [val ...]]

     Creates a record, property, or value.  If only a record path is given,
     the create command will create the record if it does not exist.  If a key
     is given, then a property with that key will be created.

     WARNING - If a property with the given key already exists, it will be
     destroyed and a new property will be created in its place.	 To add values
     to an existing property, use the append or merge commands.

     If values are included in the command, these values will be set for the
     given key.

     NOTE - Not all directory nodes support a property without a value. An
     error will be given if you attempt to create a property with no value in
     such a directory node.

   append
     Usage: append record_path key val ...

     Appends one or more values to a property in a given record.  The property
     is created if it does not exist.

   merge
     Usage: merge record_path key val ...

     Appends one or more values to a property in a given directory if the
     property does not already have those values.  The property is created if
     it does not exist.

   change
     Usage: change record_path key old_val new_val

     Replaces the given old value in the list of values of the given key with
     the new value in the specified record.

   changi
     Usage: changei path key index val

     Replaces the value at the given index in the list of values of the given
     key with the new value in the specified record.  index is an integer
     value.  An index of 1 specifies the first value.  An index greater than
     the number of values in the list will result in an error.

   delete (rm)
     Usage: delete path [key [val ...]]

     Delete a directory, property, or value.  If a directory path is given,
     the delete command will delete the directory.  This can only be used on
     record type and record paths.  If a key is given, then a property with
     that key will be deleted.	If one or more values are given, those values
     will be removed from the property with the given key.

   passwd
     Usage: passwd user_path [new_pasword | old_password new_pasword]

     Changes a password for a user. The user must be specified by full path,
     not just a username.  If you are authenticated to the node (either by
     specifying the -u and -P flags or by using the auth command when in
     interactive node) then you can simply specify a new password.  If you are
     not authenticated then the user's old password must be specified.	If
     passwords are not specified while in interactive mode, you will be
     prompted for them.

INTERACTIVE COMMANDS

   cd
     Usage: cd dir

     Sets the current directory.  Path names for other dscl commands may be
     relative to the current directory.

   pushd (pd)
     Usage: pushd path

     Similar to the pushd command commonly found in Unix shells.  When a path
     is specified it sets the current directory while pushing the previous
     directory on to the directory stack.  If no path is specified it
     exchanges the top two elements of the directory stack.  It will also
     print the final directory stack.

   popd
     Usage: popd

     Pops the directory stack and returns to the new top directory.  It will
     also print the final directory stack.

   auth (su)
     Usage: auth [user [password]]

     Authenticate as the named user, or as "root" if no user is specified.  If
     a password is supplied, then that password is used for authentication,
     otherwise the command prompts for a password.

     If dscl is run in host mode, then when this command is run the current
     directory must be in the subdirectories of a node.

   quit (q)
     Usage: quit

     Ends processing of interactive commands and terminates the program.

   command history
     The up and down arrow keys will scan through the command history.

   tab completion
     When pathnames are being typed, pressing the tab key will result in a
     search to auto-complete the typed partial subdirectory name. It will also
     attempt to correct capitilization in the process.

"Employees must be given responsibility; backed with investment; and provided with motivation. Good people won't stay without them" - Robert Heller

Related commands:

DirectoryService(8)
DirectoryServiceAttributes(7)

Equivalent BASH command:

ldapmodify - LDAP modify entry and LDAP add entry tools