slk - Slack CLI

A command-line interface for Slack. Manage your status, presence, DND, read messages, and more from the terminal.

Pure Ruby. No dependencies.

Installation

gem install slk

Requires Ruby 3.2+.

Windows

# Install Ruby (if needed) via RubyInstaller or Chocolatey
winget install RubyInstallerTeam.Ruby.3.3
# or: choco install ruby

# Install slk
gem install slk

# (Optional) Install age for encrypted token storage
choco install age.portable

Configuration is stored in %APPDATA%\slk\ on Windows.

Setup

Run the setup wizard:

slk config setup

You'll need a Slack token. Get one from:

  • User token (xoxp-): https://api.slack.com/apps → OAuth & Permissions
  • Bot token (xoxb-): Create a Slack App with bot scopes
  • Session token (xoxc-): Extract from browser (requires cookie too)

Usage

Status

slk status                              # Show current status
slk status "Working from home" :house:  # Set status with emoji
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):

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:

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

slk presence              # Show current presence
slk presence away         # Set to away
slk presence active       # Set to active

Do Not Disturb

slk dnd                   # Show DND status
slk dnd 1h                # Enable DND for 1 hour
slk dnd on 30m            # Enable DND for 30 minutes
slk dnd off               # Disable DND

Messages

slk messages general            # Read channel messages
slk messages @username          # Read DM with user
slk messages general -n 50      # Show 50 messages
slk messages general --json     # Output as JSON

Activity

slk activity              # Show recent activity feed
slk activity -n 50        # Show 50 items
slk activity -m           # Show message previews
slk activity --reactions  # Filter: reactions only
slk activity --mentions   # Filter: mentions only
slk activity --threads    # Filter: thread replies only

Displays your recent activity feed including:

  • Reactions to your messages
  • Mentions (@user, @channel, @here, etc.)
  • Thread replies
  • Bot messages (reminders, notifications)

Use --show-messages (or -m) to preview the actual message content for each activity.

Unread

slk unread                # Show unread counts
slk unread clear          # Mark all as read
slk unread clear general  # Mark channel as read

Catchup (Interactive Triage)

slk catchup               # Interactively review unread channels
slk catchup --batch       # Non-interactive, mark all as read

Presets

slk preset list           # List all presets
slk preset meeting        # Apply preset
slk preset add            # Add new preset (interactive)
slk meeting               # Shortcut: use preset name as command

Built-in presets: meeting, lunch, focus, brb, clear

Workspaces

slk workspaces list       # List configured workspaces
slk workspaces add        # Add a workspace
slk workspaces primary    # Show/set primary workspace

Cache Management

slk cache status          # Show cache status
slk cache populate        # Pre-populate user cache
slk cache clear           # Clear all caches

Global Options

-w, --workspace NAME   # Use specific workspace
--all                  # Apply to all workspaces
-v, --verbose          # Show debug output
-q, --quiet            # Suppress output
--json                 # Output as JSON (where supported)

Multi-Workspace

Configure multiple workspaces and switch between them:

slk workspaces add                    # Add another workspace
slk status -w work                    # Check status on 'work' workspace
slk status "OOO" --all                # Set status on all workspaces

Token Encryption

Optionally encrypt your tokens with age using an SSH key:

slk config set ssh_key ~/.ssh/id_ed25519

Tokens will be stored encrypted in ~/.config/slk/tokens.age.

Configuration

Files are stored in XDG-compliant locations (or %APPDATA%/%LOCALAPPDATA% on Windows):

  • Config: ~/.config/slk/ (Windows: %APPDATA%\slk\)
    • config.json - Settings
    • tokens.json or tokens.age - Workspace tokens
    • presets.json - Status presets
  • Cache: ~/.cache/slk/ (Windows: %LOCALAPPDATA%\slk\)
    • users-{workspace}.json - User cache
    • channels-{workspace}.json - Channel cache

Development

# Clone the repo
git clone https://github.com/ericboehs/slk.git
cd slk

# Run from source
ruby -Ilib bin/slk --version

# Run tests
rake test

Releasing

  1. Update version in lib/slk/version.rb
  2. Update CHANGELOG.md (move Unreleased to new version, add date)
  3. Commit: git commit -am "Release vX.Y.Z"
  4. Release to RubyGems: rake release
  5. Create GitHub Release: gh release create vX.Y.Z --generate-notes

License

MIT License. See LICENSE for details.