teems 0.3.3 → 0.8.0

data/lib/teems/commands/cal.rb

@@ -15,6 +15,7 @@ module Teems
         teems cal tentative <N|hash>     Tentatively accept event by # or hash
         teems cal create "Title" [opts]  Create a new event
         teems cal delete <N|hash>        Delete event by # or hash
+        teems cal ics [opts]             Print events as an ICS calendar (for feeds)
 
       OPTIONS:
         --days N             Show events for the next N days (default: 1)
@@ -29,12 +30,30 @@ module Teems
         --json               Output as JSON
         -h, --help           Show this help
 
+      ICS OPTIONS:
+        --all-calendars      Every calendar (holidays, shared ones), not just the
+                             default one. One that cannot be read is skipped with
+                             a warning
+        --days N             Days ahead to include (default: 60)
+        --days-back N        Days back to include (default: 7)
+        --exclude-attendee ADDRS
+                             Leave out events these addresses organize or have
+                             accepted (comma separated), e.g. ones already on
+                             another calendar you subscribe to
+        --name NAME          Calendar name (default: "Outlook (teems)")
+        --no-login           Never open Safari: renew expired tokens silently
+                             from the cached sign-in, or fail (servers, launchd)
+
       CREATE OPTIONS:
-        --start TIME         Start time: "YYYY-MM-DD HH:MM", "today HH:MM",
-                             "tomorrow HH:MM", or "HH:MM" (assumes today)
+        --start TIME         Start time: "now" (the default), "YYYY-MM-DD HH:MM",
+                             "today HH:MM", "tomorrow HH:MM", or "HH:MM" (today)
         --end TIME           End time (default: start + 30 minutes)
         --duration MIN       Duration in minutes (alternative to --end)
-        --all-day            Create an all-day event (use with --date)
+        --all-day            Create an all-day event on --date (default: today)
+                             With --all-day, --start YYYY-MM-DD is an alias for
+                             --date, and --end YYYY-MM-DD is the last day
+                             (inclusive) of a multi-day event. --duration and
+                             timed --start/--end values are not allowed.
         --location TEXT      Event location
         --body TEXT          Event description (plain text)
         --html TEXT          Event description (HTML)
@@ -66,10 +85,16 @@ module Teems
         teems cal accept a3f2            # Accept by hash prefix
         teems cal decline 3 --comment "Out of office"
         teems cal create "Standup" --start "tomorrow 09:00" --duration 15
-        teems cal create "Review" --start "2026-03-20 14:00" --teams \
+        teems cal create "Review" --start "2026-03-20 14:00" --teams \\
           --attendees alice@example.com,bob@example.com
+        teems cal create "Day off" --all-day --date 2026-03-20
+        teems cal create "PTO" --all-day --date 2026-03-23 --end 2026-03-24 \\
+          --show-as oof --no-reminder  # One event spanning both days
         teems cal delete 3               # Delete event #3
         teems cal --json | jq ...        # JSON output, no prompt
+        teems cal ics > work.ics         # 7 days back through 60 ahead
+        teems cal ics --days 30 --days-back 0 --no-login
+        teems cal ics --all-calendars    # Include holiday and shared calendars
     HELP
 
     # Date range computation for calendar queries
@@ -164,7 +189,7 @@ module Teems
       SUBCOMMAND_PARSERS = {
         'show' => :parse_show_subcommand, 'today' => :parse_today_subcommand,
         'tomorrow' => :parse_tomorrow_subcommand, 'create' => :parse_create_subcommand,
-        'delete' => :parse_delete_subcommand
+        'delete' => :parse_delete_subcommand, 'ics' => :parse_ics_subcommand
       }.freeze
 
       private
@@ -205,6 +230,11 @@ module Teems
         @options[:date] = (Date.today + 1).to_s
       end
 
+      def parse_ics_subcommand(remaining)
+        @subcommand = 'ics'
+        remaining.shift
+      end
+
       def parse_rsvp_subcommand(remaining)
         action, event_arg = remaining.shift(2)
         @subcommand = action
@@ -282,11 +312,6 @@ module Teems
         resolve_event_id || 1
       end
 
-      def api_error_result(prefix, err)
-        error("#{prefix}: #{err.message}")
-        1
-      end
-
       def render_single_event(event_id)
         event = fetch_event_for_display(event_id)
         render_event_output(event)
@@ -563,7 +588,15 @@ module Teems
       end
 
       def validate_conflicting_flags
-        conflict_error('--teams', '--no-teams') if @options[:teams] && @options[:no_teams]
+        return conflict_error('--teams', '--no-teams') if @options[:teams] && @options[:no_teams]
+
+        validate_all_day_flags if @options[:all_day]
+      end
+
+      def validate_all_day_flags
+        return conflict_error('--all-day', '--duration') if @options[:duration]
+
+        conflict_error('--date', '--start') if @options[:date] && @options[:start]
       end
 
       def conflict_error(flag_a, flag_b)
@@ -588,11 +621,66 @@ module Teems
       end
     end
 
+    # Resolves --all-day dates into Graph's all-day range, which runs from midnight on the
+    # first day to midnight after the last day. --end is inclusive, like `teems ooo --end`.
+    module CalAllDayTimes
+      include Support::TimeParsing
+
+      private
+
+      def resolve_all_day_times
+        first_day = all_day_first_day
+        return first_day if first_day.is_a?(Integer)
+
+        last_day = all_day_last_day(first_day)
+        return last_day if last_day.is_a?(Integer)
+
+        [midnight(first_day), midnight(last_day + 1)]
+      end
+
+      def all_day_first_day
+        start = @options[:start]
+        return all_day_option_date('--start', start) if start
+
+        date = @options[:date] || Date.today.to_s
+        Date.parse(date)
+      rescue Date::Error
+        all_day_error("Invalid date: #{date}")
+      end
+
+      def all_day_last_day(first_day)
+        raw = @options[:end]
+        return first_day unless raw
+
+        last_day = all_day_option_date('--end', raw)
+        return last_day if last_day.is_a?(Integer) || last_day >= first_day
+
+        all_day_error("--end #{last_day} is before the first day, #{first_day}")
+      end
+
+      # --start and --end name calendar days here, so a time of day is almost certainly a mistake
+      def all_day_option_date(flag, raw)
+        return Date.parse(raw) unless parse_time_input(raw)
+
+        all_day_error("#{flag} must be a date (YYYY-MM-DD) with --all-day, not a time: #{raw}")
+      rescue Date::Error
+        all_day_error("Invalid #{flag} date: #{raw}. Use YYYY-MM-DD")
+      end
+
+      def all_day_error(message)
+        error(message)
+        1
+      end
+
+      def midnight(date) = date.strftime('%Y-%m-%dT00:00:00')
+    end
+
     # Event creation subcommand
     module CalCreateActions
       include Support::TimeParsing
       include CalEventFields
       include CalCreateValidation
+      include CalAllDayTimes
 
       private
 
@@ -623,14 +711,6 @@ module Teems
         @options[:all_day] ? resolve_all_day_times : resolve_timed_event_times
       end
 
-      def resolve_all_day_times
-        date = @options[:date] || Date.today.to_s
-        parsed = Date.parse(date)
-        [parsed.strftime('%Y-%m-%dT00:00:00'), (parsed + 1).strftime('%Y-%m-%dT00:00:00')]
-      rescue Date::Error
-        error("Invalid date: #{date}") || 1
-      end
-
       def resolve_timed_event_times
         start_time = validated_start_time
         return start_time if start_time.is_a?(Integer)
@@ -641,18 +721,12 @@ module Teems
         [format_time(start_time), format_time(end_time)]
       end
 
+      # Now when --start is left out
       def validated_start_time
-        start_input = @options[:start]
-        return missing_start_time_error unless start_input
-
+        start_input = @options[:start] || 'now'
         parse_time_input(start_input) || (error("Invalid start time: #{start_input}") || 1)
       end
 
-      def missing_start_time_error
-        error('Start time required. Use --start "YYYY-MM-DD HH:MM" or --start "today HH:MM"')
-        1
-      end
-
       def compute_end_time(start_time)
         @options[:end] ? parse_explicit_end_time : compute_end_from_duration(start_time)
       end
@@ -735,7 +809,12 @@ module Teems
         '--no-reminder' => ->(opts, _args) { opts[:no_reminder] = true },
         '--no-rsvp' => ->(opts, _args) { opts[:no_rsvp] = true },
         '--no-time-proposals' => ->(opts, _args) { opts[:no_time_proposals] = true },
-        '--hide-attendees' => ->(opts, _args) { opts[:hide_attendees] = true }
+        '--hide-attendees' => ->(opts, _args) { opts[:hide_attendees] = true },
+        '--days-back' => ->(opts, args) { opts[:days_back] = args.shift.to_i },
+        '--exclude-attendee' => ->(opts, args) { opts[:exclude_attendee] = args.shift },
+        '--name' => ->(opts, args) { opts[:name] = args.shift },
+        '--no-login' => ->(opts, _args) { opts[:no_login] = true },
+        '--all-calendars' => ->(opts, _args) { opts[:all_calendars] = true }
       }.freeze
     end
 
@@ -747,6 +826,7 @@ module Teems
       include CalEventActions
       include CalCreateActions
       include CalInteractiveMode
+      include CalIcsExport
 
       def initialize(args, runner:)
         @options = {}
@@ -786,6 +866,7 @@ module Teems
         when 'show' then show_event
         when 'create' then create_event
         when 'delete' then delete_event
+        when 'ics' then export_ics
         when 'accept', 'decline', 'tentative' then rsvp_event
         else list_events
         end

data/lib/teems/commands/cal_ics.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Teems
+  module Commands
+    # `teems cal ics`: events from days-back days ago to days ahead as an ICS calendar,
+    # for a subscription server (outlook-cli's outlook-calendar-server) to serve
+    module CalIcsExport
+      ICS_DEFAULTS = { days: 60, days_back: 7, name: 'Outlook (teems)' }.freeze
+      DAY_SECONDS = 86_400
+
+      private
+
+      def export_ics
+        now = Time.now
+        events = with_token_refresh { fetch_feed_events(now) }
+        excluded = excluded_addresses
+        kept = events.reject { |event| event.involves?(excluded) }
+        # The calendar is the command's result, so -q does not silence it
+        output.print(Formatters::IcsFormat.calendar(kept, name: ics_option(:name), stamp: now))
+        0
+      rescue ApiError => e
+        api_error_result('Failed to fetch calendar', e)
+      end
+
+      # With --all-calendars, a shared calendar that cannot be read is warned about and left
+      # out, so one calendar does not take down the feed
+      def fetch_feed_events(now)
+        api = runner.calendar_api
+        range = { from: ics_start(now), to: ics_end(now) }
+        return api.feed_events(**range) unless @options[:all_calendars]
+
+        api.feed_events(**range, views: api.calendar_views) do |name, error|
+          warn("Skipped calendar #{name.inspect}: #{error.message}")
+        end
+      end
+
+      def ics_option(key) = @options[key] || ICS_DEFAULTS.fetch(key)
+
+      def ics_start(now) = now - (ics_option(:days_back) * DAY_SECONDS)
+
+      def ics_end(now) = now + (ics_option(:days) * DAY_SECONDS)
+
+      # Comma, semicolon or space separated, compared without case
+      def excluded_addresses = @options[:exclude_attendee].to_s.downcase.split(/[\s,;]+/).reject(&:empty?)
+    end
+  end
+end

data/lib/teems/commands/confirmation.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Teems
+  module Commands
+    # Asking before a bulk or irreversible change. Without a terminal there is nobody to ask,
+    # so the caller has to pass --yes instead.
+    module Confirmation
+      private
+
+      # question: "Archive 3 messages"; refusal: the error when there is no terminal
+      def confirm?(question, refusal:)
+        raise Error, refusal unless $stdin.tty?
+
+        output.prompt("#{question}? [y/N] ")
+        $stdin.gets.to_s.strip.downcase.start_with?('y')
+      end
+    end
+  end
+end

data/lib/teems/commands/help.rb

@@ -8,9 +8,11 @@ module Teems
       ['cal', 'List calendar events and view details'],
       ['channels', 'List joined teams and channels'],
       ['chats', 'List recent chats'],
+      ['meet', 'Start a Teams meeting and print its join link'],
       ['meeting', 'View meeting details, chat, transcripts, and recordings'],
       ['transcripts', 'Sync saved meeting transcripts to this machine'],
       ['messages', 'Read messages from a channel or chat'],
+      ['mail', 'Read Outlook mail: list, read, folders, search, sync'],
       ['sync', 'Sync chat history locally'],
       ['who', "Look up a user's profile"],
       ['org', 'Show org chart for a user'],
@@ -85,6 +87,8 @@ module Teems
             teems chats                    List recent chats
             teems messages <channel-id>    Read messages from a channel
             teems transcripts sync         Download recent meeting transcripts
+            teems mail list --unread       Unread messages in the Inbox
+            teems mail read 3f9a2c1b       Read a message from the list
             teems who                      Show your profile
             teems who john                 Search for a user
             teems org                      Show your org chart

data/lib/teems/commands/mail.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module Teems
+  module Commands
+    # list, read, folders, and search for `teems mail`
+    module MailReading
+      DEFAULT_COUNT = 20
+
+      private
+
+      def list_messages
+        folder, count = list_args
+        return error('Count must be a positive number') unless count&.positive?
+
+        show_messages(mail_api.messages(folder: mail_folders.resolve_id(folder), count: count, only: only_filters))
+      end
+
+      # --unread and --flagged limit a listing (both: unread and flagged)
+      def only_filters = Api::Mail::FILTERS.keys.select { |key| @options[key] }
+
+      # [folder] [count]; a lone number is the count
+      def list_args
+        folder, count = positional_args.drop(1)
+        return ['Inbox', Integer(folder)] if !count && folder.to_s.match?(/\A\d+\z/)
+
+        [folder || 'Inbox', Integer(count || @options[:limit] || DEFAULT_COUNT, exception: false)]
+      end
+
+      def search_messages
+        query = positional_args[1]
+        return error('Usage: teems mail search <query> [folder]') if query.to_s.strip.empty?
+
+        count = (@options[:limit] || DEFAULT_COUNT).clamp(1, 1000)
+        show_messages(mail_api.search(query: query, count: count, folder: search_folder))
+      end
+
+      def search_folder
+        name = @options[:folders]&.last || positional_args[2]
+        name && mail_folders.resolve_id(name)
+      end
+
+      def show_messages(messages)
+        id_cache.remember(messages)
+        return json_result(messages.map(&:to_json_hash)) if @options[:json]
+        return print_lines(messages.map(&:tsv_row)) if @options[:tsv]
+
+        rows = mail_formatter.message_rows(messages)
+        rows.empty? ? print_lines([output.gray('No messages found')]) : print_lines(rows)
+      end
+
+      def read_message
+        token = positional_args[1]
+        return error('Usage: teems mail read <id>') unless token
+
+        show_message(mail_api.message(resolve_message_id(token)))
+      end
+
+      def show_message(message)
+        return show_purview(message) if message.protection == 'purview'
+
+        id = message.id
+        envelope = message.bodyless? && envelope_attachment(id)
+        return show_encrypted(message, envelope) if envelope
+
+        warn('Not S/MIME encrypted; nothing to decrypt') if @options[:decrypt]
+        return print_lines([message.body]) if @options[:html]
+
+        render_message(message, message.attachment_names_from(mail_api))
+      end
+
+      # encryption: nil for plain mail, else { type:, decrypted:, signed: } (see MailDecrypting)
+      def render_message(message, names, encryption = nil)
+        return print_lines([message.body]) if @options[:html]
+
+        if @options[:json]
+          return json_result(message.full_json_hash(attachments: names).merge(encryption ? { encryption: } : {}))
+        end
+
+        notes = Models::MailEncryption.notes(encryption, web_link: message.web_link)
+        print_lines([message.to_text(attachments: names, notes: notes)])
+      end
+
+      # Outlook on the web, which opens what teems cannot (Purview protected mail); --print
+      # prints the address instead
+      def open_message
+        token = positional_args[1] or raise Error, 'Usage: teems mail open <id> [--print]'
+        link = mail_api.web_link(resolve_message_id(token)) or raise Error, 'Graph gave no web link for that message'
+        return print_lines([link]) if @options[:print]
+
+        runner.browser.open(link)
+        success('Opened in Outlook on the web')
+        0
+      end
+
+      def list_folders
+        all = mail_folders.all
+        return json_result(all.map(&:to_json_hash)) if @options[:json]
+        return print_lines(all.map(&:tsv_row)) if @options[:tsv]
+
+        print_lines(mail_formatter.folder_rows(all))
+      end
+
+      def json_result(data)
+        output_json(data)
+        0
+      end
+
+      # Data output goes straight to stdout so --quiet only silences status messages
+      def print_lines(lines)
+        lines.each { |line| output.puts(line) }
+        0
+      end
+    end
+
+    # Outlook mail via Microsoft Graph: list, read, folders, search, local sync, and triage
+    # (read state, flags, and moves). Nothing sends mail.
+    class Mail < Base
+      include MailReading
+      include MailDecrypting
+      include MailThread
+      include MailSyncing
+      include MailTriage
+      include MailRules
+      include Confirmation
+      include Support::Timezone
+
+      HELP = MailHelp::TEXT
+
+      SUBCOMMANDS = {
+        'list' => :list_messages, 'recent' => :list_messages, 'read' => :read_message, 'thread' => :show_thread,
+        'open' => :open_message, 'folders' => :list_folders, 'search' => :search_messages, 'sync' => :sync_mail,
+        **MailTriage::ACTIONS.transform_values { :triage }, 'rules' => :mail_rules
+      }.freeze
+
+      FLAGS = { '--unread' => :unread, '--flagged' => :flagged, '--html' => :html, '--tsv' => :tsv,
+                '--attachments' => :attachments, '--no-login' => :no_login, '--dry-run' => :dry_run,
+                '--yes' => :yes, '-y' => :yes, '--decrypt' => :decrypt,
+                '--full' => :full, '--thread' => :thread, '--print' => :print, **MailRuleOptions::FLAGS }.freeze
+      VALUES = { '--since' => :since, '--dir' => :dir, '--folder' => :folders, '--search' => :search,
+                 '--to' => :to, '--due' => :due, **MailRuleOptions::VALUES }.freeze
+      REPEATABLE = [:folders, *MailRuleOptions::REPEATABLE].freeze
+
+      def initialize(args, runner:)
+        @options = {}
+        super
+      end
+
+      def execute
+        validation = validate_options
+        return validation if validation
+
+        handler = SUBCOMMANDS[positional_args.first]
+        return error("Usage: teems mail <#{SUBCOMMANDS.keys.join('|')}> (teems mail --help)") unless handler
+        return error('Rule options (--from, --move-to, ...) go with rules add only') if misplaced_rule_options?
+
+        run_authenticated(handler)
+      end
+
+      protected
+
+      # No default -n: list and search show 20, a triage selection up to 1,000
+      def default_options = super.merge(limit: nil)
+
+      def handle_option(arg, pending)
+        return @options[FLAGS[arg]] = true if FLAGS.key?(arg)
+
+        key = VALUES[arg]
+        return super unless key
+
+        store_value(key, pending.shift.to_s)
+      end
+
+      # --folder repeats (sync takes several), as do rule conditions and categories; other
+      # values keep the last one given
+      def store_value(key, value)
+        REPEATABLE.include?(key) ? (@options[key] ||= []) << value : @options[key] = value
+      end
+
+      def help_text = HELP
+
+      private
+
+      def run_authenticated(handler)
+        auth = require_auth
+        return auth if auth
+
+        with_token_refresh { fresh_attempt(handler) }
+      rescue ApiError => e
+        api_error_result('Mail request failed', e)
+      rescue Teems::Error => e
+        error(e.message)
+      end
+
+      # The folder tree is cached for one attempt: a retry after a token refresh starts over
+      # with the new token
+      def fresh_attempt(handler)
+        @mail_folders = nil
+        send(handler)
+      end
+
+      def mail_api = runner.mail_api
+      def mail_folders = @mail_folders ||= Services::MailFolders.new(mail_api)
+      def mail_formatter = Formatters::MailFormatter.new(output: output)
+      def id_cache = Services::MailIdCache.new
+    end
+  end
+end

data/lib/teems/commands/mail_decrypting.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Teems
+  module Commands
+    # Protected mail for `teems mail read`. Graph hands S/MIME encrypted mail over with an empty
+    # body and its envelope as an smime.p7m attachment; --decrypt opens it with the PIV card
+    # (macOS asks for the PIN) and shows it like any other message. Purview (rights-managed)
+    # mail needs Microsoft's service, so it is only labelled.
+    module MailDecrypting
+      LOCKED_HINT = Models::MailEncryption::LOCKED_HINT
+
+      private
+
+      def envelope_attachment(message_id)
+        mail_api.attachments(message_id).find { |item| Models::MailEncryption.envelope?(item) }
+      end
+
+      def show_purview(message)
+        warn('--decrypt opens S/MIME mail only; Purview protected mail needs Outlook') if @options[:decrypt]
+        warn([message.protection_note, message.web_link].compact.join(': ')) if @options[:html]
+        render_message(message, message.attachment_names_from(mail_api), { type: 'purview', decrypted: false })
+      end
+
+      def show_encrypted(message, envelope)
+        return show_locked(message) unless @options[:decrypt]
+
+        content = decrypt_content(message.id, envelope)
+        render_message(content.apply_to(message), content.attachment_names, Models::MailEncryption.decrypted(content))
+      end
+
+      # The message inside an envelope (an smime.p7m attachment), opened with the PIV card
+      def decrypt_content(message_id, envelope)
+        Services::SmimeContent.parse(runner.smime_decryptor.decrypt(envelope_bytes(message_id, envelope['id'])))
+      end
+
+      def show_locked(message)
+        warn(LOCKED_HINT) if @options[:html] # no header block to carry the hint
+        render_message(message, [], { type: 'smime', decrypted: false })
+      end
+
+      def envelope_bytes(message_id, attachment_id)
+        mail_api.attachment(message_id, attachment_id)['contentBytes'].to_s.unpack1('m')
+      end
+    end
+  end
+end

data/lib/teems/commands/mail_help.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Teems
+  module Commands
+    # `teems mail --help`
+    module MailHelp
+      TEXT = <<~HELP
+        teems mail - Read and triage Outlook mail via Microsoft Graph (never sends)
+
+        USAGE:
+          teems mail list [folder] [count]              Newest messages (alias: recent)
+          teems mail read <id> [--html] [--decrypt]     Headers, plain-text body, numbered links
+          teems mail thread <id> [--full [--decrypt]]   The whole conversation, any folder, oldest first
+          teems mail open <id> [--print]                Open in Outlook on the web (--print: print the link)
+          teems mail folders                            Folders with unread and total counts
+          teems mail search <query> [folder]            Graph $search (KQL), e.g. "from:alice subject:report"
+          teems mail sync [folder...] [options]         Incremental local copy (Graph delta)
+
+        TRIAGE:
+          teems mail mark-read <id>...                  Mark read (mark-unread: unread)
+          teems mail flag <id>... [--due DATE]          Flag for follow-up (unflag: clear it)
+          teems mail archive <id>...                    Move to Archive
+          teems mail move <id>... --to FOLDER           Move to a folder
+          teems mail delete <id>...                     Move to Deleted Items (never purges)
+
+          Instead of IDs, select messages with --search QUERY [--folder NAME] or
+          --folder NAME [--unread] [--flagged] (up to 1,000; -n for fewer). A selection
+          is confirmed first: answer the prompt, or pass --yes. --dry-run lists the
+          messages without changing them. --thread adds the rest of each named message's
+          conversation (not what sits in Sent Items, Drafts, Deleted Items, or Junk Email)
+          and is confirmed the same way.
+
+        RULES (Inbox rules, applied by Exchange as mail arrives):
+          teems mail rules                              List them in order (alias: rules list)
+          teems mail rules add <name> <conditions> <actions>
+          teems mail rules enable <rule>                Turn on (disable: turn off)
+          teems mail rules delete <rule>                Remove (asks first; --yes skips)
+
+          <rule> is a name, the number rules lists, or an ID (--tsv shows them).
+          Conditions (repeatable; a message must match each kind given):
+            --from ADDR  --sent-to ADDR  --subject TEXT  --body TEXT
+          Actions: --move-to FOLDER  --copy-to FOLDER  --mark-read  --category NAME
+            --importance low|normal|high  --delete (to Deleted Items)  --stop (skip later rules)
+          --disabled adds the rule turned off, and --dry-run shows it without adding it.
+          Rules never forward or redirect mail, and one that does is not turned on.
+
+        OPTIONS:
+          --unread          list, triage --folder: only unread messages
+          --flagged         list, triage --folder: only flagged messages
+          --html            read: print the raw HTML body
+          --decrypt         read, thread --full: open S/MIME encrypted mail with your PIV card (asks for the PIN)
+          --full            thread: print every message as read does
+          --thread          triage: act on the named messages' whole conversations
+          --folder NAME     search: limit to a folder; sync: folder to sync (repeatable)
+          --search QUERY    triage: act on the messages a KQL search finds
+          --to FOLDER       move: destination folder
+          --due DATE        flag: due date (YYYY-MM-DD, today, tomorrow, or a weekday)
+          --dry-run         triage: list what would change, change nothing
+          -y, --yes         triage: act on a selection without asking
+          --tsv             list/search/folders/thread: tab-separated output with full IDs
+          -n, --limit N     list: count (default 20); search: max results (default 20)
+          --json            JSON output
+
+        SYNC OPTIONS:
+          --dir DIR         Store root (default ~/.local/share/teems/sync/mail)
+          --since DAYS      First sync of a folder: only mail from the last DAYS days,
+                            or "all" (default 90). Later runs fetch only changes.
+                            Graph caps a first sync limited by DAYS at 5,000 messages
+                            per folder; use "all" for more.
+          --attachments     Also download file attachments to <Folder>/attachments/
+          --no-login        Never open Safari: renew expired tokens silently from the
+                            cached sign-in, or fail (for launchd and cron)
+
+        Folders are names ("Inbox", "Sent Items", "Projects/EERT"), well-known names
+        (inbox, archive, sent, drafts, deleted, junk), or Graph folder IDs. IDs from
+        list and search are short handles; read and triage accept them or full Graph IDs.
+
+        Sync writes one Markdown file per message plus <Folder>/index.json, and keeps
+        delta links in ~/.local/state/teems/mail-sync.json. Syncing into a directory an
+        older outlook-cli sync filled (e.g. ~/Mail) adopts its files instead of
+        duplicating them. Removed messages keep their file; the index marks them.
+      HELP
+    end
+  end
+end