# Slackctl

> Slack automation CLI for AI agents. Use when: - Reading a Slack message or thread (given a URL or channel+ts) - Browsing recent channel messages / channel history - Getting all unread messages across channels - Listing saved-for-later messages (Slack "Later" list) - Searching Slack messages or files - Sending, editing, or deleting a message; adding/removing reactions - Uploading files/images to channels or threads (including stdin piping) - Downloading Slack files and attachments to local paths - Listing, inspecting, or deleting files - Listing channels/conversations; creating channels and inviting users - Fetching a Slack canvas as markdown - Looking up Slack users - Marking channels/DMs as read - Opening DM or group DM channels Triggers: "slack message", "slack thread", "slack URL", "read slack", "reply on slack", "search slack", "channel history", "recent messages", "mark as read", "unread messages", "unread", "what did I miss", "saved messages", "saved for later", "later list", "upload file", "send image"

- Skill: `cluas/slackctl` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add cluas/slackctl`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cluas/slackctl/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: cluas (https://skillmd.com/u/cluas)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cluas/slackctl

---


# Slack automation with `slackctl`

`slackctl` is a single-binary CLI on `$PATH`. Invoke directly (e.g. `slackctl user get @alice`).

## Installation

`slackctl` is a single static binary with no runtime dependencies, available for macOS, Linux, and Windows (amd64 + arm64).

If `slackctl` is not found on `$PATH`, install it for the current OS:

- **macOS / Linux** (recommended) — Homebrew:

```bash
brew tap cluas/tap
brew install slackctl
```

- **Windows** (recommended) — Scoop:

```powershell
scoop bucket add cluas https://github.com/cluas/scoop-bucket
scoop install slackctl
```

- **Any OS with Go installed**:

```bash
go install github.com/cluas/slackctl/cmd/slackctl@latest
```

- **Manual (any OS)**: download the archive for your OS/arch from the [releases page](https://github.com/cluas/slackctl/releases), extract it, and put `slackctl` (or `slackctl.exe` on Windows) on your `PATH`.

## CRITICAL: Bash command formatting rules

Claude Code's permission checker has security heuristics that force manual approval prompts. Avoid these patterns to keep commands auto-allowed.

1. **No `#` anywhere in the command string.** Use bare channel names (`general` not `#general`).
2. **No `''` (consecutive single quotes) or `""` (consecutive double quotes).** Triggers "potential obfuscation" check.
3. **Only `| jq` for filtering — no python3, no other commands.** `jq` with single-quote-only expressions (no `"` inside) is safe:
   - RIGHT: `slackctl search messages "query" | jq '.messages[] | .ts'`
4. **No `||` or `&&` chains.** Run multiple slackctl commands as separate Bash tool calls.
5. **No file redirects (`>`, `>>`).** Process JSON output directly, don't write to files.

## Quick start (auth)

Auth auto-detection works on **macOS, Linux, and Windows**. It reads credentials
straight from local apps (no browser automation), trying Slack Desktop first,
then Chrome, then Firefox. Cookie decryption is handled per-platform: macOS
Keychain, Linux Secret Service (`secret-tool`), and Windows DPAPI.

Per-source platform support:

| Source (`auth import-*`) | macOS | Linux | Windows |
|--------------------------|-------|-------|---------|
| `import-desktop` (Slack Desktop) | ✅ | ✅ | ✅ |
| `import-chrome` | ✅ | ✅ | ✅ |
| `import-brave` | ✅ | ✅ | ✅ |
| `import-firefox` | ✅ | ✅ | ✅ |

Notes: On Linux, Chrome/Brave/Slack cookie decryption reads the key from the
desktop keyring via `secret-tool` (install `libsecret-tools` / `libsecret`),
falling back to the default `peanuts` password when no keyring is configured.
Firefox `cookies.sqlite` is plaintext on every platform.

If credentials aren't available, run one of:

- Slack Desktop import (macOS/Linux/Windows):

```bash
slackctl auth import-desktop
slackctl auth test
```

- Firefox fallback (macOS/Linux/Windows):

```bash
slackctl auth import-firefox
slackctl auth test
```

- Chrome fallback (macOS/Linux/Windows):

```bash
slackctl auth import-chrome
slackctl auth test
```

- Or set env vars:

```bash
export SLACK_TOKEN="xoxc-..."
export SLACK_COOKIE_D="xoxd-..."
export SLACK_WORKSPACE_URL="https://myteam.slack.com"
slackctl auth test
```

- Or add manually:

```bash
slackctl auth add --workspace-url https://myteam.slack.com --xoxc xoxc-... --xoxd xoxd-...
slackctl auth test
```

Check configured workspaces:

```bash
slackctl auth whoami
```

## Canonical workflow (given a Slack message URL)

1. Fetch a single message:

```bash
slackctl message get "https://workspace.slack.com/archives/C123/p1700000000000000"
```

2. If you need the full thread:

```bash
slackctl message list "https://workspace.slack.com/archives/C123/p1700000000000000" --thread-ts 1700000000.000000
```

## Browse recent channel messages

```bash
slackctl message list "general" --limit 20
slackctl message list "C0123ABC" --limit 10
slackctl --attachments message list "general" --limit 20
```

`--attachments` is off by default. Pass it when the message body lives in
attachments rather than `text`.

## Get unread messages

List all channels with unread messages:

```bash
slackctl message unread --limit 20
```

Also fetch the actual unread message content:

```bash
slackctl message unread --fetch --max-per-channel 5
```

Note: For Enterprise Grid, use `--workspace` with the enterprise URL for unread counts:

```bash
slackctl message unread --workspace longbridge-group --fetch
```

## Get saved-for-later messages (Later)

List the user's saved messages (Slack's "Later" list):

```bash
slackctl message saved --limit 20
```

Also fetch the actual saved message content:

```bash
slackctl message saved --fetch
```

Filter by state (`saved` = in progress, `completed`, `archived`; default is all):

```bash
slackctl message saved --filter saved --fetch
```

For Enterprise Grid, the enterprise workspace is used automatically when needed.

## Send, edit, delete, or react

```bash
slackctl message send "general" "here is the report"
slackctl message send U01AAAA "hello via DM"
slackctl message send "general" "threaded reply" --thread-ts 1700000000.000000
slackctl message edit "general" 1700000000.000000 "updated text"
slackctl message delete "general" 1700000000.000000
slackctl message react add "general" 1700000000.000000 "eyes"
slackctl message react remove "general" 1700000000.000000 "eyes"
```

Send to a user ID opens a DM automatically.

## List channels + create/invite

```bash
slackctl channel list
slackctl channel list --limit 50
slackctl channel new "incident-war-room"
slackctl channel new "incident-leads" --private
slackctl channel invite "incident-war-room" "U01AAAA,U02BBBB"
```

## Files (upload, download, list, info, delete)

Upload a file to a channel or thread:

```bash
slackctl file upload ./report.pdf "general" --title "Weekly Report" --message "Here is this week's report"
slackctl file upload ./screenshot.png "general" --thread-ts 1700000000.000000
slackctl file upload ./photo.jpg U01AAAA --message "Check this out"
```

Upload from stdin (pipe):

```bash
cat output.log | slackctl file upload - "general" --filename "build.log" --title "Build Log"
```

Download a file:

```bash
slackctl file download F0123ABCDEF --output ./downloaded.png
slackctl file download F0123ABCDEF --url-only
```

List, inspect, delete files:

```bash
slackctl file list --channel "general" --limit 10
slackctl file list --types images --limit 20
slackctl file info F0123ABCDEF
slackctl file delete F0123ABCDEF
```

## Search (messages + files)

```bash
slackctl search messages "deploy failed" --limit 10
slackctl search files "report" --limit 5
```

## Mark as read

```bash
slackctl channel mark "general" 1700000000.000000
```

## Canvas

Fetch a Slack canvas and convert to Markdown:

```bash
slackctl canvas get "https://workspace.slack.com/docs/T123/F456"
slackctl canvas get F0123ABCDEF
```

## Users

```bash
slackctl user list --limit 100
slackctl user get "@alice"
slackctl user get U01AAAA
```

## Multi-workspace

If you have multiple workspaces, pass `--workspace` to disambiguate:

```bash
slackctl message list "general" --workspace "myteam" --limit 10
slackctl auth set-default https://myteam.slack.com
```

## All output is JSON

All commands output JSON to stdout. Use `| jq` for filtering:

```bash
slackctl user get U01AAAA | jq '.email'
slackctl message list "general" --limit 5 | jq '.[].text'
```

## References

- [references/commands.md](references/commands.md): full command map + all flags
- [references/targets.md](references/targets.md): URL vs channel targeting rules
- [references/output.md](references/output.md): JSON output shapes