dscl is a general-purpose utility for operating on Directory Service directory nodes. Its commands allow one to create, read, and manage Directory Service data.

I've been aware of dscl for some time, but have been reluctant to use it. The scope of its function intimidated me, and the syntax of the commands has always struck me as a little unwieldy. However, I recently had cause to make some remote changes to a number of Macs in our department, and found that dscl was the best (only?) way to achieve what I wanted.

On a superficial level, dscl is means by which a sys admin can manage the user and group objects on a local machine. A quick look on the web revealed a few useful resources. Amsys' blog is a good entry point, and Charles Edge's posts demonstrate the depth of what the utility can achieve. However, I found that the superuser forums were the most immediate source of information.

First, I took a look at running dscl via the interactive prompt:

$ dscl
Entering interactive mode... (type "help" for commands)
 >

You can then inspect the directories the machine is bound to. This functions as CLI version of the Directory Utility GUI app:

> ls
Active Directory
Local

Contact
Search
 > cd Active\ Directory/
/Active Directory >

You can then cd or ls through the directory, listing objects such as Printers, Users and Groups. You can inspect the properties of these objects with the read command. For example, invoking this on a user:

> read Active\ Directory/Domain/Users/user1

will print out the directory attributes of that user, including UID, home directory location and group membership.

As you might expect, dscl allows the modification of node attributes. This is where my working example comes in. We could use the interactive shell for this, but the desired effect can be achieved without.

I needed to remove a user from a group on a particular machine. First, I SSH'd to the machine. Then, I needed to find the local group name:

$ dscl . list /Groups

This produces a listing of all groups on the machine. Over to grep:

$ dscl . list /Groups | grep ssh
_sshd
com.apple.access_ssh

Inspect the current members of the group:

$ dscl . list /Groups/com.apple.access_ssh GroupMembership
GroupMembership: user1 user2

Remove user2:

$ dscl . delete /Groups/com.apple.access_ssh GroupMembership user2

Verify success:

$ dscl . read /Groups/com.apple.access_shh GroupMembership
GroupMembership: user1

Done. A cumbersome analogue of usermod, but a useful one nonetheless.

As an aside, you can easily view all groups and associated members with:

$ dscl . list /Groups GroupMembership

Of course, this isn't a tool to use lightly. Every forum post I've seen seems to feature a sys admin horror story of users, groups and attributes corrupted through improper use of the command. Furthermore, I've seen dseditgroup commonly cited as a more robust means of modifying user and group attributes. I'll post on that when I've had a play around with it.