Metadata-Version: 2.4
Name: slack-cli-agent
Version: 1.4.0
Summary: Slack CLI for coding agents — search, read, and draft messages via the Slack Web API using browser-extracted tokens
Author: Alan Shum
License: MIT
Project-URL: Homepage, https://github.com/alankyshum/slack-cli
Project-URL: Repository, https://github.com/alankyshum/slack-cli
Project-URL: Issues, https://github.com/alankyshum/slack-cli/issues
Keywords: slack,cli,agent,search,messages,automation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Other
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

[![npm version](https://img.shields.io/npm/v/@alankyshum/slack-cli)](https://www.npmjs.com/package/@alankyshum/slack-cli)
[![PyPI version](https://img.shields.io/pypi/v/slack-cli-agent)](https://pypi.org/project/slack-cli-agent/)

# slack-cli

A Slack CLI designed for coding agents (Claude Code, Cursor, etc.) that provides structured JSON access to Slack workspaces via the Web API.

It works by extracting authentication tokens from your existing browser session — no Slack app or bot token required.

## Install

**npm:**
```bash
npm install -g @alankyshum/slack-cli
```

**pip:**
```bash
pip install slack-cli-agent
```

**Manual:**
```bash
git clone https://github.com/alankyshum/slack-cli.git
chmod +x slack-cli/bin/slack-cli
ln -s "$(pwd)/slack-cli/bin/slack-cli" ~/.local/bin/slack-cli
```

## Prerequisites

- `curl` and `jq` (for all commands)
- `python3` (for URL encoding)
- Node.js + [Playwright](https://playwright.dev/) (only for `auth` command)

```bash
npm install -g playwright
npx playwright install chromium
```

## Quick Start

```bash
# 1. Authenticate (opens browser to extract tokens)
slack-cli auth --domain mycompany.slack.com

# 2. Search messages
slack-cli search "from:@alice in:#engineering deployment"

# 3. Read channel history
slack-cli read engineering 10

# 4. Draft a message (saved locally, not sent)
slack-cli draft general "Hey team, the fix for JIRA-123 is ready"
```

## Commands

| Command | Description |
|---------|-------------|
| `auth --domain <dom>` | Extract tokens from browser session |
| `whoami` | Show authenticated user |
| `config` | Show current configuration |
| `search <query>` | Search messages (full Slack query syntax) |
| `read <channel> [count]` | Read channel messages |
| `unreads` | Show recent activity |
| `draft <channel> <msg> [--thread <ts>] [--file <path>]` | Save a server-side draft |
| `draft-delete <draft_id>` | Delete a server-side draft |
| `drafts` | List saved drafts |
| `send <draft_id>` | Send a draft (with confirmation prompt) |
| `post <channel> <msg> [--thread <ts>] [--file <path>]` | Send a message with mrkdwn formatting |
| `channels` | List your channels |
| `dms` | List recent DMs |
| `userinfo <user>` | Look up user by ID, email, or name |
| `status [emoji] [text]` | Get or set your Slack status (`clear` to remove) |
| `presence [user_id|username|email]` | Show a user's presence status (active/away). Defaults to self. |

## Search Modifiers

Slack's full search syntax is supported:

| Modifier | Example | Description |
|----------|---------|-------------|
| `from:` | `from:@alice` / `from:me` | Messages from a person |
| `in:` | `in:#channel` / `in:@user` | Messages in channel or DM |
| `before:` | `before:2025-06-01` | Before a date |
| `after:` | `after:2025-01-01` | After a date |
| `on:` | `on:2025-03-15` | On exact date |
| `during:` | `during:january` | During a month or year |
| `has:` | `has::eyes:` / `has:pin` | Has reaction or pin |
| `is:` | `is:saved` / `is:thread` | Saved or thread messages |
| `"..."` | `"exact phrase"` | Exact phrase match |
| `-` | `-word` | Exclude word |
| `*` | `deploy*` | Wildcard (min 3 chars) |

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `SLACK_CLI_HOME` | `~/.slack-cli` | Config directory |
| `SLACK_CLI_CHROME_PROFILE` | `~/.slack-cli/chrome-profile` | Chrome profile for auth |
| `SLACK_CLI_COUNT` | `20` | Results per page |
| `SLACK_CLI_SORT` | `timestamp` | Sort: `timestamp` or `score` |
| `SLACK_CLI_SORT_DIR` | `desc` | Direction: `asc` or `desc` |

## How It Works

1. **`auth`** opens a Chromium browser using your existing Chrome profile (via Playwright), navigates to your Slack workspace, and intercepts the `xoxc-` API token and `xoxd-` session cookie from live API requests.

2. All other commands use direct **Slack Web API** calls via `curl` — no browser needed, making them fast and suitable for automation.

3. **Drafts** are saved locally to `~/.slack-cli/drafts.json`. The `send` command requires interactive confirmation before posting.

4. All output is **structured JSON**, making it easy to parse with `jq` or consume from AI agents.

## Security

- Credentials are stored at `~/.slack-cli/credentials.json` with `600` permissions
- Tokens are `xoxc-` client tokens scoped to your user session
- The `send` command requires explicit `y` confirmation
- No data is sent to any third party

## License

MIT
