CLI reference

Global options

Option	Description
--db PATH	SQLite cache database path (default: ~/.cache/slack-cached/threads.db)
--api-base-url URL	Slack API base URL (default: https://slack.com/api)
-v, --verbose	Enable debug logging

Subcommands

fetch

Cache or refresh a Slack thread, or fetch messages from a channel.

slack-cached fetch [URL] [--channel CHANNEL] [--ts TS] [--full-threads] [--last DURATION]

Argument	Description
URL	Slack thread permalink URL
--channel CHANNEL	Channel ID (use without --ts for channel message fetch)
--ts TS	Thread root timestamp
--full-threads	Also fetch all thread replies (channel fetch only)
--last DURATION	Lookback period for channel fetch (default: 1d)

show

Print a cached thread or channel to stdout.

slack-cached show [URL] [--channel CHANNEL] [--ts TS] [--json] [--no-fetch] [--last DURATION]

Argument	Description
URL	Slack thread permalink URL
--channel CHANNEL	Channel ID (shows all channel messages without --ts)
--ts TS	Thread root timestamp
--json	Output as JSON
--no-fetch	Do not auto-fetch if not cached
--last DURATION	Lookback period for channel display (default: 1d)

fetch-users

Cache all workspace users.

slack-cached fetch-users

fetch-channels

Cache all visible channels.

slack-cached fetch-channels

show-users

Print cached users.

slack-cached show-users [--json] [--no-fetch]

show-channels

Print cached channels.

slack-cached show-channels [--json] [--no-fetch]

poll

Poll channels concurrently in a loop for new messages.

slack-cached poll --channels CHANNELS [--interval DURATION] [--last DURATION] [--full-threads] [--concurrency N] [--json]

Argument	Description
--channels CHANNELS	Comma-separated list of channels (required). Each entry may be a channel id (C001), a bare name (general), or a #-prefixed name (#general). Names are resolved against the cached channels.
--interval DURATION	Time between poll cycles (default: 5m)
--last DURATION	Lookback period per cycle (default: 5m, use all for full history)
--full-threads	Also fetch all thread replies for every threaded message
--concurrency N	Maximum number of channels fetched concurrently (default: 3)
--json	Emit per-cycle JSON summaries to stdout

Uses httpx.AsyncClient for non-blocking concurrent HTTP requests. An asyncio.Semaphore caps concurrent in-flight requests to avoid overwhelming Slack's rate limit. The client also reads X-RateLimit-Remaining headers from every response and proactively waits for the rate limit window to reset when nearly exhausted.

Stops gracefully on Ctrl+C.

Duration format

The --last flag accepts duration strings:

Format	Example	Meaning
Nh	3h	N hours
Nd	7d	N days
Nm	90m	N minutes
Combined	2d5h30m	2 days, 5 hours, 30 minutes
all	all	No time limit