Natural Language Command

The nl (natural language) command allows you to query and manage your emails using natural language instead of traditional command-line flags and options.

Overview

This command uses Ollama to parse natural language queries into structured email operations. You can express email commands in plain English and the system will automatically convert them to the appropriate technical operations.

Prerequisites

• Ollama must be installed and running locally (default: http://localhost:11434)
• At least one language model must be installed in Ollama
• EmailOS must be configured with valid email credentials

Usage

mailos nl "natural language query"

Examples

Search Operations

# Find emails from a specific person
mailos nl "show all emails from John this month"

# Search by subject
mailos nl "find emails about invoices"

# Search unread messages
mailos nl "list unread messages from clients today"

# Search with attachments
mailos nl "show emails with attachments from last week"

# Complex searches
mailos nl "find urgent emails from my manager about project updates"

Email Management

# Count emails
mailos nl "how many emails from support this week"

# Summarize content
mailos nl "summarize important emails from yesterday"

# Read specific emails
mailos nl "read email with id 12345"

Flags

• --account EMAIL: Specify which email account to use
• --verbose: Show detailed parsing information and debug output
• --dry-run: Preview what would be executed without actually running the command
• --model MODEL: Specify which Ollama model to use for parsing
• --ollama-url URL: Ollama server URL (default: http://localhost:11434)
• --list-models: List available Ollama models and exit
• --check-ollama: Check Ollama connection and available models

Supported Actions

The natural language parser can handle these types of operations:

• list/show/search: Find and display emails
• read: Read specific email content
• count: Count matching emails
• summarize: Generate summaries of email content

Supported Filters

You can use natural language to specify:

• From/To: "emails from John", "messages to the team"
• Subject: "about meetings", "regarding invoices"
• Date ranges: "today", "this week", "last month", "since Monday"
• Status: "unread messages", "important emails"
• Attachments: "with attachments", "containing files"

Model Recommendations

For Speed

• llama3.2:3b - Fast parsing, good for simple queries
• phi3:mini - Very fast, minimal resource usage

For Accuracy

• llama3.1:8b - Better understanding of complex queries
• llama3.2:7b - Good balance of speed and accuracy

Setup and Configuration

Install Ollama

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Start Ollama service
ollama serve

# Install a recommended model
ollama pull llama3.2:3b

Check Installation

# Verify Ollama is running and check models
mailos nl --check-ollama

# List available models
mailos nl --list-models

Examples with Flags

# Use specific model
mailos nl "find emails from [email protected]" --model llama3.1:8b

# Preview command without executing
mailos nl "delete all spam emails" --dry-run

# Verbose parsing information
mailos nl "show recent invoices" --verbose

# Use specific account
mailos nl "list unread messages" --account [email protected]

Troubleshooting

Ollama Not Found

Error: Cannot connect to Ollama server at http://localhost:11434

• Ensure Ollama is installed: curl -fsSL https://ollama.ai/install.sh | sh
• Start Ollama: ollama serve
• Check if running: ollama list

No Models Available

Error: No models available in Ollama

• Install a model: ollama pull llama3.2:3b
• List available models: ollama list

Parsing Errors

Error: No valid JSON found in model response

• Try a different model: --model llama3.1:8b
• Rephrase your query more clearly
• Use simpler language and specific terms

Slow Performance

Error: Ollama request timed out

• Use a smaller/faster model: ollama pull phi3:mini
• Increase timeout or use simpler queries
• Check system resources

Advanced Usage

Predefined Filters

The system recognizes common email patterns:

• clients → emails from client domains
• invoices → emails about billing/payments
• meetings → emails about meetings/calls
• urgent → important/priority emails
• unread → unread messages only
• today → emails from today
• attachments → emails with file attachments

Custom Ollama Server

# Use remote Ollama instance
mailos nl "find emails" --ollama-url http://remote-server:11434

# Use custom model
mailos nl "search messages" --model custom-model:latest

Integration with Other Commands

The natural language command generates standard mailos commands, so you can:

1. Use --dry-run to see the equivalent command
2. Run the suggested command directly
3. Combine with other mailos features

# See equivalent command
mailos nl "find emails from John" --dry-run
# Output: Would execute: ./mailos search --from John -n 10

# Run the equivalent directly
mailos search --from John -n 10

Security and Privacy

• Natural language queries are processed locally by Ollama
• No data is sent to external services
• All email content remains on your local system
• Ollama models run entirely offline

Performance Tips

1. Use smaller models for faster parsing: phi3:mini, llama3.2:3b
2. Be specific in your queries to reduce ambiguity
3. Use predefined filters when possible
4. Consider using traditional commands for complex operations

See Also

• Search Command - Traditional email search
• Read Command - Reading specific emails
• Setup Guide - Initial configuration
• Installation - Installing EmailOS