NitroDigest CLI design

[Frodigo]

Hello there, I am collecting feedback about NitroDigest CLI, which Is a tool for developers that TLDR emails privately using local LLM (Ollama). More info about the tool in the README

Naming

I want to keep it short and easy to type. nitro looks like a good idea. I checked, and there are some existing tools with nitro in the name but I didn't find a CLI tool with an exact nitro name:

• AWS Nitro Enclaves CLI: nitro-cli
• Nuxt.js Nitro: it's not a CLI tool.

I wonder if nitro is a good name, or is too general?

The main command will be nitro email digest, which looks fine.
I thought about the nitrodigest name, but the command nitrodigest email digest doesn't look good.

CLI commands

All NitroDigest commands follow this pattern:

nitro [global-options] <source> <command> [command-options]

Where:

• <source> is the data source type (email, slack, github, etc.) (in the prototype version there is only email)
• <command> is the specific action to perform

Global options

These options can be used with any command:

-h, --help                  Show help information
-v, --verbose               Enable verbose output
--config PATH               Path to configuration file (default: config.json)
--no-color                  Disable colored output
--source SOURCE             Default source to use (overrides config)
--summarizer TYPE           Default summarizer to use (overrides config)

Email source commands

email digest - Process and summarize emails

nitro email digest [options]

Options:

--limit N                   Maximum number of emails to process (default: 5)
--output-dir PATH           Directory to save summaries (default: "summaries")
--mark-as-read              Mark processed emails as read
--credentials NAME          Named email credentials to use (from config)
--email ADDRESS             Email address (overrides credentials/config)
--password PASSWORD         Email password (overrides credentials/config)
--server HOST               IMAP server (overrides credentials/config)
--port N                    IMAP port (overrides credentials/config)
--folder NAME               Email folder to process (default: "INBOX")
--timeout SECONDS           Timeout in seconds for API requests (default: 300)
--prompt-file PATH          Path to custom prompt template file
--prompt TEXT               Direct prompt content (overrides prompt-file)
--model NAME                Model name for the summarizer (default: from config)
--filter QUERY              Filter emails by criteria (e.g., "from:newsletter@example.com")

Examples:

# Process 10 unread emails using default email account
nitro email digest --limit 10

# Process unread emails from work account with custom prompt
nitro email digest --credentials work --prompt-file work_summary.txt

email list - List emails in folder

nitro email list [options]

Options:

--limit N                   Maximum number of emails to list (default: 10)
--credentials NAME          Named email credentials to use (from config)
--email ADDRESS             Email address (overrides credentials/config)
--password PASSWORD         Email password (overrides credentials/config)
--server HOST               IMAP server (overrides credentials/config)
--port N                    IMAP port (overrides credentials/config)
--folder NAME               Email folder to list from (default: "INBOX")
--unread-only               Only show unread emails (default: true)
--format FORMAT             Output format: table, json, csv (default: table)
--sort-by FIELD             Sort by: date, from, subject (default: date)
--filter QUERY              Filter emails by criteria

Examples:

# List unread emails from personal account
nitro email list --credentials personal

# List all emails (read and unread) from work account, Newsletter folder
nitro email list --credentials work --folder "Newsletters" --unread-only false

email accounts - Manage email accounts

nitro email accounts <subcommand> [options]

Subcommands:

list - List configured email accounts

nitro email accounts list

add - Add a new email account

nitro email accounts add <name> [options]

Options:

--email ADDRESS             Email address
--password PASSWORD         Email password
--server HOST               IMAP server (default: auto-detect from email domain)
--port N                    IMAP port (default: 993)
--folder NAME               Default folder (default: "INBOX")

Example:

# Add a new work email account
# Prompt for password interactively (most secure)
nitro email accounts add work --email work@example.com

# Read password from a file
nitro email accounts add work --email work@example.com --password-file /path/to/password.txt

# Read from environment variable
nitro email accounts add work --email work@example.com --password-env EMAIL_PASSWORD

remove - Remove an email account

nitro email accounts remove <name> [--force]

test - Test connection to an email account

nitro email accounts test <name>

email folders - Work with email folders

nitro email folders <subcommand> [options]

Configuration for Multi-Source Setup

The configuration structure for multiple sources:

{
  "default_source": "email",
  "default_summarizer": "ollama",
  "summaries_path": "summaries",
  
  "sources": {
    "email": {
      "accounts": {
        "personal": {
          "default": true,
          "address": "personal@example.com",
          "password": "personal-password",
          "server": "imap.example.com",
          "port": 993,
          "default_folder": "INBOX"
        },
        "work": {
          "address": "work@company.com",
          "password": "work-password",
          "server": "mail.company.com",
          "port": 993,
          "default_folder": "INBOX"
        }
      },
      "settings": {
        "limit": 10,
        "mark_as_read": true
      }
    }
  },
  
  "summarizers": {
    "ollama": {
      "default": true,
      "model": "mistral",
      "base_url": "http://localhost:11434",
      "timeout": 300,
      "prompt_file": "prompts/email_summary.txt"
    }
  }
}

Email workflow examples

Processing emails from multiple accounts

# List unread emails in personal account
nitro email list --credentials personal --limit 5

# List unread emails in work account
nitro email list --credentials work --limit 5

Email filtering

# List emails matching a specific pattern
nitro email list --filter "subject:report" --credentials work

# Process only emails from a specific sender
nitro email digest --filter "from:updates@github.com" --mark-as-read

# Process emails from multiple folders
nitro email digest --folder "Newsletters,Updates" --limit 10

Ollama configuration

summarizers ollama - Manage Ollama configuration

nitro summarizers ollama <subcommand> [options]

Subcommands:

configure - Configure Ollama settings

nitro summarizers ollama configure [options]

Options:

--base-url URL              Set base URL for Ollama (default: http://localhost:11434)
--timeout SECONDS           Set timeout in seconds (default: 300)
--model NAME                Set default model name (default: mistral)
--prompt-file PATH          Set default prompt template file
--test                      Test connection after configuring

Examples:

# Configure Ollama with basic settings
nitro summarizers ollama configure --model llama2 --timeout 180

# Configure Ollama with custom URL (e.g., for Docker setup)
nitro summarizers ollama configure --base-url http://192.168.1.100:11434 --test

test - Test Ollama connection

nitro summarizers ollama test

Example:

# Test if Ollama server is accessible with current configuration
nitro summarizers ollama test

models - Manage Ollama models

nitro summarizers ollama models <subcommand> [options]

Subcommands:

• list - List available models

  nitro summarizers ollama models list [--details]
  

• pull - Pull a new model

  nitro summarizers ollama models pull <model_name>
  

• info - Show details about a specific model

  nitro summarizers ollama models info <model_name>
  

Examples:

# List all available models
nitro summarizers ollama models list

# Pull a specific model
nitro summarizers ollama models pull mistral

# Get information about a model
nitro summarizers ollama models info llama2

---

If you have any feedback, just write a comment below. Thanks in advance!

[nestak]

Hey!

I wonder what are the intended boundaries of this program. I see examples such as nitro summarizers ollama models list, which seem problematic. The program would need to actually know much more about ollama and its API. This looks like unnecessary maintenance burden. Even more so, because ollama has its own cli, right? So, why use this program over ollama directly?

This also is counter to the unix way of doing small programs that can collaborate with each other. Maybe that was not your goal, however the unix way has many benefits. (As a side note, I recommend a great book, The Art of Unix Programming
by Eric Steven Raymond.)

Email accounts and credentials management is another area which I wonder if can be simplified. For example, when using curl, you can use a widely adopted standard of saving credentials using a .netrc file, so you don't need to type in usernames and passwords. Did you consider using it?

Put another way: why would I want to store credentials in another (application-specific in this case) configuration file?

Of course there are some implications of using netrc, see here, but that is a problem the user needs to deal anyway. And if NitroDigest implements storing credentials, would they be encrypted or cleartext? Is there a benefit here over using netrc?

Moving on to configuration – I think it is better to keep things flat than nested, which python seem to promote. I think JSON is not the best format for configuration.

In regards to naming – I think this is not a big issue, since any command can be aliased to whatever a user desires. I suggest to name it simple and to the point, and not be too abstract or vague about what this program does.

These are my quick thoughts on the matter. I did not intend to criticize your design, only to give some ideas and a point of view, so maybe it will be useful. Cheers!

[Frodigo]

Thanks @nestak! valid points

I wonder what are the intended boundaries of this program.

Well, I think I fell into the trap of overengineering.

Example: Does this tool really need to read emails? No, a user can use another existing tool (this can be even CURL as you mentioned) that reads emails and just passes text that they want to summarize to nitrodigest

Email accounts and credentials management is another area which I wonder if can be simplified. For example, when using curl, you can use a widely adopted standard of saving credentials using a .netrc file, so you don't need to type in usernames and passwords. Did you consider using it?

No, I didn't consider it, but after your comments and our conversation on chat, I am close to the approach that Nitrodigest shouldn't read emails at all, so my credentials for email are not needed anymore in this case.

In fact, this tool can be simplified to two use cases:

nitrodigest  <file_text>  # make summary of text file
nitrodigest <directory with text files> # make a summary of files in a specific directory 

Based on that, the value that Nitrodigest offers to the user is:

• Preparing text before sending it to LLM. For example: extract text from HTML
• split long text into chunks that can be processed using smaller models
• providing a prompt or a set of prompts that were evaluated and work well for the given use case,
• providing examples and predefined automation scripts/jobs

Again, thanks for your comment and discussion. Chatting with a real person gives such huge value that no AI can give 😄

[nestak]

Hey,
I think the new direction is interesting, and worth investigating.

Preparing text before sending it to LLM. For example: extract text from HTML

I wonder if pandoc would fit: curl <fetch_something> | pandoc --from html --to plain | digest.
It supports wide range of formats, see https://pandoc.org/try/

[Frodigo]

will check it, thanks

[nestak]

I found a similar tool, but for summarizing web pages, see https://github.com/dahlia/yoyak

They support a few differend backends (models), and define prompt here https://github.com/dahlia/yoyak/blob/main/src/summary.ts

May be interesting read.

[Frodigo]

Good one, but it doesn't work with local LLMs

[Frodigo]

I implemented many things we discussed here in this PR: #124

Closing this discussion for now. Feel free to reopen if needed or create a new one.

Thanks!