ecm-cli

A command-line interface for the Earth Class Mail API.

Manage your virtual mailbox from the terminal - list mail, request scans, archive, shred, and more.

Installation

# Clone the repository
git clone https://github.com/csima/ecm-cli.git
cd ecm-cli

# Install dependencies
npm install

# Build
npm run build

# Link globally (optional)
npm link

Configuration

API Key

You need an Earth Class Mail API key to use this CLI. Configure it using one of these methods (in order of priority):

1. Command-line flag: --api-key <key>
2. Environment variable: ECM_API_KEY
3. Config file: Run ecm config set api-key <your-key>

# Set API key in config file
ecm config set api-key your-api-key-here

# Or use environment variable
export ECM_API_KEY=your-api-key-here

Default Inbox

Optionally set a default inbox to avoid specifying it for every command:

ecm config set default-inbox-id 12345

Usage

ecm [options] [command]

Global Options

Option	Description
-V, --version	Output version number
--api-key <key>	API key (overrides config and env)
--json	Output as JSON
-h, --help	Display help

Commands

Authentication

# Test API connection and show current user
ecm auth

Inboxes

# List all inboxes
ecm inbox list

Mail

# List mail in default inbox (or first inbox)
ecm mail list

# List mail in a specific inbox
ecm mail list 12345

# List with pagination
ecm mail list --limit 50 --page 2

# Filter by scan status
ecm mail list --scanned
ecm mail list --unscanned

# Show details for a specific mail piece
ecm mail show 67890

# Get media/scans for a mail piece
ecm mail media 67890

# Request a scan
ecm mail scan 67890

# Archive a mail piece
ecm mail archive 67890

# Shred a mail piece
ecm mail shred 67890

# Email scans to an address
ecm mail email 67890 [email protected]
ecm mail email 67890 [email protected] --message "Here are the scans"

Configuration

# Show current configuration
ecm config show

# Set a configuration value
ecm config set api-key <value>
ecm config set default-inbox-id <inbox-id>

# Clear a configuration value
ecm config unset api-key
ecm config unset default-inbox-id

JSON Output

All commands support --json for machine-readable output:

ecm mail list --json | jq '.[] | {id, sender: .sender.name}'

Development

# Run in development mode (no build required)
npm run dev

# Build TypeScript
npm run build

# Run built version
npm start

Requirements

• Node.js >= 18.0.0
• Earth Class Mail account with API access

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

Disclaimer

This project is not affiliated with or endorsed by Earth Class Mail. Use at your own risk.