lldap-cli

A TypeScript CLI tool for managing LLDAP (Lightweight LDAP) users, groups, and schema.

Built with Bun for fast execution and modern TypeScript support.

Features

• User Management - Create, list, update, and delete users
• Group Management - Create, list, and manage group membership
• Schema Management - View and modify custom user/group attributes
• Secure Authentication - JWT-based auth with automatic token refresh
• Security Hardened - Input validation, rate limiting, audit logging

Installation

From npm

# Install globally with npm
npm install -g lldap-cli

# Install globally with bun
bun add -g lldap-cli

# Run without installing (npx)
npx lldap-cli --help

# Run without installing (bunx)
bunx lldap-cli --help

From Release

Download the standalone binary for your platform from the releases page:

# Linux x64
curl -LO https://github.com/madeinoz67/lldap-cli/releases/latest/download/lldap-cli-linux-x64
chmod +x lldap-cli-linux-x64
sudo mv lldap-cli-linux-x64 /usr/local/bin/lldap-cli

# Linux ARM64
curl -LO https://github.com/madeinoz67/lldap-cli/releases/latest/download/lldap-cli-linux-arm64
chmod +x lldap-cli-linux-arm64
sudo mv lldap-cli-linux-arm64 /usr/local/bin/lldap-cli

# macOS x64 (Intel)
curl -LO https://github.com/madeinoz67/lldap-cli/releases/latest/download/lldap-cli-darwin-x64
chmod +x lldap-cli-darwin-x64
sudo mv lldap-cli-darwin-x64 /usr/local/bin/lldap-cli

# macOS ARM64 (Apple Silicon)
curl -LO https://github.com/madeinoz67/lldap-cli/releases/latest/download/lldap-cli-darwin-arm64
chmod +x lldap-cli-darwin-arm64
sudo mv lldap-cli-darwin-arm64 /usr/local/bin/lldap-cli

# Windows x64 (untested)
# Download lldap-cli-windows-x64.zip from the releases page and extract

Note: Windows builds are provided but currently untested. Please report any issues.

From Source

# Clone the repository
git clone https://github.com/madeinoz67/lldap-cli.git
cd lldap-cli

# Install dependencies
bun install

# Build
bun run build

# Run directly with Bun
bun run dev -- user list

Configuration

Environment Variables

export LLDAP_HTTP_URL="http://localhost:17170"
export LLDAP_USERNAME="admin"
export LLDAP_PASSWORD="your-password"
# Or use tokens (set automatically by eval $(lldap-cli login -p))
export LLDAP_TOKEN="your-jwt-token"
export LLDAP_REFRESH_TOKEN="your-refresh-token"

You can also create a .env file in your working directory with these variables - it will be loaded automatically.

Config File

Create ~/.config/lldap-cli/config.json:

{
  "httpUrl": "http://localhost:17170",
  "username": "admin"
}

CLI Options

CLI options override environment variables and config file:

lldap-cli -H http://localhost:17170 -u admin user list

Usage

Authentication

# Login with password prompt (recommended - password hidden, tokens set automatically)
eval $(lldap-cli login -p)

# Login with password on command line (less secure)
eval $(lldap-cli login -w password)

# Login and save tokens to file (most secure for scripts)
lldap-cli login -p -o ~/.lldap-tokens
source ~/.lldap-tokens

# Logout and invalidate tokens
eval $(lldap-cli logout)

The -p flag prompts for password securely (input hidden). The eval $(...) pattern automatically sets LLDAP_TOKEN and LLDAP_REFRESHTOKEN environment variables for subsequent commands.

User Management

# List users
lldap-cli user list              # List user IDs (default)
lldap-cli user list email        # List user emails
lldap-cli user list all          # Table with ID, email, display name
lldap-cli user list -g admins    # List users in 'admins' group
lldap-cli user list all -g staff # Table of users in 'staff' group
lldap-cli user info              # Show detailed user info

# Search users (supports * and ? wildcards)
lldap-cli user search john       # Search by uid, email, or display name
lldap-cli user search "*@corp.com"  # Find users with corp.com email
lldap-cli user search "svc_*"    # Find service accounts

# Create a user
lldap-cli user add jsmith [email protected] -d "John Smith" -f John -l Smith

# Delete a user
lldap-cli user del jsmith

# Set user password (requires lldap_set_password tool)
lldap-cli user set-password jsmith

# Update user attributes
lldap-cli user update set jsmith displayName "Johnny Smith"
lldap-cli user update clear jsmith avatar
lldap-cli user update add jsmith mailAlias "[email protected]"
lldap-cli user update del jsmith mailAlias "[email protected]"

# User attributes
lldap-cli user attribute list jsmith
lldap-cli user attribute values jsmith mailAlias

# User group membership
lldap-cli user group list jsmith
lldap-cli user group add jsmith "mail users"
lldap-cli user group del jsmith "mail users"

Group Management

# List groups
lldap-cli group list

# Search groups (supports * and ? wildcards)
lldap-cli group search admin*    # Find groups starting with 'admin'
lldap-cli group search "*users"  # Find groups ending with 'users'

# Create a group
lldap-cli group add "mail users"

# Delete a group
lldap-cli group del "mail users"

# Show users in a group
lldap-cli group info "mail users"

# Add/remove users
lldap-cli group add-user 1 jsmith
lldap-cli group remove-user 1 jsmith

# Update group attributes
lldap-cli group update set "mail users" description "Mail system users"

# Group attributes
lldap-cli group attribute list "mail users"
lldap-cli group attribute values "mail users" description

Schema Management

# User schema attributes
lldap-cli schema attribute user list
lldap-cli schema attribute user add mailAlias string -l -v    # list, visible
lldap-cli schema attribute user del mailAlias

# Group schema attributes
lldap-cli schema attribute group list
lldap-cli schema attribute group add memberCount integer
lldap-cli schema attribute group del memberCount

# User object classes
lldap-cli schema objectclass user list
lldap-cli schema objectclass user add inetOrgPerson
lldap-cli schema objectclass user del inetOrgPerson

# Group object classes
lldap-cli schema objectclass group list
lldap-cli schema objectclass group add posixGroup
lldap-cli schema objectclass group del posixGroup

Attribute Types

When adding schema attributes, use one of:

• string - Text values
• integer - Numeric values
• date_time - Date/time values
• jpeg_photo - Binary image data

Attribute Options

• -l, --list - Attribute can have multiple values
• -v, --visible - Attribute is visible in LDAP queries
• -e, --editable - Attribute can be modified via LDAP

Global Options

| Option | Description | |--------|-------------| | -H, --http-url <url> | LLDAP HTTP URL | | -u, --username <user> | Username for authentication | | -t, --token <token> | JWT access token | | -r, --refresh-token <token> | JWT refresh token | | -q, --quiet | Suppress header and non-essential output | | --debug | Enable debug output (WARNING: may expose sensitive info) | | -h, --help | Show help | | -V, --version | Show version |

Login Options

| Option | Description | |--------|-------------| | -p, --prompt-password | Prompt for password (input hidden) | | -w, --password <pass> | Password on command line (less secure) | | -o, --output <file> | Write tokens to file instead of stdout | | -q, --quiet | Suppress security warnings |

Programmatic Usage

import { LldapClient, UserService, GroupService, SchemaService, buildConfig } from 'lldap-cli';

const config = buildConfig({
  httpUrl: 'http://localhost:17170',
  username: 'admin',
  password: 'password',
});

const client = new LldapClient(config);
const userService = new UserService(client);

// List all users
const users = await userService.getUsers();
console.log(users);

// Clean up
await client.cleanup();

Exit Codes

The CLI uses standard BSD sysexits.h exit codes for scripting:

| Code | Name | Description | |------|------|-------------| | 0 | SUCCESS | Command completed successfully | | 1 | ERROR | General/unknown error | | 64 | USAGE | Invalid arguments or usage | | 69 | UNAVAILABLE | Service unavailable (server down) | | 74 | IOERR | I/O error (file not found) | | 75 | TEMPFAIL | Temporary failure (rate limited) | | 77 | NOPERM | Authentication/authorization failed | | 78 | CONFIG | Configuration error |

Example scripting usage:

lldap-cli login -p
case $? in
  0)  echo "Login successful" ;;
  77) echo "Authentication failed" ;;
  78) echo "Configuration error - check username/URL" ;;
  *)  echo "Other error: $?" ;;
esac

Security Features

This CLI includes comprehensive security hardening:

| Feature | Description | |---------|-------------| | Input Validation | All inputs validated for length and dangerous characters | | Password Complexity | Passwords must be 8-128 chars with letters and numbers | | Rate Limiting | Exponential backoff on 429 responses (max 3 retries) | | Session Timeout | 30-minute inactivity timeout | | Token Management | Automatic refresh, expiration detection | | Audit Logging | Security events logged to stderr | | Error Sanitization | Sensitive data redacted from error messages | | Path Traversal Protection | File paths validated to prevent attacks | | HTTPS Warning | Warns when using HTTP to non-localhost servers |

Development

# Install dependencies
bun install

# Run tests
bun test

# Run tests in watch mode
bun test --watch

# Type check
bun run typecheck

# Lint
bun run lint

# Lint and fix
bun run lint:fix

# Build
bun run build

Requirements

• Bun 1.0+ (for development/running from source)
• LLDAP server running and accessible
• lldap_set_password tool (optional, for password management)

License

MIT License - Copyright (c) 2026 Stephen Eaton

See LICENSE for details.

Contributing

Contributions are welcome! Please ensure:

1. All tests pass (bun test)
2. Code passes linting (bun run lint)
3. TypeScript compiles without errors (bun run typecheck)
4. Security scanning passes (Trivy, TruffleHog)

Acknowledgments

• LLDAP - The lightweight LDAP server this tool manages
• Commander.js - CLI framework
• Bun - JavaScript runtime and toolkit