Command Reference

--json

Output structured JSON instead of human-readable text. Available on every command.

--dry-run

Show what would happen without making any changes. Writes include a "dry_run": true field in JSON mode.

--version

Print the frm version and exit.

frm init

Interactive setup wizard. Walks you through connecting a CardDAV server (iCloud, Fastmail, or custom) and optionally a JMAP provider for email context. Creates ~/.frm/config.json.

frm init

If a config already exists, you can choose to overwrite it or add another service. Validates the connection before saving.

frm check

Show contacts that are overdue for a catch-up. A contact is overdue when the time since your last interaction exceeds its tracking frequency. Ignores snoozed and ignored contacts.

# See who needs attention
frm check

# Machine-readable output (includes email, phone, org, group, last note)
frm check --json

frm list

List tracked contacts with their frequency, group, and due dates.

• --all — include untracked and ignored contacts

# Tracked contacts only
frm list

# Everyone
frm list --all

frm log <name>

Record an interaction with a contact. Resets their overdue timer.

• --note <text> — note about the interaction
• --when <date> — backdate to YYYY-MM-DD instead of now

frm log "Alice" --note "caught up over coffee"
frm log "Alice" --when 2026-02-15 --note "ran into her at the conference"

frm context <name>

Pre-meeting prep. Shows a contact's name, group, frequency, last interaction, and days until due. If JMAP is configured, includes recent email threads. Aliases: show, detail.

frm context "Alice Smith"
frm context "Alice Smith" --json

frm history <name>

Show the interaction log for a specific contact. Displays dates and notes in chronological order.

frm history "Alice Smith"

frm stats

Dashboard showing totals for contacts (tracked, ignored, untriaged), overdue count, total interactions, and most/least contacted people.

frm stats
frm stats --json

frm triage

Interactive loop through contacts that have no frequency and are not ignored. Shows name, email, org, phone, and email context (if JMAP is configured), then prompts for a frequency.

• --limit <n> — max contacts to show (default 5, use -1 for all)

# Interactive mode
frm triage
frm triage --limit 20

# JSON mode for agents (no prompts)
frm triage --json --limit -1

frm track <name> --every <freq>

Set the tracking frequency for a contact. The --every flag is required.

• --every <freq> — frequency string: 3d, 2w, 1m, etc.

frm track "Alice" --every 2w
frm track "Bob" --every 1m

frm untrack <name>

Remove the tracking frequency from a contact. They will no longer appear in frm check.

frm untrack "Alice"

frm ignore <name>

Permanently hide a contact from triage and check. Skips contacts that are already ignored.

frm ignore "Spam Contact"

frm unignore <name>

Reverse an ignore, making the contact visible in triage and check again.

frm unignore "Alice"

frm snooze <name> --until <date>

Temporarily suppress a contact from check until a given date. Accepts an absolute date or a relative duration.

• --until <date|duration> — e.g. 2026-06-01 or 2m

frm snooze "Alice" --until 2m
frm snooze "Alice" --until 2026-06-01

frm unsnooze <name>

Remove the snooze from a contact so they appear in check immediately.

frm unsnooze "Alice"

frm add <name>

Create a new contact in the first configured CardDAV account.

• --email <addr> — email address
• --phone <num> — phone number
• --org <name> — organization
• --url <url> — website or social URL

frm add "Jane Doe" --email jane@example.com --org "Acme Corp"

frm edit <name>

Update fields on an existing contact. At least one flag must be provided.

• --email <addr> — email address
• --phone <num> — phone number
• --org <name> — organization
• --url <url> — website or social URL

frm edit "Jane Doe" --phone "+1-555-0100" --org "New Company"

frm spread

After a big import, all tracked contacts show as overdue at once. This command randomly staggers snoozes across each contact's frequency interval, so they come due gradually instead of all at once. Only affects tracked contacts that have never been contacted.

• --apply — actually apply the snoozes (default is a preview)

# Preview
frm spread

# Apply
frm spread --apply

frm group set <name> <group>

Assign a contact to a group. Groups are freeform strings — use whatever names make sense to you.

frm group set "Alice" friends
frm group set "Bob" professional

frm group unset <name>

Remove a contact from its group.

frm group unset "Alice"

frm group list

List all groups with their contact counts.

frm group list

frm group members <group>

List all contacts in a specific group.

frm group members friends