User Management

CLI commands for managing users and admins

Overview

TrailBase provides comprehensive CLI commands for managing users and administrators. Unlike the admin UI, CLI commands allow you to modify admin users and perform operations that require elevated permissions.

User Commands

All user commands operate on the _user table in the main database. Users can be identified by either email address or UUID.

User Identifiers

Most commands accept a user identifier that can be:

Email Address · string

User’s email address (e.g., [e-mail])

Must contain an @ symbol

UUID · string

User’s unique identifier (e.g., 550e8400-e29b-41d4-a716-446655440000)

Standard UUID format

Using Email

trail user verify [e-mail] true

trail user verify 550e8400-e29b-41d4-a716-446655440000 true

Adding Users

user add

Create a new verified user with email and password.

trail user add <EMAIL> <PASSWORD>

email · string · required

Email address for the new user. Must be a valid email format and unique.

password · string · required

Password for the new user. Not checked against password policies, so choose a strong password.

Create Regular User

trail user add [e-mail] SecureP@ssw0rd123

# Output: Added user '[e-mail]'

# Step 1: Add user
trail user add [e-mail] AdminP@ssw0rd123

# Step 2: Promote to admin
trail admin promote [e-mail]

Users created with trail user add are automatically marked as verified and can log in immediately.

The CLI does not enforce password policies. Ensure you use strong passwords when creating users via CLI.

Modifying Users

user change-password

Change a user’s password.

trail user change-password <USER> <PASSWORD>

user · string · required

User identifier (email or UUID).

password · string · required

New password to set for the user.

By Email

trail user change-password [e-mail] NewP@ssw0rd456

# Output: Updated password for '[e-mail]'

trail user change-password 550e8400-e29b-41d4-a716-446655440000 NewP@ssw0rd456

# Output: Updated password for '550e8400-e29b-41d4-a716-446655440000'

Password changes take effect immediately. Active sessions remain valid until their tokens expire.

user change-email

Change a user’s email address.

trail user change-email <USER> <NEW_EMAIL>

user · string · required

User identifier (email or UUID).

new_email · string · required

New email address to set for the user. Must be unique.

Change Email

trail user change-email [e-mail] [e-mail]

# Output: Updated email for '[e-mail]'

trail user change-email 550e8400-e29b-41d4-a716-446655440000 [e-mail]

# Output: Updated email for '550e8400-e29b-41d4-a716-446655440000'

Email changes do not trigger verification emails. The user can immediately log in with the new email address.

user verify

Change a user’s email verification status.

trail user verify <USER> [VERIFIED]

user · string · required

User identifier (email or UUID).

verified · boolean · default: "true"

Verification status to set. true to verify, false to unverify.

Verify User

trail user verify [e-mail] true

# Output: Set verified=true for '[e-mail]'

trail user verify [e-mail] false

# Output: Set verified=false for '[e-mail]'

trail user verify [e-mail]

# Output: Set verified=true for '[e-mail]'

Unverified users cannot log in until they verify their email or are manually verified via CLI.

Session Management

user invalidate-session

Invalidate all active sessions for a user, forcing re-authentication.

trail user invalidate-session <USER>

user · string · required

User identifier (email or UUID).

Example

trail user invalidate-session [e-mail]

# Output: Sessions invalidated for '[e-mail]'

Active auth tokens remain valid until expiration. Users will need to re-authenticate when their current token expires.

Use cases:

• User reports compromised account
• Force logout after password change
• Security incident response
• User permission changes require re-authentication

user mint-token

Generate an authentication token for a user.

trail user mint-token <USER>

user · string · required

User identifier (email or UUID).

Example:

trail user mint-token [e-mail]

# Output:
# Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAiLCJleHAiOjE3MDk4MjU0MTJ9.signature

The output is in Bearer token format and can be used directly in Authorization headers for API requests.

Use token with curl:

# Mint token
TOKEN=$(trail user mint-token [e-mail])

# Use in API request
curl -H "Authorization: ${TOKEN}" https://localhost:4000/api/records/v1/posts

Use cases:

• Testing API endpoints
• Automated scripts requiring authentication
• Debugging authentication issues
• Service-to-service authentication

Tokens are sensitive credentials. Handle them securely and never commit them to version control.

Deleting Users

user delete

Permanently delete a user and all associated data.

trail user delete <USER>

user · string · required

User identifier (email or UUID).

By Email

trail user delete [e-mail]

# Output: Deleted user '[e-mail]'

trail user delete 550e8400-e29b-41d4-a716-446655440000

# Output: Deleted user '550e8400-e29b-41d4-a716-446655440000'

This operation is irreversible. All user data will be permanently deleted. Consider backing up the database before deleting users.

What gets deleted:

• User record from _user table
• User sessions from _session table
• User avatar from _user_avatar table
• Related records (depending on foreign key constraints)

Backup before deletion:

# Backup database
cp traildepot/data/main.db traildepot/data/main.db.backup

# Then delete user
trail user delete [e-mail]

Admin Management

admin list

List all users with admin privileges.

trail admin list

Example output:

                                   id	email	created	updated
550e8400-e29b-41d4-a716-446655440000	[e-mail]	2024-01-15T10:30:00Z	2024-03-07T14:22:00Z
6ba7b810-9dad-11d1-80b4-00c04fd430c8	[e-mail]	2024-02-01T08:15:00Z	2024-03-05T16:45:00Z

Output columns:

• id - User UUID
• email - User email address
• created - Account creation timestamp
• updated - Last update timestamp

admin promote

Promote a regular user to admin.

trail admin promote <USER>

user · string · required

User identifier (email or UUID).

By Email

trail admin promote [e-mail]

# Output: Promoted user to admin for '[e-mail]'

trail admin promote 550e8400-e29b-41d4-a716-446655440000

# Output: Promoted user to admin for '550e8400-e29b-41d4-a716-446655440000'

Admin users gain access to the admin UI and all admin API endpoints. Permissions take effect immediately for new sessions.

Admin privileges include:

• Access to Admin UI (/_admin)
• Configuration management
• User management via UI
• Schema management
• Log viewing
• API management

admin demote

Demote an admin user to regular user.

trail admin demote <USER>

user · string · required

User identifier (email or UUID).

By Email

trail admin demote [e-mail]

# Output: Demoted admin to user for '[e-mail]'

trail admin demote 550e8400-e29b-41d4-a716-446655440000

# Output: Demoted admin to user for '550e8400-e29b-41d4-a716-446655440000'

Demoted users lose admin access immediately for new sessions. Existing sessions may retain admin access until tokens expire.

Unlike the admin UI, the CLI allows you to demote yourself. Ensure you have at least one admin user before demoting all admins.

User Import

user import

Bulk import users from external authentication providers.

trail user import [OPTIONS]

--auth0-json · string

Path to Auth0 exported users as newline-delimited JSON (NDJSON) file.

-n, --dry-run · boolean · default: "false"

Validate users without importing. Useful for testing before actual import.

Dry Run (Validate Only)

trail user import --auth0-json users.ndjson --dry-run

# Output:
# Importing 150 users.
# (No actual import, validation only)

trail user import --auth0-json users.ndjson

# Output:
# Importing 150 users.
# Successfully imported 150 users.

Auth0 export format:

Auth0 exports users in NDJSON format (one JSON object per line):

{"user_id":"auth0|123","email":"[e-mail]","email_verified":true,...}
{"user_id":"auth0|456","email":"[e-mail]","email_verified":false,...}

Import process:

1. Validates each user record
2. Creates users with verified status
3. Hashes passwords securely
4. Handles duplicate emails (skips or errors)
5. Reports import statistics

Always run with --dry-run first to validate the import file before performing the actual import.

Large imports may take time. Monitor the import process and ensure the database isn’t locked by other processes.

Common Workflows

Creating Your First Admin

Step-by-step: Create first admin user

# 1. Add user
trail user add [e-mail] SecureAdminP@ssw0rd

# 2. Promote to admin
trail admin promote [e-mail]

# 3. Verify admin status
trail admin list

# 4. Log in to admin UI
# Navigate to http://localhost:4000/_admin
# Use: [e-mail] / SecureAdminP@ssw0rd

Handling Forgotten Passwords

Step-by-step: Reset user password

# 1. User contacts you about forgotten password

# 2. Reset password via CLI
trail user change-password [e-mail] TemporaryP@ss123

# 3. Send new temporary password to user via secure channel

# 4. Instruct user to change password after login

Emergency Admin Access

Step-by-step: Regain admin access

# Scenario: Locked out of admin account

# 1. Check if admin exists
trail admin list

# 2. If no admins exist, create emergency admin
trail user add [e-mail] EmergencyP@ss123
trail admin promote [e-mail]

# 3. Log in and create proper admin account via UI

# 4. Delete emergency account
trail user delete [e-mail]

Bulk User Operations

Step-by-step: Create multiple users from CSV

# users.csv format: email,password
# [e-mail],Password123
# [e-mail],Password456

# Create users from CSV
while IFS=, read -r email password; do
  trail user add "$email" "$password"
done < users.csv

Step-by-step: Verify all unverified users

# Get unverified user emails from database
sqlite3 traildepot/data/main.db \
  "SELECT email FROM _user WHERE verified = 0" | \
  while read -r email; do
    trail user verify "$email" true
    echo "Verified: $email"
  done

Security Operations

Step-by-step: Handle compromised account

# 1. Invalidate all sessions
trail user invalidate-session [e-mail]

# 2. Change password
trail user change-password [e-mail] NewSecureP@ss789

# 3. If admin, consider temporary demotion
trail admin demote [e-mail]

# 4. Notify user
trail email \
  --to [e-mail] \
  --subject "Security Alert" \
  --body "Your password has been reset. Contact support for details."

# 5. After user verifies identity, restore admin if needed
trail admin promote [e-mail]

Troubleshooting

User Not Found

Error: Could not find user: [e-mail]

Solutions:

# Check if user exists
sqlite3 traildepot/data/main.db "SELECT email FROM _user WHERE email = '[e-mail]'"

# List all users
sqlite3 traildepot/data/main.db "SELECT email FROM _user"

# Check by UUID instead
trail user verify 550e8400-e29b-41d4-a716-446655440000 true

Duplicate Email

Error: User with email already exists

Solutions:

# Find existing user
sqlite3 traildepot/data/main.db \
  "SELECT id, email, verified FROM _user WHERE email = '[e-mail]'"

# Delete existing user if appropriate
trail user delete [e-mail]

# Or modify existing user instead of creating new one
trail user change-password [e-mail] NewP@ssw0rd

Can’t Demote Last Admin

Issue: Demoting the last admin leaves no way to access admin UI

Solution:

# Create new admin before demoting
trail user add [e-mail] AdminP@ss123
trail admin promote [e-mail]

# Verify multiple admins exist
trail admin list

# Now safe to demote
trail admin demote [e-mail]

Import Fails Partway

Issue: Large import fails after importing some users

Solutions:

# 1. Check how many users were imported
sqlite3 traildepot/data/main.db "SELECT COUNT(*) FROM _user"

# 2. Identify which users need importing
# Extract emails from NDJSON
grep -o '"email":"[^"]*"' users.ndjson | cut -d'"' -f4 > all_emails.txt

# Get imported emails
sqlite3 traildepot/data/main.db "SELECT email FROM _user" > imported_emails.txt

# Find remaining emails
comm -23 <(sort all_emails.txt) <(sort imported_emails.txt) > remaining_emails.txt

# 3. Filter NDJSON to only remaining users and retry

Database Schema

_user Table

The user table structure:

CREATE TABLE _user (
  id BLOB PRIMARY KEY,              -- UUID (16 bytes)
  email TEXT NOT NULL UNIQUE,       -- Email address
  password_hash BLOB,               -- Argon2id hash
  verified INTEGER NOT NULL,        -- 0 = unverified, 1 = verified
  admin INTEGER NOT NULL,           -- 0 = user, >0 = admin
  created INTEGER NOT NULL,         -- Unix timestamp
  updated INTEGER NOT NULL          -- Unix timestamp
);

CREATE INDEX idx_user_email ON _user(email);
CREATE INDEX idx_user_admin ON _user(admin);

Query examples:

-- List all users
SELECT id, email, verified, admin, created FROM _user;

-- Find unverified users
SELECT email FROM _user WHERE verified = 0;

-- Count admins
SELECT COUNT(*) FROM _user WHERE admin > 0;

-- Recent users
SELECT email, created FROM _user ORDER BY created DESC LIMIT 10;