Electerm Data Tool

中文文档 (Chinese README)

A command-line utility for managing Electerm application data, including database migration from v1 (NeDB) to v2 (SQLite) and data export functionality.

Features

• 🔄 Database Migration: Migrate Electerm data from v1 (NeDB) to v2 (SQLite)
• 📤 Data Export: Export all Electerm data to a single JSON file with decrypted passwords
• 📊 Database Info: Display information about your current Electerm database
• 🔐 Password Decryption: Automatically decrypt passwords during export for readable backups

Installation

Quick Start with npx (Recommended)

No installation required! Run the tool directly using npx:

npx electerm-data-tool migrate
npx electerm-data-tool export ~/backup.json
npx electerm-data-tool info

Global Installation

npm install -g electerm-data-tool

Usage

Command Overview

Using npx (no installation required):

npx electerm-data-tool [command] [options]

Using globally installed version:

electerm-data-tool [command] [options]

Available commands:

• migrate - Migrate database from v1 to v2
• export <path> - Export all data to JSON file
• info - Display database information
• --help - Show help information
• --version - Show version number

Global Options

• --app-type <type> - Specify application type (desktop or web)
  • desktop (default): Standard Electerm desktop application
  • web: Electerm web application with different path structure
• -d, --data-path <path> - Custom path to electerm data directory (for portable installations)

1. Database Migration

Migrate your Electerm database from v1 (NeDB) to v2 (SQLite):

electerm-data-tool migrate

This command will:

• Check if migration is needed
• Migrate all data from NeDB files to SQLite database
• Create backups of original NeDB files with timestamp
• Perform any necessary data upgrades

Note: Requires Node.js 22.0.0 or higher for SQLite support.

2. Data Export

Export all Electerm data to a JSON file with decrypted passwords:

electerm-data-tool export /path/to/backup.json

Example:

electerm-data-tool export ~/electerm-backup-2025-09-03.json

The exported JSON will contain:

• All bookmarks with decrypted passwords
• Bookmark groups and folder structure
• Terminal themes
• Quick commands
• Profiles
• Configuration settings
• And all other Electerm data

Important: The exported file contains plain-text passwords. Store it securely and delete when no longer needed.

3. Database Information

View information about your current Electerm database:

electerm-data-tool info

This will show:

• Database type (v1 NeDB or v2 SQLite)
• Number of records in each table
• Migration recommendations if applicable

Application Types

The tool supports two application types with different path structures:

Desktop Application (Default)

Standard Electerm desktop application using the default path structure:

electerm-data-tool info
# or explicitly specify desktop type
electerm-data-tool info --app-type desktop

Default paths:

• NeDB files: {APP_PATH}/electerm/users/default_user/electerm.*.nedb
• SQLite files: {APP_PATH}/electerm/users/default_user/electerm*.db

Web Application

Electerm web application with customized path structure:

electerm-data-tool info --app-type web

Web paths:

• NeDB files: {APP_PATH}/nedb-database/users/default_user/electerm.*.nedb
• SQLite files: {APP_PATH}/sqlite/electerm*.db

Custom Data Directory

You can specify a custom data directory using the APP_PATH environment variable:

# Example for web application
export APP_PATH="/path/to/your/data"
electerm-data-tool migrate --app-type web

# Example for desktop application  
export APP_PATH="/custom/path"
electerm-data-tool export backup.json --app-type desktop

Complete web application example:

# Set custom data directory
export APP_PATH="/Users/username/my-electerm-data"

# Check database status
electerm-data-tool info --app-type web

# Export data
electerm-data-tool export backup.json --app-type web

# Migrate from NeDB to SQLite
electerm-data-tool migrate --app-type web

Portable Installations

For portable installations or custom data directories, use the --data-path option:

# Using --data-path option (recommended for portable installations)
electerm-data-tool info --data-path "/path/to/portable/electerm" --app-type desktop
electerm-data-tool export backup.json --data-path "/path/to/portable/electerm" --app-type desktop
electerm-data-tool migrate --data-path "/path/to/portable/electerm" --app-type desktop

# Web application with custom data path
electerm-data-tool info --data-path "/custom/data/directory" --app-type web
electerm-data-tool export backup.json --data-path "/custom/data/directory" --app-type web
electerm-data-tool migrate --data-path "/custom/data/directory" --app-type web

Path Priority:

1. --data-path option (highest priority)
2. APP_PATH environment variable
3. Default system-specific path (lowest priority)

Database Detection

The tool automatically detects whether you're using:

• v1 Database (NeDB): Original file-based database format
• v2 Database (SQLite): New SQLite-based format (Node.js 22+ required)

When exporting data:

• If v1 database is detected, uses NeDB module for data access
• If v2 database is detected, uses SQLite module for data access
• Passwords are automatically decrypted in both cases

Data Structure

Export Format

The exported JSON follows this structure:

{
  "bookmarks": [...],
  "bookmarkGroups": [...],
  "terminalThemes": [...],
  "quickCommands": [...],
  "profiles": [...],
  "config": {...},
  "addressBookmarks": [...],
  "lastStates": [...],
  "data": [...],
  "log": [...],
  "dbUpgradeLog": [...]
}

Password Handling

• Passwords stored in Electerm are encrypted using a simple character-based encryption
• During export, passwords are automatically decrypted to plain text
• The passwordEncrypted flag is removed from exported data
• Exported passwords are human-readable for backup purposes

Requirements

• Node.js: 16.0.0 or higher
• For SQLite (v2): Node.js 22.0.0 or higher

File Locations

The tool operates on Electerm data stored in the standard locations:

Database Files:

• NeDB (v1): ~/.electerm/users/{username}/electerm.{table}.nedb
• SQLite (v2): ~/.electerm/users/{username}/electerm.db

Backup Files: During migration, original NeDB files are renamed with timestamp:

• electerm.bookmarks.nedb-{timestamp}.bak

Examples

Complete Migration Workflow

Using npx (recommended):

# 1. Check current database status
npx electerm-data-tool info

# 2. Export current data as backup
npx electerm-data-tool export ~/electerm-backup-before-migration.json

# 3. Perform migration
npx electerm-data-tool migrate

# 4. Verify migration succeeded
npx electerm-data-tool info

# 5. Export migrated data to verify
npx electerm-data-tool export ~/electerm-backup-after-migration.json

Using globally installed version:

# 1. Check current database status
electerm-data-tool info

# 2. Export current data as backup
electerm-data-tool export ~/electerm-backup-before-migration.json

# 3. Perform migration
electerm-data-tool migrate

# 4. Verify migration succeeded
electerm-data-tool info

# 5. Export migrated data to verify
electerm-data-tool export ~/electerm-backup-after-migration.json

Troubleshooting

Migration Issues

"Migration not needed": Your database is already v2 or no v1 files exist.

SQLite errors: Ensure you're using Node.js 22.0.0 or higher.

Permission errors: Ensure you have read/write access to Electerm data directory.

Export Issues

Empty export: Check that Electerm has been run and contains data.

Encrypted passwords in export: The tool should automatically decrypt passwords. If you see encrypted text, there may be an issue with the decryption module.

General Issues

Command not found: If installed globally, ensure npm global bin directory is in your PATH.

Module errors: Run npm install to ensure all dependencies are installed.

Security Considerations

• Exported files contain plain-text passwords - store securely
• Delete export files after use if they're temporary backups
• File permissions - exported files inherit system default permissions
• Local processing only - no data is transmitted over network

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Related Projects

• Electerm - The main Electerm terminal application
• Electerm Documentation - Official documentation

License

MIT License - see LICENSE file for details.