Skip to main content

​
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., [email protected])Must contain an @ symbol
​
UUID
string
User’s unique identifier (e.g., 550e8400-e29b-41d4-a716-446655440000)Standard UUID format
trail user verify [email protected] 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.
trail user add [email protected] SecureP@ssw0rd123

# Output: Added user '[email protected]'
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.
trail user change-password [email protected] NewP@ssw0rd456

# Output: Updated password for '[email protected]'
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.
trail user change-email [email protected] [email protected]

# Output: Updated email for '[email protected]'
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.
trail user verify [email protected] true

# Output: Set verified=true for '[email protected]'
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 [email protected]

# Output: Sessions invalidated for '[email protected]'
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 [email protected]

# 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 [email protected])

# 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).
trail user delete [email protected]

# Output: Deleted user '[email protected]'
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 [email protected]

​
Admin Management

​
admin list

List all users with admin privileges. 
trail admin list
Example output: 
                                   id	email	created	updated
550e8400-e29b-41d4-a716-446655440000	[email protected]	2024-01-15T10:30:00Z	2024-03-07T14:22:00Z
6ba7b810-9dad-11d1-80b4-00c04fd430c8	[email protected]	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).
trail admin promote [email protected]

# Output: Promoted user to admin for '[email protected]'
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).
trail admin demote [email protected]

# Output: Demoted admin to user for '[email protected]'
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.
trail user import --auth0-json users.ndjson --dry-run

# Output:
# Importing 150 users.
# (No actual import, validation only)
Auth0 export format: Auth0 exports users in NDJSON format (one JSON object per line): 
{"user_id":"auth0|123","email":"[email protected]","email_verified":true,...}
{"user_id":"auth0|456","email":"[email protected]","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

# 1. Add user
trail user add [email protected] SecureAdminP@ssw0rd

# 2. Promote to admin
trail admin promote [email protected]

# 3. Verify admin status
trail admin list

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

​
Handling Forgotten Passwords

# 1. User contacts you about forgotten password

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

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

# 4. Instruct user to change password after login

​
Emergency 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 [email protected] EmergencyP@ss123
trail admin promote [email protected]

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

# 4. Delete emergency account
trail user delete [email protected]

​
Bulk User Operations

# users.csv format: email,password
# [email protected],Password123
# [email protected],Password456

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

# 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

# 1. Invalidate all sessions
trail user invalidate-session [email protected]

# 2. Change password
trail user change-password [email protected] NewSecureP@ss789

# 3. If admin, consider temporary demotion
trail admin demote [email protected]

# 4. Notify user
trail email \
  --to [email protected] \
  --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 [email protected]

​
Troubleshooting

​
User Not Found

Error: Could not find user: [email protected] Solutions: 
# Check if user exists
sqlite3 traildepot/data/main.db "SELECT email FROM _user WHERE email = '[email protected]'"

# 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 = '[email protected]'"

# Delete existing user if appropriate
trail user delete [email protected]

# Or modify existing user instead of creating new one
trail user change-password [email protected] 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 [email protected] AdminP@ss123
trail admin promote [email protected]

# Verify multiple admins exist
trail admin list

# Now safe to demote
trail admin demote [email protected]

​
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;

Build docs developers (and LLMs) love

Get started for freeTalk to us