slk 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 139ba582e24a6b92cd79493c0000a1479fbeb4ce59c90d883d0bbb603e8ff4c7
-  data.tar.gz: 81bdd74fc8a1d9b44480272098f78744297b3bd2b42b39dbc25c7f1fdb891c2f
+  metadata.gz: 895e4fdd405a7b4f560424a93d4906ea7330088763a5559b2d581788908794b3
+  data.tar.gz: 6f8c66d9cd6555153db454d99d7cafdf4e82bbaac2f6349edee1427047e31104
 SHA512:
-  metadata.gz: f79c404a79de6d32c77e85226b92b65322ff159ae610201d3514abc66fc9f8497a30c29da802b81e0ed2f36cdb3bc805835eee0e85f744f0f323d2620391c483
-  data.tar.gz: 6fff7a3b9b11762d179ccd2d22e5a0e4a6e395f52bd4fe89810cb045fed144c989026c07928179efdcd35e8ac3c3c991dab8f90344042cd0475adc8fc1007d7e
+  metadata.gz: 7394318fac53168225d5ff30a249612a0f756fe60eaca67141ca937d43f8c70aaa7a1066681bb35a97fc49f242254d87438f369b02700193cc86456ded97ca9c
+  data.tar.gz: ea890ffc51e6540c6a19db3481d92b8f0263c042594f74c4ec2ac3f975c7f988d345f69e0a6b37345993b499535180b87456cd189dffa9506b2c60148f2b9481

data/CHANGELOG.md

@@ -5,7 +5,34 @@ 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.7.0] - 2026-08-03
+
+### Added
+
+- **`slk status schedule|scheduled|unschedule`** — queue statuses to turn on later
+  - `slk status schedule "<text>" [:emoji:] <start-end>` schedules a status; emoji defaults to `:speech_balloon:`
+  - Time windows accept bare 12- or 24-hour times (`1:30p-3:30p`, `13:30-15:30`) or an explicit `YYYY-MM-DD` date (`2026-08-04 9:00-17:00`)
+  - Bare times resolve forward: a window at or before now rolls to tomorrow, and an end before the start crosses midnight (`11p-1a`)
+  - A single am/pm carries across the range, so `1-3p` is 1pm to 3pm — unless that would invert it, leaving `9-5p` as 9am to 5pm
+  - Ambiguous or impossible windows are rejected rather than guessed: `9-5` and `9a-5` (both read as crossing midnight and spanning 20 hours), `1p-1p`, a time DST skips, and unrecognized date forms such as `8/4` or `tomorrow`
+  - The check applies only to a reading that had to be guessed, and only past 12 hours, so windows that say what they mean still work: `11p-1a`, `8p-9a`, `20:00-09:00`, `20:00-6`, and `9p-5`
+  - `--start WHEN` / `--end WHEN` take `[YYYY-MM-DD ]TIME` each, for windows the single-date range cannot express: `--start "2026-08-12 8a" --end "2026-08-14 5p"`. Omitting `--end` schedules a status with no expiry
+  - `--with-dnd` also pauses notifications while the status is active
+  - `slk status scheduled` lists pending statuses with their IDs across every workspace; `slk status unschedule <id>` looks up which workspace owns the ID rather than assuming the primary one (`-w`/`--all` still override)
+  - `slk status scheduled` marks the one Slack reports as currently applied with `[active]`
+  - Backed by Slack's internal `users.customStatus.*` endpoints, which require form-encoded bodies and only return the scheduled section when `statuses_count_per_section` is sent. Responses are checked rather than trusted: an absent `scheduled_statuses` section, a create that echoes nothing back, a status payload with no id, and a delete the following list still shows all raise instead of reporting success
+
+### Changed
+
+- New `Slk::UsageError` (bad invocation) and `Slk::TimeFormatError` (unparseable time) error types. `slk` prints them without an error-type label, and callers can rescue malformed input without also swallowing arity or range errors from their own code
+- Flags that take a value now reject a missing one or a following flag instead of shifting `nil`. This covers `--start`, `--end`, `-p` and `-d` on `status`, and `-w`/`--workspace` everywhere — a trailing `slk status -w` previously applied to *every* workspace and exited 0
+
+### Fixed
+
+- `slk status unschedule` no longer reports a successful cancel as a failure when the confirming re-read fails (a network error, a rate limit, or Slack dropping the `scheduled_statuses` section — which is exactly what happens when you cancel your only scheduled status). The cancel is reported with an explicit "could not confirm" caveat and exit 0; only a status still demonstrably present is an error
+- `slk status schedule` again reports an unusable Slack response as "check the status picker to see whether it was created" rather than the less actionable "returned a scheduled status with no id"
+- `Slk::UsageError` no longer files a backtrace in `~/.cache/slk/error.log`; a mistyped flag is not a fault to investigate later
+- SSH key validation no longer hangs on Windows when the private key is passphrase-protected. `ssh-keygen` prompts on the console rather than on stdin, so the prompt could not be answered or dismissed; it is now given an empty passphrase up front and reports the unsupported key instead of waiting
 
 ## [0.6.0] - 2026-04-27
 
@@ -183,6 +210,8 @@ Initial release of the Ruby rewrite. Pure Ruby, no external dependencies.
   - Pure Ruby stdlib - no gem dependencies
   - Ruby 3.2+ with modern features (Data.define, pattern matching)
 
+[0.7.0]: https://github.com/ericboehs/slk/releases/tag/v0.7.0
+[0.6.0]: https://github.com/ericboehs/slk/releases/tag/v0.6.0
 [0.5.0]: https://github.com/ericboehs/slk/releases/tag/v0.5.0
 [0.4.2]: https://github.com/ericboehs/slk/releases/tag/v0.4.2
 [0.4.0]: https://github.com/ericboehs/slk/releases/tag/v0.4.0

data/README.md

@@ -52,6 +52,37 @@ slk status "In a meeting" :calendar: 1h # Set status for 1 hour
 slk status clear                        # Clear status
 ```
 
+Statuses can also be scheduled to turn on later (Slack allows up to 5 at a time):
+
+```bash
+slk status schedule "Vet Appt" :paw_prints: 1:30p-3:30p       # Bare times; rolls to tomorrow if past
+slk status schedule "OOO" :palm_tree: 2026-08-04 9:00-17:00   # Explicit date
+slk status schedule "Heads down" :no_bell: 11p-1a --with-dnd  # Overnight, pausing notifications
+slk status scheduled                                          # List pending (all workspaces)
+slk status unschedule CS0BMQDDGWTU                            # Cancel one (finds the owning workspace)
+```
+
+A single am/pm carries across the range, so `1-3p` is 1pm to 3pm — unless that
+would invert it, leaving `9-5p` as 9am to 5pm. Anything the am/pm cannot settle
+is read as a 24-hour time, which is usually right but occasionally means the
+opposite of what you typed: `9-5` and `9a-5` both come out as 9am until 5am the
+next morning. Windows that land that way — guessed, crossing midnight, and over
+12 hours — are rejected rather than scheduled, so add the second am/pm (`9a-5p`)
+or use 24-hour times (`9:00-17:00`).
+
+Overnight windows are fine when they say so. A meridiem on both sides (`11p-1a`,
+`8p-9a`) or a 24-hour time on either side (`20:00-09:00`, `20:00-6`) settles the
+range, and a pm start is enough on its own: `9p-5` is 9pm to 5am.
+
+A `start-end` range writes the date once and the end can only reach the next
+day, so multi-day windows use `--start` / `--end` instead. Each takes
+`[YYYY-MM-DD ]TIME`, and omitting `--end` schedules a status with no expiry:
+
+```bash
+slk status schedule "OOO" :palm_tree: --start "2026-08-12 8a" --end "2026-08-14 5p"
+slk status schedule "Heads down" :no_bell: --start 2p         # Stays until cleared
+```
+
 ### Presence
 
 ```bash

data/lib/slk/api/custom_status.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Slk
+  module Api
+    # Wrapper for Slack's internal users.customStatus.* endpoints, which back
+    # the "Scheduled" section of the status picker.
+    #
+    # Two undocumented quirks these methods paper over:
+    #   - Only form-encoded bodies are accepted. A JSON body is ignored and the
+    #     call fails with invalid_arguments naming every field as missing.
+    #   - list omits scheduled_statuses entirely unless
+    #     statuses_count_per_section is passed.
+    class CustomStatus
+      DEFAULT_SECTION_COUNT = 20
+
+      def initialize(api_client, workspace)
+        @api = api_client
+        @workspace = workspace
+      end
+
+      # @return [Hash] raw response; 'statuses' (recent) and 'scheduled_statuses'
+      #   (pending) are each absent when Slack omits the section
+      def list(count_per_section: DEFAULT_SECTION_COUNT)
+        @api.post_form(@workspace, 'users.customStatus.list',
+                       { statuses_count_per_section: count_per_section.to_s })
+      end
+
+      # @return [Array<Models::ScheduledStatus>] pending statuses only
+      def scheduled(count_per_section: DEFAULT_SECTION_COUNT)
+        response = list(count_per_section: count_per_section)
+        section = response['scheduled_statuses']
+        # An absent section is a protocol change, not an empty list. Reporting
+        # it as "none scheduled" would invite the user to re-create statuses
+        # that still exist.
+        unless section.is_a?(Array)
+          raise ApiError.new('Slack returned no scheduled_statuses section; this internal endpoint may have changed. ' \
+                             'Check the Slack status picker before re-scheduling.',
+                             code: :missing_scheduled_section)
+        end
+
+        section.map { |item| Models::ScheduledStatus.from_api(item) }
+      end
+
+      # @param date_scheduled [Integer] Unix timestamp the status turns on
+      # @param date_expire [Integer, nil] Unix timestamp it clears
+      # @param dnd [Boolean] also pause notifications while active
+      # @return [Models::ScheduledStatus]
+      def schedule(text:, emoji:, date_scheduled:, date_expire: nil, dnd: false)
+        params = { text: text, emoji: emoji, date_scheduled: date_scheduled.to_i.to_s }
+        params[:date_expire] = date_expire.to_i.to_s if date_expire
+        params[:is_dnd] = 'true' if dnd
+
+        response = @api.post_form(@workspace, 'users.customStatus.schedule', params)
+        Models::ScheduledStatus.from_api(confirmed_schedule(response))
+      end
+
+      # Slack answers a delete with ok: true whether or not anything changed —
+      # including for an id that never existed — so the response alone is not
+      # evidence. Re-reading the list at least catches an accepted delete that
+      # did not apply. It cannot distinguish "cancelled" from "was never
+      # there": both leave the id absent. `unschedule` covers that case ahead
+      # of time by finding the workspace that owns the id.
+      #
+      # @return [Array(Symbol, String, nil)] `[:cancelled, nil]`, or
+      #   `[:unconfirmed, reason]` when the delete was accepted but the
+      #   following read failed. Those are different things: only the second
+      #   read failed, and reporting it as a failed *cancel* would send the
+      #   user back to re-cancel something already gone.
+      # @raise [ApiError] only when the status is demonstrably still there
+      def delete_scheduled(custom_status_id)
+        @api.post_form(@workspace, 'users.customStatus.deleteScheduled',
+                       { custom_status_id: custom_status_id })
+        confirm_deleted(custom_status_id)
+      end
+
+      private
+
+      # The delete has already been accepted by the time this runs, so this
+      # only decides how much can honestly be said about it. A read that
+      # fails — including a rate-limited one, since the confirming read hits
+      # the same `list` method a multi-workspace sweep just used — is a
+      # failure to look, not a failure to delete.
+      def confirm_deleted(custom_status_id)
+        return [:cancelled, nil] unless scheduled.any? { |status| status.id == custom_status_id }
+
+        raise ApiError.new("Slack reported success but #{custom_status_id} is still scheduled.",
+                           code: :delete_not_applied)
+      rescue ApiError => e
+        raise if e.code == :delete_not_applied
+
+        [:unconfirmed, e.message]
+      end
+
+      # A create that reports ok without echoing back the status it made has
+      # not demonstrably created anything.
+      #
+      # The id check duplicates ScheduledStatus.validate!, deliberately:
+      # letting an id-less payload through to that guard trades this message
+      # for "Slack returned a scheduled status with no id: {}", which tells
+      # the user nothing they can act on. Here the answer is the same either
+      # way — go look at the picker.
+      def confirmed_schedule(response)
+        payload = response['scheduled_status']
+        return payload if payload.is_a?(Hash) && !payload['id'].to_s.empty?
+
+        raise ApiError.new('Slack accepted the request but returned no scheduled status, so nothing was confirmed. ' \
+                           'Check the Slack status picker to see whether it was created.',
+                           code: :malformed_schedule_response)
+      end
+    end
+  end
+end

data/lib/slk/cli.rb

@@ -72,7 +72,7 @@ module Slk
       else
         show_unknown_command(command_name)
       end
-    rescue ConfigError, EncryptionError, ApiError => e
+    rescue ConfigError, EncryptionError, ApiError, UsageError => e
       handle_known_error(e)
     end
 
@@ -86,7 +86,10 @@ module Slk
     def handle_known_error(error)
       label = error_label(error)
       @output.error(label ? "#{label}: #{error.message}" : error.message)
-      log_error(error)
+      # error.log exists to investigate faults after the fact. A mistyped flag
+      # or an unparseable time is not one, and filing a backtrace for it both
+      # buries the real entries and contradicts what UsageError promises.
+      log_error(error) unless error.is_a?(UsageError)
       1
     end
 

data/lib/slk/commands/base.rb

@@ -65,7 +65,7 @@ module Slk
       # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
       def parse_single_option(arg, args, remaining)
         case arg
-        when '-w', '--workspace' then @options[:workspace] = args.shift
+        when '-w', '--workspace' then @options[:workspace] = option_value(arg, args)
         when '--width' then parse_width_option(args)
         when '--no-wrap' then @options[:width] = nil
         when '--all' then @options[:all] = true
@@ -93,6 +93,18 @@ module Slk
 
       protected
 
+      # A bare `args.shift` returns nil for a trailing flag, which then reads
+      # as an option nobody set: `slk status -w` selected *every* workspace
+      # and exited 0, the opposite of what it says. A following flag is the
+      # same mistake one token later — `--end --with-dnd` would take
+      # "--with-dnd" as the time.
+      def option_value(flag, args)
+        value = args.first
+        raise UsageError, "#{flag} requires a value." if value.nil? || value.start_with?('-')
+
+        args.shift
+      end
+
       # Override in subclass to handle command-specific options
       # Return true if option was handled, false to raise unknown option error
       def handle_option(arg, _args, _remaining) # rubocop:disable Naming/PredicateMethod

data/lib/slk/commands/help.rb

@@ -74,6 +74,7 @@ module Slk
             slk status                       Show current status
             slk status "Working" :laptop:    Set status
             slk status clear                 Clear status
+            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 preset meeting               Apply preset

data/lib/slk/commands/status.rb

@@ -10,6 +10,10 @@ module Slk
     class Status < Base
       include Support::InlineImages
 
+      SCHEDULE_USAGE = 'Usage: slk status schedule "<text>" [:emoji:] <start-end> | --start WHEN [--end WHEN]'
+      MISSING_RANGE = 'Missing time range. Example: slk status schedule "Vet Appt" :paw_prints: 1:30p-3:30p ' \
+                      '(or --start/--end for a multi-day window).'
+
       def execute
         result = validate_options
         return result if result
@@ -22,6 +26,9 @@ module Slk
 
       def dispatch_action
         case positional_args
+        in ['schedule', *rest] then schedule_status(rest)
+        in ['scheduled', *] then list_scheduled
+        in ['unschedule', *rest] then unschedule_status(rest)
         in ['clear', *] then clear_status
         in [text, *rest] then set_status(text, rest)
         in [] then get_status
@@ -31,17 +38,17 @@ module Slk
       protected
 
       def default_options
-        super.merge(presence: nil, dnd: nil)
+        super.merge(presence: nil, dnd: nil, with_dnd: false, start_at: nil, end_at: nil)
       end
 
       def handle_option(arg, args, remaining)
         case arg
-        when '-p', '--presence'
-          @options[:presence] = args.shift
-        when '-d', '--dnd'
-          @options[:dnd] = args.shift
-        else
-          super
+        when '-p', '--presence' then @options[:presence] = option_value(arg, args)
+        when '-d', '--dnd' then @options[:dnd] = option_value(arg, args)
+        when '--with-dnd' then @options[:with_dnd] = true
+        when '--start' then @options[:start_at] = option_value(arg, args)
+        when '--end' then @options[:end_at] = option_value(arg, args)
+        else super
         end
       end
 
@@ -49,7 +56,10 @@ module Slk
         help = Support::HelpFormatter.new('slk status [text] [emoji] [duration] [options]')
         help.description('Get or set your Slack status.')
         help.note('GET shows all workspaces by default. SET applies to primary only.')
+        help.note('scheduled shows all workspaces; schedule applies to primary; unschedule finds the ID owner.')
+        help.note('Slack allows at most 5 scheduled statuses at a time.')
         add_examples_section(help)
+        add_scheduling_section(help)
         add_options_section(help)
         help.render
       end
@@ -64,17 +74,42 @@ module Slk
         end
       end
 
+      def add_scheduling_section(help)
+        help.section('SCHEDULING') do |s|
+          s.example('slk status schedule "Vet Appt" :paw_prints: 1:30p-3:30p', 'Schedule for later')
+          s.example('slk status schedule "OOO" :palm_tree: 2026-08-04 9:00-17:00')
+          s.example('slk status schedule "OOO" :palm_tree: --start "2026-08-12 8a" --end "2026-08-14 5p"',
+                    'Span multiple days')
+          s.example('slk status schedule "Heads down" :no_bell: --start 2p', 'No end; stays until cleared')
+          s.example('slk status scheduled', 'List pending scheduled statuses')
+          s.example('slk status unschedule CS0BMQDDGWTU', 'Cancel a scheduled status')
+        end
+      end
+
       def add_options_section(help)
         help.section('OPTIONS') do |s|
-          s.option('-p, --presence VALUE', 'Also set presence (away/auto/active)')
-          s.option('-d, --dnd DURATION', "Also set DND (or 'off')")
-          s.option('-w, --workspace', 'Limit to specific workspace')
-          s.option('--all', 'Set across all workspaces')
-          s.option('-v, --verbose', 'Show debug information')
-          s.option('-q, --quiet', 'Suppress output')
+          add_general_options(s)
+          add_scheduling_options(s)
         end
       end
 
+      def add_general_options(section)
+        section.option('-p, --presence VALUE', 'Also set presence (away/auto/active)')
+        section.option('-d, --dnd DURATION', "Also set DND (or 'off')")
+        section.option('-w, --workspace', 'Limit to specific workspace')
+        section.option('--all', 'Set across all workspaces')
+        section.option('-v, --verbose', 'Show debug information')
+        section.option('-q, --quiet', 'Suppress output')
+      end
+
+      # These are ignored outside `schedule`, so say so rather than leaving
+      # --with-dnd looking like a sibling of -d/--dnd.
+      def add_scheduling_options(section)
+        section.option('--with-dnd', 'Scheduling only: pause notifications while the status is active')
+        section.option('--start WHEN', 'Scheduling only: window start, "[YYYY-MM-DD ]TIME"')
+        section.option('--end WHEN', 'Scheduling only: window end; omit for no expiry')
+      end
+
       private
 
       def get_status # rubocop:disable Naming/AccessorMethodName
@@ -210,6 +245,182 @@ module Slk
         0
       end
 
+      def schedule_status(args)
+        text, *rest = args
+        return error(SCHEDULE_USAGE) if text.to_s.strip.empty?
+
+        window = parse_schedule_window(rest)
+        return 1 unless window
+
+        result = create_scheduled_status(text, extract_emoji(rest), *window)
+        show_all_workspaces_hint
+        result
+      end
+
+      # Narrow on both axes: only the parsing is covered, so a Slack failure is
+      # not reported as a mistyped range, and only TimeFormatError is caught, so
+      # an arity or range error from this code does not surface as user error.
+      def parse_schedule_window(rest)
+        return flag_window(rest) if @options[:start_at] || @options[:end_at]
+
+        range = extract_time_range(rest)
+        return reject_window(MISSING_RANGE) unless range
+
+        Support::TimeRangeParser.parse(range)
+      rescue TimeFormatError => e
+        error(e.message)
+        nil
+      end
+
+      # --start/--end is the general form. Both times carry their own date, so
+      # it reaches multi-day windows the positional range cannot express, and
+      # omitting --end schedules a status that never auto-clears.
+      def flag_window(rest)
+        return reject_window('--end requires --start.') unless @options[:start_at]
+        return reject_window('Use either a time range or --start/--end, not both.') if extract_time_range(rest)
+
+        starts_at = Support::TimeParser.parse(@options[:start_at])
+        return [starts_at, nil] unless @options[:end_at]
+
+        [starts_at, validated_end(starts_at)]
+      end
+
+      def validated_end(starts_at)
+        ends_at = Support::TimeParser.parse(@options[:end_at])
+        # An explicit end is unambiguous, so there is nothing to roll forward.
+        return ends_at if ends_at > starts_at
+
+        raise TimeFormatError, "--end #{@options[:end_at]} is not after --start #{@options[:start_at]}."
+      end
+
+      # Returns nil so the caller reads it as "no window, already reported".
+      def reject_window(message)
+        error(message)
+        nil
+      end
+
+      # The range may arrive as one token ("1:30p-3:30p") or several
+      # ("2026-08-04 13:30-15:30"), so the non-emoji arguments are matched as a
+      # whole. Emoji are dropped first because the pattern is \A-anchored and a
+      # leading ":palm_tree:" would stop the date form from matching at all.
+      #
+      # Everything left has to be part of the range. Only YYYY-MM-DD dates
+      # parse, so picking the range out and discarding "8/4" or "tomorrow"
+      # would silently schedule the status for today.
+      def extract_time_range(rest)
+        candidates = rest.reject { |arg| arg.start_with?(':') && arg.end_with?(':') }
+        return nil if candidates.empty?
+
+        joined = candidates.join(' ')
+        return joined if Support::TimeRangeParser.match?(joined)
+
+        raise TimeFormatError, "Unrecognized argument: #{joined}. Use #{Support::TimeRangeParser::EXAMPLE}"
+      end
+
+      # Each workspace is an independent call, so one failure must not strand
+      # the workspaces after it: the user would re-run to fix the tail and
+      # double-schedule everything that already succeeded.
+      def each_workspace_reporting(workspaces)
+        failed = false
+
+        workspaces.each do |workspace|
+          yield workspace
+        rescue ApiError => e
+          failed = true
+          error("#{workspace.name}: #{e.message}")
+        end
+
+        failed ? 1 : 0
+      end
+
+      def create_scheduled_status(text, emoji, starts_at, ends_at)
+        each_workspace_reporting(target_workspaces) do |workspace|
+          scheduled = runner.custom_status_api(workspace.name).schedule(
+            text: text, emoji: emoji,
+            date_scheduled: starts_at, date_expire: ends_at,
+            dnd: @options[:with_dnd]
+          )
+          success("Scheduled on #{workspace.name}: #{scheduled}")
+          debug("  ID: #{scheduled.id}")
+        end
+      end
+
+      def list_scheduled
+        workspaces = target_workspaces_for_get
+
+        each_workspace_reporting(workspaces) do |workspace|
+          puts output.bold(workspace.name) if workspaces.size > 1
+          print_scheduled(runner.custom_status_api(workspace.name).scheduled)
+        end
+      end
+
+      def print_scheduled(scheduled)
+        return puts '  (none scheduled)' if scheduled.empty?
+
+        scheduled.each { |status| puts "  #{status.id}  #{status}" }
+      end
+
+      def unschedule_status(args)
+        id = args.first
+        return error('Usage: slk status unschedule <id>') if id.to_s.strip.empty?
+
+        @unchecked = []
+        targets = unschedule_targets(id)
+        return report_id_not_found(id) if targets.empty?
+
+        each_workspace_reporting(targets) do |workspace|
+          outcome, reason = runner.custom_status_api(workspace.name).delete_scheduled(id)
+          report_cancelled(workspace, outcome, reason)
+        end
+      end
+
+      # The delete succeeded either way, so both are successes — but only one
+      # of them has been checked, and saying so is the difference between the
+      # user moving on and the user re-cancelling something already gone.
+      def report_cancelled(workspace, outcome, reason)
+        return success("Cancelled scheduled status on #{workspace.name}") if outcome == :cancelled
+
+        warn("Cancelled scheduled status on #{workspace.name}, but could not confirm it: #{reason}")
+      end
+
+      # `slk status scheduled` lists every workspace, so the obvious next step
+      # is to paste an ID straight back in. Defaulting to the primary workspace
+      # made that fail with a bare Slack error whenever the ID came from
+      # another one, so look up the owner instead. An explicit -w/--all still
+      # wins, and a lone workspace needs no lookup.
+      def unschedule_targets(id)
+        return target_workspaces if @options[:all] || @options[:workspace]
+
+        workspaces = runner.all_workspaces
+        return workspaces if workspaces.size <= 1
+
+        [workspaces.find { |workspace| owns_scheduled?(workspace, id) }].compact
+      end
+
+      # "Not found" is only true of the workspaces we actually reached. Saying
+      # it flatly after warning that one could not be checked contradicts the
+      # warning, and pointing at `slk status scheduled` would just fail the
+      # same way — it calls the same endpoint.
+      def report_id_not_found(id)
+        return error("No scheduled status #{id} found. Run 'slk status scheduled' to list IDs.") if @unchecked.empty?
+
+        error("#{id} was not found, but #{@unchecked.join(', ')} could not be checked. " \
+              'Retry, or name the workspace with -w to cancel it directly.')
+      end
+
+      def owns_scheduled?(workspace, id)
+        runner.custom_status_api(workspace.name).scheduled.any? { |status| status.id == id }
+      rescue RateLimitError
+        # Every remaining check spends another call against the same limit, so
+        # continuing turns one rate limit into several and still cannot answer.
+        raise
+      rescue ApiError => e
+        # Skipping it silently would report "not found" for an ID that exists.
+        warn("Could not check #{workspace.name}: #{e.message}")
+        @unchecked << workspace.name
+        false
+      end
+
       def show_all_workspaces_hint
         # Show hint if user has multiple workspaces and didn't use --all or -w
         return if @options[:all] || @options[:workspace]

data/lib/slk/models/scheduled_status.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Slk
+  module Models
+    # A status queued to turn on later, from users.customStatus.list.
+    #
+    # Slack derives `duration` server-side from the window, so it is not
+    # modelled here — the window itself is the source of truth.
+    ScheduledStatus = Data.define(:id, :text, :emoji, :date_scheduled, :date_expire, :dnd, :active) do
+      def self.from_api(data)
+        validate!(data)
+
+        new(
+          id: data['id'].to_s,
+          text: data['text'].to_s,
+          emoji: data['emoji'].to_s,
+          date_scheduled: data['date_scheduled'].to_i,
+          date_expire: data['date_expire'].to_i,
+          dnd: truthy?(data['is_dnd']),
+          active: truthy?(data['is_active'])
+        )
+      end
+
+      # Every field is coerced, so without this guard any payload at all —
+      # a bare string, nil, a hash of unexpected keys — becomes a valid-looking
+      # record with an empty id that prints as a blank line and never matches
+      # the id the user asked about. An unusable record is a protocol change,
+      # not a status.
+      def self.validate!(data)
+        return if data.is_a?(Hash) && !data['id'].to_s.empty?
+
+        raise ApiError.new("Slack returned a scheduled status with no id: #{data.inspect[0, 120]}",
+                           code: :malformed_scheduled_status)
+      end
+      private_class_method :validate!
+
+      # These endpoints are string-typed on the way in — Api::CustomStatus sends
+      # is_dnd as 'true' — so a strict `== true` would quietly read a scheduled
+      # DND back as off. Accept the shapes Slack actually uses.
+      def self.truthy?(value) = [true, 'true', 1, '1'].include?(value)
+      private_class_method :truthy?
+
+      def starts_at = date_scheduled.positive? ? Time.at(date_scheduled) : nil
+      def ends_at = date_expire.positive? ? Time.at(date_expire) : nil
+
+      def to_s
+        span = window
+        [
+          emoji,
+          text,
+          span.empty? ? '' : "(#{span})",
+          ('[dnd]' if dnd),
+          # Slack marks the one that has already turned on. Worth showing: it
+          # is the difference between "will happen" and "is happening".
+          ('[active]' if active)
+        ].reject { |part| part.to_s.empty? }.join(' ')
+      end
+
+      # Human-readable window; the end date is only repeated when it differs
+      # from the start date, which makes multi-day windows obvious.
+      def window
+        dated = '%a %b %-d %-l:%M%P'
+        start_time = starts_at or return ''
+        formatted = start_time.strftime(dated)
+        finish = ends_at or return formatted
+
+        "#{formatted} -> #{finish.strftime(same_day?(start_time, finish) ? '%-l:%M%P' : dated)}"
+      end
+
+      private
+
+      def same_day?(start_time, finish)
+        start_time.to_date == finish.to_date
+      end
+    end
+  end
+end

data/lib/slk/runner.rb

@@ -88,6 +88,10 @@ module Slk
       Api::Saved.new(@api_client, workspace(workspace_name))
     end
 
+    def custom_status_api(workspace_name = nil)
+      Api::CustomStatus.new(@api_client, workspace(workspace_name))
+    end
+
     def team_api(workspace_name = nil)
       Api::Team.new(@api_client, workspace(workspace_name))
     end

data/lib/slk/services/encryption.rb

@@ -104,8 +104,15 @@ module Slk
               'Please provide the correct public key for this private key.'
       end
 
+      # `-P ''` supplies the passphrase up front so ssh-keygen cannot ask for
+      # one. Without it, an encrypted key makes ssh-keygen prompt — and it
+      # prompts on the console directly, not on the stdin capture3 hands it, so
+      # closing stdin does not help. On Windows that read blocks forever; this
+      # hung the CI job until its timeout with no output. An empty passphrase
+      # fails an encrypted key with the same message it already reported, which
+      # is the right answer regardless: slk cannot use such a key anyway.
       def derive_public_key(private_key_path)
-        output, error, status = Open3.capture3('ssh-keygen', '-y', '-f', private_key_path)
+        output, error, status = Open3.capture3('ssh-keygen', '-y', '-P', '', '-f', private_key_path)
         return output.strip if status.success?
 
         # Check if ssh-keygen is missing vs other failures

data/lib/slk/support/time_parser.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'date'
+
+module Slk
+  module Support
+    # Resolves a single clock time ("1:30p", "2026-08-12 8a") to a Unix
+    # timestamp. A bare time at or before now rolls to tomorrow; an explicit
+    # YYYY-MM-DD date is honoured as given.
+    #
+    # TimeRangeParser builds the two-sided form on the clock arithmetic here.
+    class TimeParser
+      TIME = /(\d{1,2})(?::(\d{2}))?\s*([ap]m?)?/i
+      PATTERN = /\A(?:(\d{4}-\d{2}-\d{2})\s+)?#{TIME}\z/i
+
+      EXAMPLE = '1:30p or 2026-08-12 8:00'
+
+      MINUTES_PER_DAY = 24 * 60
+
+      # A bare hour of 0 or 13-23 can only be 24-hour notation, so no am/pm was
+      # omitted. Anything in 1..12 is genuinely ambiguous without one.
+      CLOCK_HOURS = (1..12)
+
+      # @param now [Time] reference point for rolling bare times forward
+      # @return [Integer] Unix timestamp
+      def self.parse(input, now: Time.now) = new(now: now).parse(input)
+
+      def initialize(now: Time.now)
+        @now = now
+      end
+
+      def parse(input)
+        match = PATTERN.match(input.to_s.strip)
+        raise TimeFormatError, "Invalid time: #{input}. Use #{EXAMPLE}" unless match
+
+        parts = match.captures[1..3]
+        date = match[1] ? parse_date(match[1]) : roll_forward(parts)
+        at(date, *parts).to_i
+      end
+
+      # The rest of this class is clock arithmetic shared with TimeRangeParser,
+      # which needs to place the same parts on dates it works out itself.
+
+      # @param example [String] format hint, so a caller with its own syntax
+      #   (TimeRangeParser) does not advertise this class's example
+      def parse_date(text, example: EXAMPLE)
+        Date.parse(text)
+      rescue Date::Error
+        raise TimeFormatError, "Invalid date: #{text}. Use #{example}"
+      end
+
+      def at(date, *parts)
+        hours, minutes = to_24_hour(*parts)
+        time = build(date, hours, minutes)
+        # Ruby silently shifts a local time that DST skips (2:30a on a
+        # spring-forward date becomes 3:30a), which would move the window
+        # rather than fail. Reject it instead.
+        return time if time.hour == hours && time.min == minutes
+
+        raise TimeFormatError,
+              format('%<clock>s does not exist on %<date>s (clocks skip forward for DST).',
+                     clock: format('%<h>02d:%<m>02d', h: hours, m: minutes), date: date)
+      end
+
+      # Same placement without the existence check, for callers asking a
+      # question a nonexistent time still answers. `at` would raise, which for
+      # the roll-forward probe would reject "2:30a" outright on a spring-forward
+      # date instead of rolling it to the next day, where it does exist.
+      def place(date, *parts) = build(date, *to_24_hour(*parts))
+
+      # Minutes since midnight, for comparing two times before either has a date.
+      def minutes(parts)
+        hours, mins = to_24_hour(*parts)
+        (hours * 60) + mins
+      end
+
+      # True when these parts could have meant either am or pm — no meridiem
+      # given, and an hour small enough that both readings are plausible.
+      def ambiguous?(parts) = parts[2].nil? && CLOCK_HOURS.cover?(parts[0].to_i)
+
+      # The opposite: a bare hour too large to be a 12-hour clock reading, so
+      # the writer was plainly using 24-hour notation. TimeRangeParser treats
+      # one of these as settling how to read the *other* side of a range.
+      def twenty_four_hour?(parts) = parts[2].nil? && !CLOCK_HOURS.cover?(parts[0].to_i)
+
+      private
+
+      def build(date, hours, minutes) = Time.new(date.year, date.month, date.day, hours, minutes, 0)
+
+      def roll_forward(parts)
+        today = @now.to_date
+        place(today, *parts) <= @now ? today + 1 : today
+      end
+
+      def to_24_hour(hour, minute, meridiem)
+        hours = hour.to_i
+        minutes = minute.to_i
+        raise TimeFormatError, "Invalid minute: #{minute}" if minutes > 59
+        return [validate_24_hour(hours), minutes] unless meridiem
+
+        [apply_meridiem(hours, meridiem), minutes]
+      end
+
+      def validate_24_hour(hours)
+        raise TimeFormatError, "Invalid hour: #{hours}" if hours > 23
+
+        hours
+      end
+
+      def apply_meridiem(hours, meridiem)
+        raise TimeFormatError, "Invalid hour for 12-hour time: #{hours}" if hours.zero? || hours > 12
+
+        # 12am is hour 0 and 12pm is hour 12, so fold 12 down before shifting.
+        base = hours % 12
+        meridiem[0].casecmp?('p') ? base + 12 : base
+      end
+    end
+  end
+end

data/lib/slk/support/time_range_parser.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'date'
+
+module Slk
+  module Support
+    # Parses a scheduling window ("1:30p-3:30p", "2026-08-04 13:30-15:30")
+    # into a [start, end] pair of Unix timestamps.
+    #
+    # Unlike DateParser, which resolves an input to a point in the past, this
+    # always resolves forward: a bare time at or before now rolls to tomorrow,
+    # and an end before the start rolls to the next day so overnight windows
+    # ("11p-1a") work.
+    #
+    # The start date is written once and the end can only reach the following
+    # day, so this cannot express a multi-day window — `slk status schedule
+    # --start/--end` is the general form for that.
+    class TimeRangeParser
+      RANGE_PATTERN = /\A(?:(\d{4}-\d{2}-\d{2})\s+)?#{TimeParser::TIME}\s*-\s*#{TimeParser::TIME}\z/i
+
+      EXAMPLE = '1:30p-3:30p or 2026-08-04 13:30-15:30'
+
+      # Longest overnight window accepted when a reading had to be guessed.
+      # Twelve hours is not a policy about window length — an explicit
+      # "8p-9a" is longer and fine — it is the point past which a guessed
+      # crossing can no longer be what the user meant.
+      MAX_GUESSED_OVERNIGHT_MINUTES = 12 * 60
+
+      # @param input [String] the range to parse
+      # @param now [Time] reference point for rolling bare times forward
+      # @return [Array(Integer, Integer)] start and end Unix timestamps
+      def self.parse(input, now: Time.now) = new(now: now).parse(input)
+
+      # True when input looks like a time range, used to pick it out of argv.
+      def self.match?(input) = RANGE_PATTERN.match?(input.to_s.strip)
+
+      def initialize(now: Time.now)
+        @now = now
+        @clock = TimeParser.new(now: now)
+      end
+
+      def parse(input)
+        match = RANGE_PATTERN.match(input.to_s.strip)
+        raise TimeFormatError, "Invalid time range: #{input}. Use #{EXAMPLE}" unless match
+
+        start_parts, end_parts = infer_meridiems(match)
+        validate_range(input, start_parts, end_parts)
+
+        date = start_date(match, start_parts)
+        start_at = @clock.at(date, *start_parts)
+
+        [start_at.to_i, end_time(date, start_at, end_parts).to_i]
+      end
+
+      private
+
+      # `match.captures` layout: 0 is the optional date, 1..3 the start time,
+      # 4..6 the end. Note the date is `match[1]` in the 1-indexed MatchData form.
+      #
+      # "1-3p" means 1pm, not 1am: when only one side names a meridiem the
+      # other borrows it. The borrow is skipped when it would invert the range
+      # ("9-5p" is 9am to 5pm, not 9pm to 5pm).
+      def infer_meridiems(match)
+        start_parts = match.captures[1..3]
+        end_parts = match.captures[4..6]
+
+        if borrowable?(start_parts, end_parts)
+          borrowed = with_meridiem(start_parts, end_parts[2])
+          return [borrowed, end_parts] if @clock.minutes(borrowed) < @clock.minutes(end_parts)
+        elsif borrowable?(end_parts, start_parts)
+          borrowed = with_meridiem(end_parts, start_parts[2])
+          return [start_parts, borrowed] if @clock.minutes(start_parts) < @clock.minutes(borrowed)
+        end
+
+        [start_parts, end_parts]
+      end
+
+      def borrowable?(parts, source) = !source[2].nil? && @clock.ambiguous?(parts)
+
+      def with_meridiem(parts, meridiem) = [parts[0], parts[1], meridiem]
+
+      # An explicit date is honoured as given; a bare time at or before now
+      # refers to tomorrow.
+      def start_date(match, start_parts)
+        return @clock.parse_date(match[1], example: EXAMPLE) if match[1]
+
+        today = @now.to_date
+        # `place`, not `at`: this only asks "is that time already past today?",
+        # and on a spring-forward date `at` would reject a skipped time outright
+        # instead of letting it roll to tomorrow, where it exists.
+        @clock.place(today, *start_parts) <= @now ? today + 1 : today
+      end
+
+      def end_time(date, start_at, end_parts)
+        end_at = @clock.at(date, *end_parts)
+        # An end before the start means the window crosses midnight.
+        end_at < start_at ? @clock.at(date + 1, *end_parts) : end_at
+      end
+
+      def validate_range(input, start_parts, end_parts)
+        if @clock.minutes(start_parts) == @clock.minutes(end_parts)
+          raise TimeFormatError, "Time range #{input} starts and ends at the same time."
+        end
+
+        validate_overnight(input, start_parts, end_parts)
+      end
+
+      # "9-5" almost always means 9am-5pm, but reads literally as 09:00 to
+      # 05:00 the next morning — a 20-hour window nobody asked for. So is
+      # "9a-5", where the am/pm is there but on the wrong side to help.
+      #
+      # Only guessed readings are checked, and only past 12 hours, which is
+      # what separates the mistake from the intent. An overnight shift written
+      # with a pm start ("9p-5", "10p-2") can only come out 12 hours or less;
+      # a dropped meridiem ("9-5", "9a-5", "10-5a") can only come out longer.
+      def validate_overnight(input, start_parts, end_parts)
+        return unless guessed?(start_parts, end_parts)
+
+        span = overnight_minutes(start_parts, end_parts)
+        return if span.nil? || span <= MAX_GUESSED_OVERNIGHT_MINUTES
+
+        raise TimeFormatError,
+              "Time range #{input} reads as crossing midnight and spans #{format_span(span)}. " \
+              'Add am/pm to both sides (9a-5p), use 24-hour times (9:00-17:00), ' \
+              'or --start/--end for a multi-day window.'
+      end
+
+      # True when a side's reading had to be guessed.
+      #
+      # A leftover ambiguous side is not enough on its own: in "20:00-6" the
+      # 24-hour start settles the whole range, so "6" is 6am and was not
+      # guessed. Without such an anchor, any side still bare after
+      # `infer_meridiems` was read as 24-hour for want of anything better —
+      # either because no meridiem was given at all ("9-5"), or because
+      # borrowing the one that was given would have inverted the range
+      # ("9a-5", where 5am precedes 9am).
+      def guessed?(start_parts, end_parts)
+        return false if @clock.twenty_four_hour?(start_parts) || @clock.twenty_four_hour?(end_parts)
+
+        @clock.ambiguous?(start_parts) || @clock.ambiguous?(end_parts)
+      end
+
+      # Wall-clock minutes from start to end across midnight, or nil when the
+      # window stays on one date.
+      #
+      # Deliberately not `end_at - start_at`: elapsed seconds stretch or shrink
+      # by an hour across a DST boundary, so the same text would report a
+      # different span depending on the date it happened to land on.
+      def overnight_minutes(start_parts, end_parts)
+        start_minutes = @clock.minutes(start_parts)
+        end_minutes = @clock.minutes(end_parts)
+        return nil if end_minutes > start_minutes
+
+        TimeParser::MINUTES_PER_DAY - start_minutes + end_minutes
+      end
+
+      # Whole hours read better, but rounding them would report a 12h01m window
+      # as "12 hours" against a 12-hour limit.
+      def format_span(minutes)
+        hours, mins = minutes.divmod(60)
+        mins.zero? ? "#{hours} hours" : format('%<h>dh%<m>02dm', h: hours, m: mins)
+      end
+    end
+  end
+end

data/lib/slk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Slk
-  VERSION = '0.6.0'
+  VERSION = '0.7.0'
 end

data/lib/slk.rb

@@ -12,6 +12,17 @@ require 'io/console'
 module Slk
   class Error < StandardError; end
 
+  # The invocation itself was wrong (a flag with no value, an unparseable
+  # time). The message is written for the user and is printed verbatim, with
+  # no "Error type:" label, because there is no internal fault to report.
+  class UsageError < Error; end
+
+  # A time or range the user typed that cannot be understood. Separate from
+  # UsageError so callers can rescue *only* malformed input: a blanket
+  # `rescue ArgumentError` around a parse call also swallows arity and range
+  # errors from the code itself and presents them as if the user mistyped.
+  class TimeFormatError < UsageError; end
+
   # Errors from any Slack-API-shaped failure: HTTP errors, network errors,
   # logical Slack errors (user_not_found, missing_scope, etc.), JSON parse
   # failures. The optional `code` symbol lets callers match specific cases
@@ -55,6 +66,7 @@ module Slk
     autoload :Duration, 'slk/models/duration'
     autoload :Workspace, 'slk/models/workspace'
     autoload :Status, 'slk/models/status'
+    autoload :ScheduledStatus, 'slk/models/scheduled_status'
     autoload :Message, 'slk/models/message'
     autoload :Reaction, 'slk/models/reaction'
     autoload :User, 'slk/models/user'
@@ -153,6 +165,7 @@ module Slk
     autoload :Activity, 'slk/api/activity'
     autoload :Search, 'slk/api/search'
     autoload :Saved, 'slk/api/saved'
+    autoload :CustomStatus, 'slk/api/custom_status'
     autoload :Team, 'slk/api/team'
   end
 
@@ -167,5 +180,7 @@ module Slk
     autoload :TextWrapper, 'slk/support/text_wrapper'
     autoload :InteractivePrompt, 'slk/support/interactive_prompt'
     autoload :DateParser, 'slk/support/date_parser'
+    autoload :TimeParser, 'slk/support/time_parser'
+    autoload :TimeRangeParser, 'slk/support/time_range_parser'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: slk
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Eric Boehs
@@ -30,6 +30,7 @@ files:
 - lib/slk/api/bots.rb
 - lib/slk/api/client.rb
 - lib/slk/api/conversations.rb
+- lib/slk/api/custom_status.rb
 - lib/slk/api/dnd.rb
 - lib/slk/api/emoji.rb
 - lib/slk/api/saved.rb
@@ -85,6 +86,7 @@ files:
 - lib/slk/models/profile_field.rb
 - lib/slk/models/reaction.rb
 - lib/slk/models/saved_item.rb
+- lib/slk/models/scheduled_status.rb
 - lib/slk/models/search_result.rb
 - lib/slk/models/status.rb
 - lib/slk/models/user.rb
@@ -123,6 +125,8 @@ files:
 - lib/slk/support/platform.rb
 - lib/slk/support/slack_url_parser.rb
 - lib/slk/support/text_wrapper.rb
+- lib/slk/support/time_parser.rb
+- lib/slk/support/time_range_parser.rb
 - lib/slk/support/user_resolver.rb
 - lib/slk/support/xdg_paths.rb
 - lib/slk/version.rb
@@ -148,7 +152,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.13
 specification_version: 4
 summary: A command-line interface for Slack
 test_files: []