SHELLDAP(1)

💖 SHELLDAP(1) — like, the whole vibe 💖

okay bestie, so this is shelldap — it lives in the User Contributed Perl Documentation part of the manual, and it's a section 1 page (that's the "run it in your terminal" section, iykyk). Pull up a chair, grab a boba, we're doing this. 🧋✨

---

🌸 NAME 🌸

Shelldap — a program for interacting with an LDAP server via a shell-like interface. that's it, that's the whole thing, and honestly? iconic. 💅

---

🦋 DESCRIPTION 🦋

Shelldap / LDAP::Shell is a program for interacting with an LDAP server via a shell-like interface.

And before you come for me: this is not meant to be an exhaustive LDAP editing and browsing interface. no cap. it's meant to be an intuitive shell for doing basic LDAP tasks quickly and with minimal effort. it's giving "we're not doing the most, we're just doing it fast". 🏃♀️💨

---

✨ SYNPOSIS ✨

(yeah the original spells it that way and I'm not about to disrespect the ancestors 🫶)

shelldap --server example.net [--help]

---

👑 FEATURES 👑

• Upon successful authenticated binding, credential information is auto-cached to ~/.shelldap.rc — future loads require no command line flags. the way that it just remembers for you. obsessed. 💖
• Custom 'description maps' for entry listings. (See the 'list' command.) 🎀
• History and autocomplete via readline, if installed. 🔥
• Automatic reconnection attempts if the connection is lost with the LDAP server. it's loyal like that. 🫶
• Basic schema introspection for quick reference. 🦋
• It feels like a semi-crippled shell, making LDAP browsing and editing at least halfway pleasurable</halfway>. lowkey the most honest sentence ever written in a manpage. 😭

---

💅 OPTIONS 💅

All command line options follow getopts long conventions. fr fr, no short-only weirdness here.

shelldap --server example.net --basedn dc=your,o=company

You may also optionally create a ~/.shelldap.rc file with command line defaults. This file should be valid YAML. (This file is generated automatically on a successful bind auth.) ✨

Example:

server: ldap.example.net
binddn: cn=Manager,dc=your,o=company
bindpass: xxxxxxxxx
basedn: dc=your,o=company
tls: yes
tls_cacert: /etc/ssl/certs/cacert.pem
tls_cert:   ~/.ssl/client.cert.pem
tls_key:    ~/.ssl/private/client.key.pem

---

• configfile — Optional. Use an alternate configuration file, instead of the default ~/.shelldap.rc.

--configfile /tmp/alternate-config.yml
-f /tmp/alternate-config.yml

This config file overrides values found in the default config, so you can easily have separate config files for connecting to your cn=monitor or cn=log overlays (for example.) multiple personalities, but make it config management. 💅

• server — Required. The LDAP server to connect to. This can be a hostname, IP address, or a URI.

--server ldaps://ldap.example.net
-H ldaps://ldap.example.net
-h hostname_or_IP

• binddn — The full dn of a user to authenticate as. If not specified, defaults to an anonymous bind. You will be prompted for a password. 👀

--binddn cn=Manager,dc=your,o=company
-D cn=Manager,dc=your,o=company

• basedn — The directory 'root' of your LDAP server. If omitted, shelldap will try and ask the server for a sane default. it's asking for directions, let it. 🗺️

--basedn dc=your,o=company
-b dc=your,o=company

• paginate — Integer. If enabled, shelldap will attempt to use server side pagination to build listings.

⚠️ Note: if you're using this to avoid sizelimit errors, you'll likely need server configuration to raise the limits for paginated results. it's not a magic wand bestie, the server has to cooperate. 😭

--paginate 100

• promptpass — Force password prompting. Useful to temporarily override cached credentials. for when you're logging in as someone else and you don't wanna wipe your whole setup. 🕵️♀️
• sasl — A space separated list of SASL mechanisms. Requires the Authen::SASL module.

--sasl 'PLAIN DIGEST-MD5 EXTERNAL GSSAPI'
-Y 'PLAIN DIGEST-MD5 EXTERNAL GSSAPI'

• sasluser — SASL authorization identity, if one is explicitly required by your backend mechanism.

--sasluser mahlon
-X mahlon

• tls — Enables TLS over what would normally be an insecure connection. Requires server side support. protect yourself, bestie. 🛡️✨
• tls_cacert — Specify CA Certificate to trust.

--tls_cacert /etc/ssl/certs/cacert.pem

• tls_cert — The TLS client certificate.

--tls_cert ~/.ssl/client.cert.pem

• tls_key — The TLS client key. Not specifying a key will connect via TLS without key verification.

--tls_key ~/.ssl/private/client.key.pem

• cacheage — Set the time to cache directory lookups in seconds.

By default, directory lookups are cached for 300 seconds, to speed autocomplete up when changing between different basedns.

Modifications to the directory automatically reset the cache. Directory listings are not cached. (This is just used for autocomplete.) Set it to 0 to disable caching completely. zero, nada, gone. 💨

• timeout — Set the maximum time an LDAP operation can take before it is cancelled. ⏰
• debug — Print extra operational info out, and backtrace on fatal error. for when you need the receipts. 🧾
• version — Display the version number. that's it. that's the whole job. 💖

🎀 SHELL COMMANDS 🎀

okay bestie this is the part you're gonna actually live in. these are the commands you type inside shelldap. no cap, they're basically regular shell commands but for LDAP, which is iconic of it.

---

alias 💅

define aliases, or show off the ones you already have. very main character.

with no arguments, alias prints the list of aliases in the reusable form alias NAME=VALUE on standard output. cute, right?

otherwise, an alias is defined for each NAME whose VALUE is given. important detail: a trailing space in VALUE causes the next word to be checked for alias substitution when the alias is expanded.

alias
alias ll=ls -al
alias ll
alias show=cat
alias cmd1=command 'arg with spaces'
alias cmd2='command '
alias cmd2=command 'with_arg '

---

cat 🐱

print the contents of an LDAP entry to STDOUT in LDIF format. yes bestie, like cat but for entries.

globbing is supported. specify either a full DN, or an RDN. RDNs are local to the current search base (that's your 'cwd' in shell terms). if the RDN is . or missing, it defaults to the current search base. you may additionally add a list of attributes to display (e.g. use + for operational attributes, or provide a specific space-separated list). the default list of attributes is ['*'] and this default list can be changed using the attributes config key or the --attributes cmdline option.

cat uid=mahlon
cat ou=*
cat uid=mahlon,ou=People,dc=example,o=company
cat uid=mahlon + userPassword

---

configfile 🌸

load or save a config file. ur settings, ur rules.

if no config file is specified as argument to load, the default search list is:

$HOME/.shelldap.rc
/usr/local/etc/shelldap.conf
/etc/shelldap.conf

if no config file is specified as argument to save, the default path is $HOME/.shelldap.rc.

configfile load
configfile load /path/to/config
configfile save
configfile save /path/to/config

---

less 🦋

literally like cat, but it uses the configured pager to paginate output. for when the entry is a whole novel and you need to scroll respectfully.

---

cd 👑

change the working directory — which in here means the LDAP search base.

translated to LDAP, this changes the current basedn. all commands after a cd operate within the new basedn. periodt.

cd                  change to 'home' (binddn if any, or basedn)
cd ~                change to 'home' (binddn if any, or basedn)
cd -                change to previous node
cd ou=People        change to explicit path below current node
cd ..               change to parent node
cd ../../ou=Groups  change to node ou=Groups, which is a sibling
                    to the current node's grandparent

since LDAP doesn't limit what can be a container object, you can cd into any entry. many commands then work on . or default to ., meaning "wherever I currently am." it's giving "home is where the basedn is."

cd uid=mahlon
cat .
cat

---

clear ✨

clear the terminal screen.

clears the screen similar to clear or Ctrl+l on the shell command line. the Ctrl+l alias is also supported. immaculate spring cleaning energy.

---

copy 💖

copy an entry. dupe it. glow up a twin.

all copies are relative to the current basedn unless a full DN is specified. all attributes are copied and then an LDAP moddn() is performed.

copy uid=mahlon uid=bob
copy uid=mahlon ou=Others,dc=example,o=company
copy uid=mahlon,ou=People,dc=example,o=company uid=mahlon,ou=Others,dc=example,o=company

---

create 🌈

create an entry. new entry just dropped.

arguments are space separated objectClass names. possible objectClasses are derived automatically from the server, and will tab-complete. (tab-complete!! we love her.)

after the classes are specified, an editor will launch. required attributes are listed first, then optional attributes. optionals are commented out. after the editor exits, the resulting LDIF is validated and added to the LDAP directory.

create top person organizationalPerson inetOrgPerson posixAccount

---

delete 💀

remove an entry. rip bozo (respectfully).

globbing is supported. all deletes are sanity-prompted. the -v flag prints the entries out for review before delete, which is lowkey the responsible thing to do.

delete uid=mahlon
delete uid=ma*
rm -v uid=mahlon,ou=People,dc=example,o=company l=office

---

edit 🎀

edit an entry in an external editor. fix her up.

after the editor exits, the resulting LDIF is sanity checked, and changes are written to the LDAP directory.

edit uid=mahlon

---

env 🧚

print values of configurable shelldap variables.

heads up: this is a subset of all variables configurable via the shelldap config file and/or its command line options. so it's not the whole squad, just the ones who showed up.

---

grep 🔍

search using LDAP filters and return matching DN results.

the search string must be a valid LDAP filter. no vibes-only searching, bestie.

grep uid=mahlon
grep uid=mahlon ou=People
grep -r (&(uid=mahlon)(objectClass=*))

---

inspect 👑

view schema and flags for an entry or objectClass.

it also includes the most common flags for the objectClass attributes. very "let me read her aura" of it.

inspect uid=mahlon
inspect posixAccount organizationalUnit
inspect _schema

the output is a list of found objectClasses, their schema hierarchy (up to top), whether or not they are a structural class, and then a merged list of all valid attributes for the given objectClasses. attributes are marked as either required or optional, and whether they allow multiple values or not.

if you ask for the special _schema object, the raw server schema is dumped to screen. raw. unfiltered. iconic.

---

list 🍓

list directory contents.

globbing is supported.

ls -l
ls -lR uid=mahlon
list uid=m*

in 'long' mode, descriptions are listed as well, if they exist. there are some default 'long listing' mappings for common objectClass types. you can additionally specify your own mappings in your .shelldap.rc, like so:

...
descmaps:
    objectClass: attributename
    posixAccount: gecos
    posixGroup: gidNumber
    ipHost: ipHostNumber

---

mkdir 🌱

create a new organizationalUnit LDAP entry.

mkdir containername
mkdir ou=whatever

---

move 🚚

move (rename) entry.

usage is identical to copy. same energy, different destination.

---

passwd 🔐

change user password.

if supported server side, change the password for a specified entry. the entry must have a userPassword attribute. no userPassword, no password change, that's just how it is.

passwd uid=mahlon

---

pwd 📍

print name of current/working LDAP search base. "where am i" but for LDAP.

---

setenv ⭐

change or define a shelldap variable.

setenv debug 1
export debug=1

---

unalias 🙈

remove each NAME from the list of defined aliases.

alias ll=ls -al
alias
unalias ll
unalias ll ls
alias

---

unsetenv 💜

remove each NAME from the list of defined shelldap variables.

unset debug
unset configfile
unset myvar1 myvar2 myvar3

---

whoami 🪞

print current bind DN.

show current auth credentials. unless you specified a binddn, this will just show an anonymous bind. mystery era.

---

📝 TODO 📝

referral support. currently, if you try to write to a replicant slave, you'll just get a referral. it would be nice if shelldap automatically tried to follow it.

for now, it only makes sense to connect to a master if you plan on doing any writes. remember that bestie.

add ability for command definitions in cmd_map to contain default arguments passed to functions.

then add ability to define custom commands/aliases in config file.

split inspect into separate commands, one working on files/entries, and one working on objectclasses. this way, autocompleter for both commands will be reasonable, unlike now.

---

😭 BUGS / LIMITATIONS 😭

there is no support for editing binary data. if you need to edit base64 stuff, just feed it to the regular ldapmodify/ldapadd/etc tools.

fr fr, don't come for shelldap about base64. she said what she said.

---

👑 AUTHOR 👑

Mahlon E. Smith <mahlon@martini.nu>

---

okay that's the whole page bestie, we ate and left no crumbs 💅 this was perl v5.42.0, dated 2025-07-25, and it's the SHELLDAP(1) manual — go forth and LDAP responsibly, mwah 🫶💖