Personal Information Management

Keystone provides a suite of CLI tools from the Pimalaya project for managing email, calendars, contacts, and timers. All tools share the same credential pattern — when mail is configured, calendar and contacts auto-default from it. No extra secrets needed.

Tools Overview

Configuration

Enable Everything

If mail is already configured, enabling the other tools requires one line each:

keystone.terminal.mail = {
  enable = true;
  accountName = "personal";
  email = "me@example.com";
  displayName = "My Name";
  login = "me";
  host = "mail.example.com";
  passwordCommand = "cat /run/agenix/mail-password";
};

keystone.terminal.calendar.enable = true;
keystone.terminal.contacts.enable = true;
keystone.terminal.timer.enable = true;

Calendar and contacts inherit accountName, host, login, and passwordCommand from the mail module. Override any option explicitly if needed.

Generated Config Files

Each tool gets a TOML config in ~/.config/:

These are managed by Home Manager — don't edit them manually.

Email (Himalaya)

List Inbox

himalaya envelope list
himalaya envelope list -f "Sent Items"

Read a Message

himalaya message read <id>

Send an Email

Always include a Date: header. Without it, emails show as 1970-01-01.

echo "From: me@example.com
To: recipient@example.com
Subject: Hello
Date: $(date -R)
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8

Message body here" | himalaya message send

Folder Names

Stalwart uses different folder names than Himalaya defaults. The module auto-maps them:

Calendars (Calendula)

Calendula connects to Stalwart's CalDAV endpoint at /dav/cal.

List Calendars

calendula calendars list

List Events

calendula items list <calendar-id>

Update an Event

calendula item update <calendar-id> <item-id>

This opens the iCalendar (.ics) data in your $EDITOR.

Contacts (Cardamum)

Cardamum connects to Stalwart's CardDAV endpoint at /dav/card.

List Address Books

cardamum addressbooks list

List Contacts

cardamum cards list <addressbook-id>

Update a Contact

cardamum card update <addressbook-id> <card-id>

This opens the vCard (.vcf) data in your $EDITOR.

Timers (Comodoro)

Comodoro is a centralized Pomodoro timer with a client-server architecture. Multiple clients can control the same timer session.

Default Cycles

The keystone module configures standard Pomodoro cycles:

Start the Server

comodoro server start

Control the Timer

comodoro timer start    # Start the first cycle
comodoro timer get      # Show current timer state
comodoro timer pause    # Pause
comodoro timer resume   # Resume

Notifications

The module enables desktop notifications by default:

• Work started — "Work started!"
• Rest started — "Take a break!"
• Long rest started — "Long break time!"

OS Agents

Agents provisioned via keystone.os.agents automatically receive email, calendar, and contacts when mail is enabled. No extra configuration is needed — credentials are derived from the agent's mail account.

Verify an agent's access:

agentctl drago exec himalaya envelope list
agentctl drago exec calendula calendars list
agentctl drago exec cardamum addressbooks list

Stalwart DAV Endpoints

All CalDAV/CardDAV access goes through Stalwart's built-in DAV support:

The modules use direct URIs (home-uri) rather than discovery because Stalwart's well-known redirects trigger a nginx 400 on the follow-up PROPFIND.

Debugging

Authentication Failures

The login field is the Stalwart account name (e.g., ncrmro), not the email address. Using the email as login causes auth failures for all tools.

Connection Issues

# Test CalDAV directly
curl -X PROPFIND -u "username:password" -H "Depth: 0" \
  https://mail.example.com/dav/cal

# Test CardDAV directly
curl -X PROPFIND -u "username:password" -H "Depth: 0" \
  https://mail.example.com/dav/card

Debug Logging

All Pimalaya tools support --debug for verbose output:

himalaya --debug envelope list
calendula --debug calendars list
cardamum --debug addressbooks list