GroundEffect CLI

GroundEffect provides local-first email and calendar management with semantic search capabilities. All data is synced locally and searchable offline.

Quick Reference

Email Commands

groundeffect email search "query"              # Search emails with natural language
groundeffect email list                        # List recent emails
groundeffect email show <id>                   # Show single email
groundeffect email thread <thread_id>          # Show email thread
groundeffect email send --to X --subject "X" --body "X"  # Send email
groundeffect email send --to X --subject "X" --body "X" --html  # Send HTML email
groundeffect email send --to X --subject "X" --body "X" --save-as-draft  # Save as draft
groundeffect email attachment <email_id> <filename>      # Get attachment
groundeffect email folders                     # List IMAP folders

Draft Commands

groundeffect email draft create --from X --to X --subject "X" --body "X"  # Create draft
groundeffect email draft create --from X --to X --subject "X" --body "X" --reply-to <email_id>  # Reply draft
groundeffect email draft list --from X                   # List drafts
groundeffect email draft show --from X --draft-id <id>   # Show draft
groundeffect email draft update --from X --draft-id <id> --body "X"  # Update draft
groundeffect email draft send --from X --draft-id <id>   # Send draft
groundeffect email draft delete --from X --draft-id <id> # Delete draft

Calendar Commands

groundeffect calendar events                   # List events by date range (no query needed)
groundeffect calendar events --from 2026-01-07 --to 2026-01-08 --human  # Tomorrow's events
groundeffect calendar search "query"           # Search events with semantic search
groundeffect calendar list                     # List calendars
groundeffect calendar show <event_id>          # Show event details
groundeffect calendar create --summary "X" --start "ISO" --end "ISO"  # Create event

Calendar Events vs Calendar Search:

• Use calendar events when the user asks "what's on my calendar tomorrow/next week" (date-based, no query)
• Use calendar search when the user asks "find meetings about project X" (semantic search)

Account Commands

groundeffect account list                      # List all accounts
groundeffect account show <email|alias>        # Show account details
groundeffect account add                       # Add new Google account
groundeffect account delete <email|alias>      # Remove account
groundeffect account configure <email|alias>   # Update settings

Sync Commands

groundeffect sync status                       # Check sync status
groundeffect sync reset <email|alias>          # Reset synced data
groundeffect sync extend <email|alias>         # Sync older emails
groundeffect sync download-attachments <email|alias>  # Download pending attachments

Daemon Commands

groundeffect daemon install                    # Install launchd daemon (auto-start at login)
groundeffect daemon uninstall                  # Remove launchd daemon
groundeffect daemon status                     # Check if daemon running
groundeffect daemon restart                    # Restart daemon

Config Commands

groundeffect config settings                   # View/modify daemon settings
groundeffect config add-permissions            # Add Claude Code permissions
groundeffect config remove-permissions         # Remove Claude Code permissions

Important Guidelines

DRAFTS: When the user asks to "save as draft", "draft an email", or "save this draft", ALWAYS use the groundeffect email draft create command to save it to Gmail drafts. Do NOT save email drafts to markdown files - use Gmail's native draft system so the user can access, edit, and send drafts from any device.

SENDING: When composing an email, use groundeffect email send --save-as-draft to save to Gmail drafts, or add --confirm to send immediately. Without these flags, the command returns a preview.

Usage Notes

• CLI binary: groundeffect
• Output format: JSON by default, use --human for readable output
• Date format: Use YYYY-MM-DD for date parameters
• Account references: Use email address or alias interchangeably
• Help: Add --help to any command for detailed options

Detailed Documentation

For complete command documentation with all flags and examples, read the appropriate reference file:

• Email: references/email-commands.md - search, list, show, thread, send (HTML support), attachment, folders, drafts
• Calendar: references/calendar-commands.md - search, list, show, create
• Accounts: references/account-commands.md - list, show, add, delete, configure
• Sync: references/sync-commands.md - status, reset, extend, download-attachments
• Daemon: references/daemon-commands.md - install, uninstall, status, restart
• Config: references/config-commands.md - settings, add-permissions, remove-permissions

Common Workflows

See examples/common-workflows.md for step-by-step usage patterns.