# dscl — Manage Directory Services and Users

> Practical guide to dscl — query, create, modify and delete local users and groups on macOS via the Directory Service command-line utility.

Source: https://www.jpkc.com/db/en/cheatsheets/macos/dscl/

<!-- PROSE:intro -->
`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.
<!-- PROSE:intro:end -->

## List & Read

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

```bash
dscl . -list /Users
```

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

```bash
dscl . -list /Users UniqueID
```

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

```bash
dscl . -list /Groups
```

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

```bash
dscl . -read /Users/admin
```

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

```bash
dscl . -read /Users/admin UserShell
```

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

```bash
dscl . -read /Groups/admin GroupMembership
```

## Create Users

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

```bash
sudo dscl . -create /Users/newuser
```

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

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

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

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

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

```bash
sudo dscl . -create /Users/newuser UniqueID 550
```

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

```bash
sudo dscl . -create /Users/newuser PrimaryGroupID 20
```

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

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

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

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

## Modify & Delete

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

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

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

```bash
sudo dscl . -append /Groups/admin GroupMembership newuser
```

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

```bash
sudo dscl . -delete /Groups/admin GroupMembership newuser
```

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

```bash
sudo dscl . -delete /Users/olduser
```

## Groups

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

```bash
sudo dscl . -create /Groups/developers
```

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

```bash
sudo dscl . -create /Groups/developers PrimaryGroupID 600
```

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

```bash
sudo dscl . -delete /Groups/developers
```

## Common Patterns

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

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

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

```bash
dscl . -list /Users UniqueID | sort -nk2
```

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

```bash
id admin
```

`dscacheutil -flushcache` — Flush the Directory Service cache.

```bash
sudo dscacheutil -flushcache
```

<!-- PROSE:outro -->
## 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.

## Further Reading

- [dscl(1) — macOS Manual Page](https://ss64.com/mac/dscl.html) — full option reference
- [Apple Developer Documentation](https://developer.apple.com/documentation/) — official documentation for macOS and its services
<!-- PROSE:outro:end -->

## Related Commands

- [caffeinate](https://www.jpkc.com/db/en/cheatsheets/macos/caffeinate/) – prevents the Mac from going to sleep
- [defaults](https://www.jpkc.com/db/en/cheatsheets/macos/defaults/) – reads and writes settings in macOS property lists
- [diskutil](https://www.jpkc.com/db/en/cheatsheets/macos/diskutil/) – manages disks, volumes and partitions