slk 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c56010125fc8e78293e4701ac5619742dda1fecd3e6e06ec98a3eb6afab0dc46
-  data.tar.gz: 05fad0411c6b216091bc9dd7cade46a36579bbba951042c61859111c57db9356
+  metadata.gz: c7db83e915de4b86bafd0cc62e8a67fdaee0dcd9209cb94a1f8fd6a5a2704c46
+  data.tar.gz: eb25d2aafaa23a51016e64c2f5eb40c0117aeacb829d784caff9a50078946992
 SHA512:
-  metadata.gz: 2ae292c3c50580e4872ec7a2334052b2495d0df8943341970d98f0a1922ea5b15d9612a0b8998de30bfb100100d3daf0567c9270fafef89529fc88c65f72634d
-  data.tar.gz: e86c76ce090e6a622a2122c068fb8a384520ff7b38193613f254f446f4a4165f09c48bcf944b2f3d5a2ad3435a0e71502bda8a6ec1b776b0b1b4bbc1ee240424
+  metadata.gz: 2d928dbf2906c22dc3ad108503c6ef4bfaeb68c29c0ed562dcd27e3515cf1468df426801dc6f7e73a3c2f9bb47d79fd7bf90054b3a9fc424453a35e8f60fd75d
+  data.tar.gz: 93850e6e114cd1634ce2546631b1c370eb94731ff284eb29c05c458a533f16fb1229afde2ca27f60e6ea2e00d12828d6db17342f1d336350cc59d5ae788cc1bb

data/CHANGELOG.md

@@ -5,6 +5,53 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.11.0] - 2026-09-23
+
+### Changed
+
+- `slk sent` now expands your sent-message search hits into conversations: full paginated threads and DMs, merged channel windows (5 messages before and 30 minutes after your posts), and replies to your top-level posts. It groups by conversation and caps displayed messages with `--max` (default 200, `0` for all). `--before` and `--after-minutes` tune channel windows. `--mine` keeps the previous flat timeline and JSON shape.
+- `slk sent --json` now returns `{date, range, conversations}`. Each conversation includes its workspace, channel, type, thread timestamp, `last_speaker_is_me`, `dropped_messages`, and chronological messages with sender, name, text, and `mine`. `channel_name` remains Slack's raw value; `channel_label` is the resolved display label for DMs and channels. The sender-only format remains available through `--mine --json`, with `channel_label` added to counts.
+
+- `slk sent` text now wraps to the interactive terminal's width (or `--width N`), with indented reply and context continuations; `--no-wrap` disables wrapping. The redundant `▶` marker on your own messages and the last-speaker status lines are gone from text output; JSON still includes `last_speaker_is_me`. Thread headings now show the thread ID instead of repeating the parent message; channel and DM headings keep their readable names. A thin divider separates conversations without splitting context from new messages. Orphaned replies put their parent reference on a separate line so long thread IDs do not steal the message's wrap width.
+
+### Added
+
+- `slk sent --changed-since TIME` shows a stateless diff of conversations you participated in over `--lookback DAYS` (default 7). TIME accepts local `H:MM` or `HH:MM`, ISO datetime, Slack epoch/ts, or `90m`/`2h`/`1d`; clock times use the latest local occurrence (yesterday when that time has not arrived today). Search discovers conversations, but exact-timestamp history and replies determine what changed: old threads and DMs with new replies appear even when you did not post today. Channel chatter alone does not count; channel windows are fetched only for your own new top-level posts. Changed output orders conversations by latest activity, newest at the bottom, and includes up to `--context N` earlier messages (default 2). Text marks older context with `·` without a separate cutoff divider; JSON labels each new message. JSON adds `changed_since: {iso, ts}`, `lookback_days`, per-conversation `new_count` and `new_from_others`, and per-message `new`, retaining the flat, timestamp-sorted `thread_ts` contract. Thread subscriptions contribute unread followed threads when available. A paginated history scan per watched channel identifies active thread roots from Slack's `latest_reply` (rather than probing every root); quiet DMs use a one-message history probe. Edits/reactions do not change message timestamps; conversations you never posted in and very recent posts missing from Slack's search index remain blind spots.
+- `slk sent [today|yesterday|YYYY-MM-DD]` finds conversations you posted in, across workspaces by default. `--since YYYY-MM-DD` searches through today, `-w` selects a workspace, and `--mine` shows only your indexed messages in a flat chronological timeline with per-channel counts. Slack's index can lag, excludes deleted messages, and uses your profile timezone for date operators; DM history bounds use your local timezone.
+
+### Fixed
+
+- `slk sent` now orders conversations with exact Slack timestamps and workspace/channel/thread tie-breakers, so identical start times stay deterministic across platforms.
+- `slk sent --changed-since` no longer silently omits followed threads when their lookup fails due to network, rate-limit, authentication, or malformed-response errors. Unsupported or unauthorized-to-use subscription views still fall back to search-derived conversations. Sender lookup caches the authenticated user ID and reports a workspace-specific API error if Slack omits it. Deleted threads are recognized by Slack's error code, not message text, and invalid-time errors are limited to actual input conversions. Text wrapping falls back to 72 columns if a terminal cannot report its width.
+- `slk sent` now includes the first post of each channel window in Slack history (and expands its replies), displays DM names even for threads, resolves group-DM participants, and shows file-only thread parents through file labels. Expanded replies now appear nested beneath their parent in text output, while JSON remains flat and timestamp-sorted with `thread_ts` links.
+- Attachment and unfurl preview titles, authors, text, and image labels now decode HTML entities like message bodies.
+- `slk search --all` now searches every workspace and tags each result. Search paginates past Slack's 100-result page size when `-n` requests more, and warns when the requested limit cuts off matches.
+
+## [0.10.0] - 2026-09-18
+
+### Added
+
+- **`slk deactivations --tenure`** — how long each person stayed
+  - Start dates come from the workspace's "Start Date" custom profile field, discovered from the team schema rather than hardcoded, since every workspace numbers its own fields. A date-typed field wins over a text one with the same label
+  - `users.list` does not carry custom fields, so this costs one `users.profile.get` per person, and Slack rate-limits that endpoint to roughly eight calls a minute. The command says how long it will take before it starts, and only looks up the rows it is about to show
+  - Every answer is cached the moment it arrives, not at the end, so interrupting a long lookup keeps the work already paid for. Accounts with no start date on file are cached too, otherwise every run would pay again to learn the same nothing
+  - Tenure is counted in whole months: somebody who started on the 20th and left on the 3rd has not completed that month. An end date before the start is a data entry error rather than a negative tenure, and reads as blank
+  - Blank means nobody filled the field in, and the column disappears entirely when no start date is known. `--tenure` with `--chart` is refused rather than ignored — a histogram has no row to hang a tenure on
+- **`slk deactivations --csv`** — the spreadsheet that always gets asked for
+  - Writes every match rather than the screenful `-n` would show: a truncated export is a wrong answer that looks like a right one
+  - With `--tenure` it gains `started_on`, `tenure_months` and a readable `tenure` column; unknown start dates leave empty cells rather than zeros, so averaging tenure in a spreadsheet skips them instead of counting people who left the day they arrived
+  - RFC 4180 quoting, hand-rolled, because Ruby 3.4 moved csv out of the default gems and this tool ships with no dependencies
+  - Progress and warnings go to stderr, so `slk deactivations --csv > file.csv` captures only data
+
+### Fixed
+
+- **A cache that cannot be written no longer costs you the run.** `MetaCache.write` returns disk failures instead of raising them: a full or read-only disk means "no cache", not "no answer". This mattered most for start date lookups, which sit behind minutes of rate-limited calls, but it also fixed the deactivation roster scan, which crashed outright on an unwritable cache directory. Other exceptions still raise — a bug in the value being cached is not a disk problem
+- **A cache that cannot be read no longer crashes.** An unreadable cache file now warns and is skipped, the same way a corrupt one already was. The file is left in place rather than deleted, since removing it needs the access that just failed
+- **A malformed API response fails as an API error.** Slack replying with a JSON array, string or null instead of an object used to surface as `TypeError` or `NoMethodError` from whichever command happened to dig into it first
+- **`slk cache clear` now clears all caches.** It removed only the user and channel caches while reporting "Cleared all caches"; start dates, deactivation rosters and resolved profiles survived it
+
 ## [0.9.0] - 2026-09-18
 
 ### Added

data/README.md

@@ -217,6 +217,8 @@ slk deactivations                 # 25 most recent departures
 slk deactivations 90d             # Everyone who left in the last 90 days
 slk deactivations 2026-01-01 -n 0 # All departures this year
 slk deactivations --chart         # Departures per month
+slk deactivations --tenure        # Add how long each person stayed
+slk deactivations 1y --csv        # Spreadsheet export of a year of departures
 slk deactivations --grep engineer # Filter by name, handle, title, email, or ID
 slk deactivations --bots          # Include deactivated bots and app users
 slk deactivations --json          # Machine-readable output
@@ -240,6 +242,41 @@ forward, so treat it as "last touched" rather than a payroll record.
 The roster costs one API call per 1000 members, so the result is cached for six
 hours; `--refresh` re-fetches it.
 
+#### Tenure
+
+`--tenure` adds how long each person was here, taken from the workspace's
+"Start Date" profile field:
+
+```
+acme: 3 deactivated since 30d (664 active members)
+
+2026-09-14  Dana Whitfield         1mo  Platform Support
+2026-09-11  Priya Raghunathan   2y 7mo  UX Researcher
+2026-09-09  Sam Okonkwo        4y 10mo  Senior Software Engineer
+```
+
+This one is slow the first time. Start dates are not in the roster — they cost
+one `users.profile.get` per person, and Slack rate-limits that endpoint to
+roughly eight calls a minute, so a screenful takes about three minutes. The
+command says so before it starts, only looks up the rows it is about to show,
+and caches each answer the moment it arrives: interrupting it keeps the work
+already paid for, and the second run is instant.
+
+Blank means nobody filled the field in. Months are whole months, so somebody
+who started on the 20th and left on the 3rd has not completed that month.
+
+#### CSV
+
+`--csv` writes every match — not just the screenful `-n` would show, since a
+truncated export is a wrong answer that looks like a right one. Combine it with
+`--tenure` for `started_on`, `tenure_months` and a readable `tenure` column:
+
+```bash
+slk deactivations 1y --tenure --csv > departures.csv
+```
+
+Progress and warnings go to stderr, so the redirect above captures only data.
+
 ### Global Options
 
 ```bash

data/lib/slk/api/conversations.rb

@@ -15,17 +15,21 @@ module Slk
         @api.post(@workspace, 'conversations.list', params)
       end
 
-      def history(channel:, limit: 20, cursor: nil, oldest: nil, latest: nil)
+      # rubocop:disable Metrics/ParameterLists
+      def history(channel:, limit: 20, cursor: nil, oldest: nil, latest: nil, inclusive: false)
         params = { channel: channel, limit: limit }
         params[:cursor] = cursor if cursor
         params[:oldest] = oldest if oldest
         params[:latest] = latest if latest
+        params[:inclusive] = true if inclusive
         @api.post(@workspace, 'conversations.history', params)
       end
+      # rubocop:enable Metrics/ParameterLists
 
-      def replies(channel:, timestamp:, limit: 100, cursor: nil)
+      def replies(channel:, timestamp:, limit: 100, cursor: nil, oldest: nil)
         params = { channel: channel, ts: timestamp, limit: limit }
         params[:cursor] = cursor if cursor
+        params[:oldest] = oldest if oldest
         # Use form encoding - some workspaces (Enterprise Grid) require it
         @api.post_form(@workspace, 'conversations.replies', params)
       end

data/lib/slk/cli.rb

@@ -15,6 +15,7 @@ module Slk
       'activity' => Commands::Activity,
       'later' => Commands::Later,
       'search' => Commands::Search,
+      'sent' => Commands::Sent,
       'preset' => Commands::Preset,
       'workspaces' => Commands::Workspaces,
       'cache' => Commands::Cache,

data/lib/slk/commands/cache.rb

@@ -65,6 +65,14 @@ module Slk
         0
       end
 
+      # Every kind, including the meta cache behind start dates, deactivation
+      # rosters and resolved profiles — "cleared" should not have exceptions.
+      def clear_every_cache(workspace_name)
+        cache_store.clear_user_cache(*[workspace_name].compact)
+        cache_store.clear_channel_cache(*[workspace_name].compact)
+        cache_store.clear_meta_cache(*[workspace_name].compact)
+      end
+
       def display_workspace_status(workspace)
         puts output.bold(workspace.name) if target_workspaces.size > 1
         display_cache_counts(workspace)
@@ -87,15 +95,8 @@ module Slk
       end
 
       def clear_cache(workspace_name)
-        if workspace_name
-          cache_store.clear_user_cache(workspace_name)
-          cache_store.clear_channel_cache(workspace_name)
-          success("Cleared cache for #{workspace_name}")
-        else
-          cache_store.clear_user_cache
-          cache_store.clear_channel_cache
-          success('Cleared all caches')
-        end
+        clear_every_cache(workspace_name)
+        success(workspace_name ? "Cleared cache for #{workspace_name}" : 'Cleared all caches')
 
         0
       end

data/lib/slk/commands/deactivations.rb

@@ -8,16 +8,31 @@ module Slk
     #   slk deactivations 90d             # everyone who left in the last 90 days
     #   slk deactivations --chart         # departures per month
     #   slk deactivations --grep engineer # filter by name, handle, title, email, ID
+    #   slk deactivations --tenure        # add how long each person stayed
+    #   slk deactivations --csv           # spreadsheet export of every match
     # rubocop:disable Metrics/ClassLength
     class Deactivations < Base
       DEFAULT_LIMIT = 25
       CHART_MONTHS = 12
+      # Measured against a live workspace: users.profile.get answers two or
+      # three calls in a row, then makes you wait out a thirty second
+      # Retry-After — about eight lookups a minute averaged over a long run,
+      # which is what the time estimate is built on.
+      LOOKUPS_PER_MINUTE = 8
+      COST_WARNING_AT = 5
+      SWITCHES = {
+        '--chart' => :chart, '--bots' => :bots, '--tenure' => :tenure, '--csv' => :csv,
+        '--refresh' => :refresh, '--no-cache' => :refresh
+      }.freeze
 
       def execute
         result = validate_options
         return result if result
 
         run
+      rescue Services::StartDateLookup::MissingFieldError => e
+        error(e.message)
+        1
       rescue ApiError => e
         error("API error: #{e.message}")
         1
@@ -26,18 +41,21 @@ module Slk
       protected
 
       def handle_option(arg, args, _remaining)
+        return switch_on(SWITCHES[arg]) if SWITCHES.key?(arg)
+
         case arg
         when '-n', '--limit' then @options[:limit] = parse_limit(arg, option_value(arg, args))
         when '--since' then @options[:since] = option_value(arg, args)
-        when '--chart' then @options[:chart] = true
-        when '--bots' then @options[:bots] = true
         when '--grep' then @options[:grep] = option_value(arg, args)
-        when '--refresh', '--no-cache' then @options[:refresh] = true
         else return super
         end
         true
       end
 
+      def switch_on(key)
+        @options[key] = true
+      end
+
       def help_text
         help = Support::HelpFormatter.new('slk deactivations [since] [options]')
         help.description('Show deactivated accounts — who left the workspace, and when.')
@@ -76,33 +94,50 @@ module Slk
           s.option('-n, --limit N', "Rows to show (default #{DEFAULT_LIMIT}, 0 for all)")
           s.option('--since SPEC', 'Only departures since 7d, 4w, 6m, or YYYY-MM-DD')
           s.option('--chart', 'Histogram of departures per month')
+          s.option('--tenure', 'Add how long each person stayed (slow: one lookup per person)')
           s.option('--grep PATTERN', 'Filter by name, handle, title, email, or user ID')
           s.option('--bots', 'Include deactivated bots and app users')
-          s.option('--refresh', 'Re-fetch the roster instead of using the cache')
-          s.option('--json', 'Raw JSON output')
+          add_output_options(s)
         end
       end
 
+      def add_output_options(section)
+        section.option('--refresh', 'Re-fetch the roster instead of using the cache')
+        section.option('--csv', 'CSV of every match, for a spreadsheet')
+        section.option('--json', 'Raw JSON output')
+      end
+
       def add_examples_section(help)
         help.section('EXAMPLES') do |s|
           s.example('slk deactivations', 'Most recent departures')
           s.example('slk deactivations 90d', 'Everyone who left in the last 90 days')
           s.example('slk deactivations --chart', 'Departures per month')
+          s.example('slk deactivations --tenure', 'How long each person stayed')
+          s.example('slk deactivations 1y --csv > left.csv', 'Export a year of departures')
           s.example('slk deactivations 2026-01-01 -n 0', 'All departures this year')
         end
       end
 
       def run
         workspace = runner.workspace(@options[:workspace])
+        validate_combination
         @since_label = since_spec
         @since = parse_since(@since_label)
         report = scan(workspace)
         records = collect_records(report)
 
+        emit(workspace, report, records)
+        0
+      end
+
+      # --csv and --json export every match; the terminal list is the only
+      # view that pages, so it is the only one -n applies to. (--chart spans
+      # its whole window too, for the same reason.)
+      def emit(workspace, report, records)
+        return render_csv(workspace, records) if @options[:csv]
         return render_json(workspace, report, records) if @options[:json]
 
         render(workspace, report, records)
-        0
       end
 
       # One window, or none. A second date is a different question, and
@@ -114,16 +149,98 @@ module Slk
         @options[:since] || positional_args.first
       end
 
+      # A histogram counts departures per month; it has no row to hang a
+      # tenure on. Refusing beats quietly ignoring the flag someone paid
+      # attention to type.
+      # Two ways of asking for the same rows is one too many, and picking a
+      # winner silently means the other flag looks broken.
+      def validate_combination
+        raise UsageError, '--tenure has nothing to add to --chart; drop one of them.' if
+          @options[:tenure] && @options[:chart]
+        raise UsageError, '--csv and --json are two different exports; pick one.' if
+          @options[:csv] && @options[:json]
+      end
+
       def collect_records(report)
         records = filter(report.records)
         @options[:chart] && @since.nil? ? last_year(records) : records
       end
 
       def render_json(workspace, report, records)
-        output_json(json_payload(workspace, report, records))
+        output_json(json_payload(workspace, report, records, tenures(workspace, records)))
         0
       end
 
+      def render_csv(workspace, records)
+        Formatters::DeactivationCsv.new(
+          output: output, tenures: @options[:tenure] ? tenures(workspace, records) : nil
+        ).render(records)
+        0
+      end
+
+      # Start dates cost one rate-limited call each, so they are only ever
+      # fetched for rows that will actually be shown. The caller has already
+      # applied -n (or deliberately not, for an export); this memo assumes one
+      # record set per run, which is what a single command does.
+      def tenures(workspace, records)
+        return {} unless @options[:tenure]
+
+        @tenures ||= resolve_tenures(workspace, records)
+      end
+
+      def resolve_tenures(workspace, records)
+        lookup = start_date_lookup(workspace)
+        announce_cost(lookup, records)
+        dates = begin
+          lookup.fetch(records.map(&:user_id))
+        ensure
+          # Even when the lookup raises: otherwise the error message arrives
+          # glued to a half-drawn "start dates: 12/40".
+          output.clear_progress
+        end
+        report_cache_error(lookup)
+        records.to_h { |r| [r.user_id, Models::Tenure.build(dates[r.user_id], r.deactivated_time)] }
+      end
+
+      # The answers still arrived; they just will not be there next time.
+      def report_cache_error(lookup)
+        return unless lookup.cache_error
+
+        warn("Could not save the start date cache (#{lookup.cache_error}). " \
+             'These lookups will have to be repeated next run.')
+      end
+
+      def start_date_lookup(workspace)
+        Services::StartDateLookup.new(
+          users_api: runner.users_api(workspace.name),
+          field: start_date_field(workspace),
+          workspace_name: workspace.name,
+          cache_store: cache_store,
+          on_progress: ->(done, total) { output.progress("start dates: #{done}/#{total}") }
+        )
+      end
+
+      def start_date_field(workspace)
+        Services::StartDateField.new(
+          team_api: runner.team_api(workspace.name),
+          workspace_name: workspace.name,
+          cache_store: cache_store,
+          on_debug: ->(msg) { output.debug(msg) }
+        )
+      end
+
+      # Better to say how long this will take than to let someone wonder
+      # whether the terminal has hung.
+      def announce_cost(lookup, records)
+        pending = lookup.uncached_count(records.map(&:user_id))
+        return if pending < COST_WARNING_AT
+
+        minutes = [(pending.to_f / LOOKUPS_PER_MINUTE).round, 1].max
+        warn("Looking up #{pending} start dates, one profile call each. Slack rate-limits these " \
+             "to about #{LOOKUPS_PER_MINUTE} a minute, so this will take roughly #{minutes} " \
+             "minute#{'s' if minutes > 1}. Interrupting is safe: each answer is cached as it arrives.")
+      end
+
       def scan(workspace)
         Services::DeactivationScanner.new(
           users_api: runner.users_api(workspace.name),
@@ -192,7 +309,7 @@ module Slk
       def render(workspace, report, records)
         formatter = Formatters::DeactivationFormatter.new(output: output, width: @options[:width])
         formatter.summary(summary_line(workspace, report, records))
-        render_body(formatter, records)
+        render_body(formatter, workspace, records)
         footer = footer(report, records)
         return if footer.empty?
 
@@ -202,17 +319,19 @@ module Slk
 
       # Even an empty result keeps its footer: "nobody matched" is worth much
       # less without how old the roster behind it is.
-      def render_body(formatter, records)
+      def render_body(formatter, workspace, records)
         return info('No deactivations match.') if records.empty?
 
         puts
-        @options[:chart] ? formatter.chart(records, **chart_bounds) : render_list(formatter, records)
+        return formatter.chart(records, **chart_bounds) if @options[:chart]
+
+        render_list(formatter, workspace, records)
       end
 
-      def render_list(formatter, records)
+      def render_list(formatter, workspace, records)
         limit = @options[:limit] || DEFAULT_LIMIT
         shown = limit.positive? ? records.first(limit) : records
-        formatter.list(shown)
+        formatter.list(shown, tenures: tenures(workspace, shown))
         return unless shown.size < records.size
 
         puts
@@ -267,7 +386,7 @@ module Slk
         Models::Duration.new(seconds: seconds).to_s
       end
 
-      def json_payload(workspace, report, records)
+      def json_payload(workspace, report, records, tenures = {})
         {
           workspace: workspace.name,
           fetched_at: report.fetched_at,
@@ -276,9 +395,20 @@ module Slk
           total_deactivated: total_deactivated(report),
           includes_bots: @options[:bots] ? true : false,
           matched: records.size,
-          deactivations: records.map { |r| r.to_h.merge(deactivated_on: r.date) }
+          deactivations: records.map { |r| json_entry(r, tenures) }
         }
       end
+
+      # started_on and tenure_months appear only when they were asked for:
+      # a null that means "not looked up" is indistinguishable from one that
+      # means "nobody filled it in".
+      def json_entry(record, tenures)
+        entry = record.to_h.merge(deactivated_on: record.date)
+        return entry unless @options[:tenure]
+
+        tenure = tenures[record.user_id]
+        entry.merge(started_on: tenure&.started, tenure_months: tenure&.months)
+      end
     end
     # rubocop:enable Metrics/ClassLength
   end

data/lib/slk/commands/help.rb

@@ -12,6 +12,7 @@ module Slk
         ['dnd', 'Manage Do Not Disturb'],
         ['messages', 'Read channel or DM messages'],
         ['search', 'Search messages across channels'],
+        ['sent', 'Show your sent messages across workspaces'],
         ['unread', 'View and clear unread messages'],
         ['activity', 'Show activity feed (reactions, mentions, threads)'],
         ['later', 'Show saved "Later" items'],
@@ -84,6 +85,7 @@ module Slk
             slk status schedule "Vet" 1p-3p  Schedule a status (am/pm or 24h)
             slk dnd 1h                       Enable DND for 1 hour
             slk messages #general            Read channel messages
+            slk sent                         Show messages you sent today
             slk preset meeting               Apply preset
         EXAMPLES
       end

data/lib/slk/commands/search.rb

@@ -41,8 +41,8 @@ module Slk
       # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/AbcSize
       def handle_option(arg, args, remaining)
         case arg
-        when '-n', '--limit' then @options[:limit] = require_value(arg, args).to_i
-        when '--page' then @options[:page] = require_value(arg, args).to_i
+        when '-n', '--limit' then @options[:limit] = positive_integer(arg, args)
+        when '--page' then @options[:page] = positive_integer(arg, args)
         when '--in' then @options[:in_channel] = require_value(arg, args)
         when '--from' then @options[:from_user] = require_value(arg, args)
         when '--after' then @options[:after_date] = require_value(arg, args)
@@ -56,11 +56,19 @@ module Slk
 
       def require_value(option, args)
         value = args.shift
-        raise ArgumentError, "#{option} requires a value" unless value
+        raise ArgumentError, "#{option} requires a value" unless value && !value.start_with?('-')
 
         value
       end
 
+      def positive_integer(option, args)
+        value = require_value(option, args)
+        number = Integer(value, exception: false)
+        raise ArgumentError, "#{option} expects a positive integer" unless number&.positive?
+
+        number
+      end
+
       def help_text
         help = Support::HelpFormatter.new('slk search <query> [options]')
         help.description('Search messages across channels and DMs.')
@@ -84,11 +92,12 @@ module Slk
 
       def add_options_section(help)
         help.section('OPTIONS') do |s|
-          s.option('-n, --limit N', 'Number of results (default: 20, max: 100)')
-          s.option('--page N', 'Page number for pagination')
+          s.option('-n, --limit N', 'Results per workspace (default: 20; paginates past 100)')
+          s.option('--page N', 'Starting page in each workspace')
           s.option('--threads', 'Show thread replies inline')
           s.option('--json', 'Output as JSON')
-          s.option('-w, --workspace', 'Specify workspace')
+          s.option('-w, --workspace NAME', 'Specify workspace')
+          s.option('--all', 'Search every workspace (results tagged by workspace)')
           s.option('-v, --verbose', 'Show debug information')
           s.option('-q, --quiet', 'Suppress output')
         end
@@ -110,23 +119,19 @@ module Slk
         1
       end
 
-      # rubocop:disable Metrics/MethodLength
       def search_and_display(query)
-        workspace = target_workspaces.first
-        full_query = build_query(query)
+        raise ArgumentError, 'Use either --all or --workspace, not both' if @options[:all] && @options[:workspace]
 
+        full_query = build_query(query)
         debug("Searching: #{full_query}")
-        response = runner.search_api(workspace.name).messages(
-          query: full_query,
-          count: @options[:limit],
-          page: @options[:page]
-        )
-
-        results = parse_results(response)
-        display_results(results, workspace, response)
+        searches = target_workspaces.map do |workspace|
+          [workspace, Services::SearchPages.new(runner.search_api(workspace.name)).fetch(
+            query: full_query, limit: @options[:limit], page: @options[:page]
+          )]
+        end
+        display_results(searches)
         0
       end
-      # rubocop:enable Metrics/MethodLength
 
       def build_query(base_query)
         parts = [base_query]
@@ -138,47 +143,50 @@ module Slk
         parts.join(' ')
       end
 
-      def parse_results(response)
-        matches = response.dig('messages', 'matches') || []
-        matches.map { |m| Models::SearchResult.from_api(m) }
-      end
-
-      def display_results(results, workspace, response)
+      def display_results(searches)
         if @options[:json]
-          output_json_results(results, response)
+          output_json_results(searches)
         else
-          display_text_results(results, workspace, response)
+          display_text_results(searches)
         end
       end
 
-      def output_json_results(results, response)
-        pagination = response.dig('messages', 'pagination') || {}
-        output_json({
-                      results: results.map(&:to_h),
-                      pagination: {
-                        page: pagination['page'],
-                        page_count: pagination['page_count'],
-                        total_count: pagination['total_count']
-                      }
-                    })
+      def output_json_results(searches)
+        results = searches.flat_map do |workspace, data|
+          data[:results].map { |result| result.to_h.merge(workspace: workspace.name) }
+        end
+        output_json(results: results, pagination: json_pagination(searches))
       end
 
-      def display_text_results(results, workspace, response)
-        show_pagination_info(response) if @options[:verbose]
-
-        if results.empty?
-          puts 'No results found.'
-          return
+      def json_pagination(searches)
+        pages = searches.to_h do |workspace, data|
+          [workspace.name, data[:pagination].merge('truncated' => data[:truncated] == true)]
         end
+        searches.length == 1 ? pages.values.first : pages
+      end
 
-        results.each_with_index do |result, index|
+      def display_text_results(searches)
+        searches.each { |workspace, data| report_search(workspace, data) }
+        entries = searches.flat_map { |workspace, data| data[:results].map { |result| [result, workspace] } }
+        return puts 'No results found.' if entries.empty?
+
+        entries.each_with_index do |(result, workspace), index|
           display_single_result(result, workspace)
-          puts if index < results.length - 1
+          puts if index < entries.length - 1
         end
       end
 
+      def report_search(workspace, data)
+        show_pagination_info(data[:pagination], workspace) if @options[:verbose]
+        return unless data[:truncated]
+
+        total = data[:pagination]['total_count']
+        quantity = total ? "#{data[:results].length} of #{total}" : data[:results].length.to_s
+        warn("#{workspace.name}: Showing #{quantity} matches; raise -n for more.")
+      end
+
       def display_single_result(result, workspace)
-        runner.search_formatter.display_result(result, workspace, format_options)
+        runner.search_formatter.display_result(result, workspace, format_options.merge(workspace_label: @options[:all]))
         show_thread_replies(result, workspace) if should_show_thread?(result)
       end
 
@@ -209,13 +217,12 @@ module Slk
         lines[1..].each { |line| puts "    #{line}" }
       end
 
-      def show_pagination_info(response)
-        pagination = response.dig('messages', 'pagination') || {}
+      def show_pagination_info(pagination, workspace)
         total = pagination['total_count'] || 0
         page = pagination['page'] || 1
         page_count = pagination['page_count'] || 1
 
-        debug("Page #{page}/#{page_count} (#{total} total results)")
+        debug("#{workspace.name}: Page #{page}/#{page_count} (#{total} total results)")
       end
     end
     # rubocop:enable Metrics/ClassLength