dscl — Manage Directory Services and Users

dscl is the Directory Service command-line utility on macOS – it lets you query and manage local users, groups and their attributes straight from the terminal. The first argument names the directory node; the dot . stands for your Mac's local node. Unlike Linux's useradd/usermod, dscl works against the macOS directory database and is the right tool for creating or repairing accounts from scripts. This guide walks you through the key commands, from read-only lookups to provisioning a complete new user.

List & Read

dscl . -list /Users — List all local users.

dscl . -list /Users

dscl . -list /Users UniqueID — List all users with their UIDs.

dscl . -list /Users UniqueID

dscl . -list /Groups — List all local groups.

dscl . -list /Groups

dscl . -read /Users/<user> — Show all attributes of a user.

dscl . -read /Users/admin

dscl . -read /Users/<user> UserShell — Show a specific user attribute.

dscl . -read /Users/admin UserShell

dscl . -read /Groups/<group> GroupMembership — Show members of a group.

dscl . -read /Groups/admin GroupMembership

Create Users

dscl . -create /Users/<user> — Create a new user record.

sudo dscl . -create /Users/newuser

dscl . -create /Users/<user> UserShell /bin/zsh — Set the user's login shell.

sudo dscl . -create /Users/newuser UserShell /bin/zsh

dscl . -create /Users/<user> RealName '<name>' — Set the user's full name.

sudo dscl . -create /Users/newuser RealName 'John Doe'

dscl . -create /Users/<user> UniqueID <uid> — Set the user's UID.

sudo dscl . -create /Users/newuser UniqueID 550

dscl . -create /Users/<user> PrimaryGroupID <gid> — Set the user's primary group ID.

sudo dscl . -create /Users/newuser PrimaryGroupID 20

dscl . -create /Users/<user> NFSHomeDirectory /Users/<user> — Set the home directory path.

sudo dscl . -create /Users/newuser NFSHomeDirectory /Users/newuser

dscl . -passwd /Users/<user> '<password>' — Set the user's password.

sudo dscl . -passwd /Users/newuser 'secretpass'

Modify & Delete

dscl . -change /Users/<user> UserShell <old> <new> — Change a user attribute.

sudo dscl . -change /Users/admin UserShell /bin/bash /bin/zsh

dscl . -append /Groups/<group> GroupMembership <user> — Add a user to a group.

sudo dscl . -append /Groups/admin GroupMembership newuser

dscl . -delete /Groups/<group> GroupMembership <user> — Remove a user from a group.

sudo dscl . -delete /Groups/admin GroupMembership newuser

dscl . -delete /Users/<user> — Delete a user account.

sudo dscl . -delete /Users/olduser

Groups

dscl . -create /Groups/<group> — Create a new group.

sudo dscl . -create /Groups/developers

dscl . -create /Groups/<group> PrimaryGroupID <gid> — Set the group's GID.

sudo dscl . -create /Groups/developers PrimaryGroupID 600

dscl . -delete /Groups/<group> — Delete a group.

sudo dscl . -delete /Groups/developers

Common Patterns

dscl . -list /Users | grep -v '^_' — List only real users (exclude system users starting with _).

dscl . -list /Users | grep -v '^_'

dscl . -list /Users UniqueID | sort -nk2 — List users sorted by UID.

dscl . -list /Users UniqueID | sort -nk2

id <user> — Quick way to check user UID, GID, and groups.

id admin

dscacheutil -flushcache — Flush the Directory Service cache.

sudo dscacheutil -flushcache

Conclusion

On macOS, dscl is the most direct tool for inspecting and maintaining local accounts from scripts – from a quick -read to provisioning a full user with UID, shell, group and home directory. Keep in mind that every write operation (-create, -change, -append, -delete, -passwd) requires sudo and changes the directory database immediately. Use -delete and -passwd in particular with care: a wrong path or a missing required property (such as a UID) can lock out logins or leave an account unusable. Where possible, test new commands against a throwaway account before running them on production users.