@alankyshum/slack-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alan Shum
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+# 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>` | Save draft locally (does **not** send) |
+| `drafts` | List saved drafts |
+| `send <draft_id>` | Send a draft (with confirmation prompt) |
+| `channels` | List your channels |
+| `dms` | List recent DMs |
+| `userinfo <user>` | Look up user by ID, email, or name |
+
+## 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

package/bin/slack-cli

@@ -0,0 +1,586 @@
+#!/usr/bin/env bash
+# slack-cli - Slack CLI for coding agents
+# Uses Slack Web API with xoxc token extracted from authenticated browser session.
+# Credentials stored at ~/.slack-cli/credentials.json
+#
+# Usage:
+#   slack-cli auth [--domain <workspace>.slack.com]  - Extract tokens from browser
+#   slack-cli search <query>       - Search messages (Slack query syntax)
+#   slack-cli read <channel> [n]   - Read messages from a channel
+#   slack-cli draft <channel> <msg> - Save a draft locally (does NOT send)
+#   slack-cli send <draft_id>      - Send a draft (with confirmation)
+#   slack-cli help                 - Show full help
+
+set -euo pipefail
+
+CONFIG_DIR="${SLACK_CLI_HOME:-$HOME/.slack-cli}"
+CREDS_FILE="$CONFIG_DIR/credentials.json"
+DRAFTS_FILE="$CONFIG_DIR/drafts.json"
+SLACK_API="https://slack.com/api"
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+_check_deps() {
+  for cmd in curl jq; do
+    command -v "$cmd" &>/dev/null || { echo "ERROR: '$cmd' is required. Install it first." >&2; exit 1; }
+  done
+}
+
+_check_creds() {
+  if [[ ! -f "$CREDS_FILE" ]]; then
+    echo '{"ok":false,"error":"No credentials found. Run: slack-cli auth --domain <workspace>.slack.com"}' | jq .
+    exit 1
+  fi
+}
+
+_token() { jq -r .token "$CREDS_FILE"; }
+_cookie() { jq -r .d_cookie "$CREDS_FILE"; }
+_domain() { jq -r '.domain // empty' "$CREDS_FILE"; }
+
+_api() {
+  local method="$1"; shift
+  local response
+  response=$(curl -s "$SLACK_API/$method" \
+    -H 'Content-Type: application/x-www-form-urlencoded' \
+    -H "Cookie: d=$(_cookie)" \
+    -d "token=$(_token)&$*")
+
+  local ok err
+  ok=$(echo "$response" | jq -r '.ok')
+  if [[ "$ok" != "true" ]]; then
+    err=$(echo "$response" | jq -r '.error // empty')
+    if [[ "$err" == "token_revoked" || "$err" == "invalid_auth" || "$err" == "not_authed" ]]; then
+      echo '{"ok":false,"error":"Token expired. Run: slack-cli auth --domain '"$(_domain)"'"}' | jq .
+      exit 1
+    fi
+  fi
+  echo "$response"
+}
+
+_urlencode() {
+  python3 -c "import sys,urllib.parse; print(urllib.parse.quote(sys.stdin.read().strip()))" 2>/dev/null
+}
+
+_resolve_channel() {
+  local name="${1#\#}"
+  local response channel_id
+  response=$(_api search.messages "query=in:%23${name}&count=1")
+  channel_id=$(echo "$response" | jq -r '.messages.matches[0]?.channel.id // empty')
+  echo "$channel_id"
+}
+
+_resolve_users() {
+  local ids="$1"
+  local map="{}"
+  IFS=',' read -ra id_arr <<< "$ids"
+  for uid in "${id_arr[@]}"; do
+    [[ -z "$uid" || "$uid" == "null" ]] && continue
+    local resp name
+    resp=$(_api users.info "user=$uid" 2>/dev/null)
+    name=$(echo "$resp" | jq -r '.user.profile.display_name // .user.name // empty' 2>/dev/null)
+    if [[ -n "$name" ]]; then
+      map=$(echo "$map" | jq --arg k "$uid" --arg v "$name" '. + {($k): $v}')
+    fi
+  done
+  echo "$map"
+}
+
+# ── Commands ─────────────────────────────────────────────────────────────────
+
+cmd_auth() {
+  local domain=""
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --domain|-d) domain="$2"; shift 2 ;;
+      *) domain="$1"; shift ;;
+    esac
+  done
+
+  if [[ -z "$domain" ]]; then
+    # Check if we have a stored domain
+    if [[ -f "$CREDS_FILE" ]]; then
+      domain=$(_domain)
+    fi
+    if [[ -z "$domain" ]]; then
+      echo "Usage: slack-cli auth --domain <workspace>.slack.com" >&2
+      echo "Example: slack-cli auth --domain mycompany.slack.com" >&2
+      exit 1
+    fi
+  fi
+
+  # Normalize domain: strip protocol, ensure .slack.com suffix
+  domain="${domain#https://}"
+  domain="${domain#http://}"
+  domain="${domain%%/*}"
+  if [[ "$domain" != *".slack.com" ]]; then
+    domain="${domain}.slack.com"
+  fi
+
+  echo "Extracting Slack tokens from browser for $domain ..." >&2
+  mkdir -p "$CONFIG_DIR"
+
+  local profile_dir="${SLACK_CLI_CHROME_PROFILE:-$HOME/.slack-cli/chrome-profile}"
+
+  local tmp_script
+  tmp_script=$(mktemp /tmp/slack-cli-auth-XXXXXX.mjs)
+  cat > "$tmp_script" << NODESCRIPT
+import { chromium } from 'playwright';
+import { writeFileSync, mkdirSync } from 'fs';
+
+const DOMAIN = '${domain}';
+const PROFILE_DIR = '${profile_dir}';
+const CREDS_FILE = '${CREDS_FILE}';
+const CONFIG_DIR = '${CONFIG_DIR}';
+
+async function extractTokens() {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  console.error('Launching browser with profile at ' + PROFILE_DIR + ' ...');
+  const context = await chromium.launchPersistentContext(PROFILE_DIR, {
+    headless: false,
+    channel: 'chrome',
+    args: ['--disable-blink-features=AutomationControlled'],
+    viewport: { width: 1280, height: 800 }
+  });
+
+  const page = context.pages()[0] || await context.newPage();
+  console.error('Navigating to https://' + DOMAIN + ' ...');
+  await page.goto('https://' + DOMAIN, { waitUntil: 'networkidle', timeout: 60000 });
+
+  const url = page.url();
+  if (url.includes('signin') || url.includes('/sso/')) {
+    console.error('ERROR: Not authenticated. Please log in to Slack in the browser window, then run auth again.');
+    await page.waitForTimeout(3000);
+    await context.close();
+    process.exit(1);
+  }
+
+  // Extract d cookie
+  const cookies = await context.cookies();
+  const dCookie = cookies.find(c => c.name === 'd' && c.domain.includes('slack.com'));
+  if (!dCookie) {
+    console.error('ERROR: Could not find session cookie.');
+    await context.close();
+    process.exit(1);
+  }
+
+  // Intercept API requests to capture xoxc token
+  let token = null;
+  const handler = (req) => {
+    const postData = req.postData();
+    if (postData) {
+      const match = postData.match(/token=(xoxc-[^&\\s]+)/);
+      if (match) token = decodeURIComponent(match[1]);
+    }
+  };
+  page.on('request', handler);
+
+  // Trigger API activity
+  await page.keyboard.press('Meta+g').catch(() => page.keyboard.press('Control+g').catch(() => {}));
+  await page.waitForTimeout(500);
+  await page.keyboard.press('Escape');
+  await page.waitForTimeout(1500);
+
+  if (!token) {
+    try {
+      const tab = await page.\$('button:has-text("DMs"), button:has-text("Activity")');
+      if (tab) { await tab.click(); await page.waitForTimeout(1500); }
+    } catch(e) {}
+  }
+
+  page.off('request', handler);
+
+  if (!token) {
+    console.error('ERROR: Could not capture API token. Try refreshing Slack in the browser and re-running auth.');
+    await context.close();
+    process.exit(1);
+  }
+
+  // Verify with auth.test
+  const authResp = await page.evaluate(async (t) => {
+    const resp = await fetch('/api/auth.test', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: 'token=' + t
+    });
+    return resp.json();
+  }, token);
+
+  const creds = {
+    token,
+    d_cookie: dCookie.value,
+    domain: DOMAIN,
+    team_id: authResp.team_id || '',
+    team: authResp.team || '',
+    user_id: authResp.user_id || '',
+    user: authResp.user || '',
+    url: authResp.url || '',
+    extracted_at: new Date().toISOString()
+  };
+
+  writeFileSync(CREDS_FILE, JSON.stringify(creds, null, 2) + '\\n', { mode: 0o600 });
+  console.error('Credentials saved for ' + creds.user + ' @ ' + creds.team + ' (' + creds.team_id + ')');
+  console.log(JSON.stringify({ ok: true, user: creds.user, team: creds.team, domain: DOMAIN }));
+  await context.close();
+}
+
+extractTokens().catch(err => { console.error('ERROR:', err.message); process.exit(1); });
+NODESCRIPT
+
+  node "$tmp_script"
+  local exit_code=$?
+  rm -f "$tmp_script"
+  return $exit_code
+}
+
+cmd_search() {
+  _check_creds
+  local query="$*"
+  if [[ -z "$query" ]]; then
+    echo '{"ok":false,"error":"Usage: slack-cli search <query>"}' | jq .
+    echo >&2
+    echo "Search modifiers:" >&2
+    echo "  from:@name / from:me    Messages from a person" >&2
+    echo "  in:#channel / in:@user  Messages in a channel or DM" >&2
+    echo "  before:YYYY-MM-DD       Before a date" >&2
+    echo "  after:YYYY-MM-DD        After a date" >&2
+    echo "  on:YYYY-MM-DD           On exact date" >&2
+    echo "  during:month            During a month or year" >&2
+    echo "  has::emoji: / has:pin   Has reaction or pin" >&2
+    echo "  is:saved / is:thread    Saved or thread messages" >&2
+    echo '  "exact phrase"          Exact match' >&2
+    echo "  -word                   Exclude word" >&2
+    echo "  wild*                   Wildcard (min 3 chars)" >&2
+    return 1
+  fi
+
+  local count="${SLACK_CLI_COUNT:-20}"
+  local sort="${SLACK_CLI_SORT:-timestamp}"
+  local sort_dir="${SLACK_CLI_SORT_DIR:-desc}"
+  local encoded_query
+  encoded_query=$(echo -n "$query" | _urlencode)
+
+  local response
+  response=$(_api search.messages "query=$encoded_query&count=$count&sort=$sort&sort_dir=$sort_dir")
+
+  echo "$response" | jq '{
+    ok: .ok,
+    query: .query,
+    total: .messages.total,
+    messages: [.messages.matches[]? | {
+      text,
+      user: .username,
+      channel: .channel.name,
+      channel_id: .channel.id,
+      ts,
+      permalink,
+      date: (.ts | split(".")[0] | tonumber | strftime("%Y-%m-%d %H:%M:%S"))
+    }]
+  }'
+}
+
+cmd_read() {
+  _check_creds
+  local channel="${1:-}"
+  local count="${2:-20}"
+
+  if [[ -z "$channel" ]]; then
+    echo '{"ok":false,"error":"Usage: slack-cli read <channel_name_or_id> [count]"}' | jq .
+    return 1
+  fi
+
+  local channel_id="$channel"
+  if [[ ! "$channel" =~ ^[CDG][A-Z0-9]+$ ]]; then
+    channel_id=$(_resolve_channel "$channel")
+    if [[ -z "$channel_id" || "$channel_id" == "null" ]]; then
+      echo "{\"ok\":false,\"error\":\"Could not resolve channel: $channel. Try the channel ID.\"}" | jq .
+      return 1
+    fi
+  fi
+
+  local response
+  response=$(_api conversations.history "channel=$channel_id&limit=$count")
+
+  local ok
+  ok=$(echo "$response" | jq -r '.ok')
+  if [[ "$ok" != "true" ]]; then
+    echo "$response" | jq '{ok, error}'
+    return 1
+  fi
+
+  local user_ids
+  user_ids=$(echo "$response" | jq -r '[.messages[]?.user] | unique | join(",")')
+  local user_map="{}"
+  if [[ -n "$user_ids" ]]; then
+    user_map=$(_resolve_users "$user_ids")
+  fi
+
+  echo "$response" | jq --argjson users "$user_map" --arg cid "$channel_id" '{
+    ok: .ok,
+    channel_id: $cid,
+    messages: [.messages[]? | {
+      text,
+      user_id: .user,
+      user: ($users[.user] // .user),
+      ts,
+      date: (.ts | split(".")[0] | tonumber | strftime("%Y-%m-%d %H:%M:%S")),
+      thread_ts: .thread_ts,
+      reply_count: .reply_count,
+      reactions: [.reactions[]? | {name, count}]
+    }] | reverse
+  }'
+}
+
+cmd_unreads() {
+  _check_creds
+  local response
+  response=$(_api search.messages "query=*&count=30&sort=timestamp&sort_dir=desc")
+  echo "$response" | jq '{
+    ok: .ok,
+    total_recent: .messages.total,
+    recent_messages: [.messages.matches[:30]? | .[]? | {
+      text: .text[0:200],
+      user: .username,
+      channel: .channel.name,
+      date: (.ts | split(".")[0] | tonumber | strftime("%Y-%m-%d %H:%M:%S")),
+      permalink
+    }]
+  }'
+}
+
+cmd_draft() {
+  _check_creds
+  local channel="${1:-}"
+  shift 2>/dev/null || true
+  local message="$*"
+
+  if [[ -z "$channel" || -z "$message" ]]; then
+    echo '{"ok":false,"error":"Usage: slack-cli draft <channel_name_or_id> <message>"}' | jq .
+    return 1
+  fi
+
+  local channel_id="$channel"
+  if [[ ! "$channel" =~ ^[CDG][A-Z0-9]+$ ]]; then
+    channel_id=$(_resolve_channel "$channel")
+    if [[ -z "$channel_id" || "$channel_id" == "null" ]]; then
+      echo "{\"ok\":false,\"error\":\"Could not resolve channel: $channel\"}" | jq .
+      return 1
+    fi
+  fi
+
+  mkdir -p "$CONFIG_DIR"
+  local draft_id
+  draft_id=$(date +%s)
+  local draft_entry
+  draft_entry=$(jq -n \
+    --arg id "$draft_id" \
+    --arg channel "$channel" \
+    --arg channel_id "$channel_id" \
+    --arg message "$message" \
+    --arg created "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    '{id:$id, channel:$channel, channel_id:$channel_id, message:$message, created:$created, status:"draft"}')
+
+  if [[ -f "$DRAFTS_FILE" ]]; then
+    local existing
+    existing=$(cat "$DRAFTS_FILE")
+    echo "$existing" | jq --argjson new "$draft_entry" '. + [$new]' > "$DRAFTS_FILE"
+  else
+    echo "[$draft_entry]" | jq . > "$DRAFTS_FILE"
+  fi
+
+  echo "$draft_entry" | jq '{ok:true, action:"draft_saved", info:"Use '\''slack-cli drafts'\'' to list, '\''slack-cli send <id>'\'' to send.", draft:.}'
+}
+
+cmd_drafts() {
+  if [[ ! -f "$DRAFTS_FILE" ]]; then
+    echo '{"ok":true,"drafts":[]}' | jq .
+    return 0
+  fi
+  jq '{ok:true, drafts:[.[] | select(.status == "draft")]}' "$DRAFTS_FILE"
+}
+
+cmd_send() {
+  _check_creds
+  local draft_id="${1:-}"
+  if [[ -z "$draft_id" ]]; then
+    echo '{"ok":false,"error":"Usage: slack-cli send <draft_id>"}' | jq .
+    return 1
+  fi
+
+  if [[ ! -f "$DRAFTS_FILE" ]]; then
+    echo '{"ok":false,"error":"No drafts found"}' | jq .
+    return 1
+  fi
+
+  local draft
+  draft=$(jq -r --arg id "$draft_id" '.[] | select(.id == $id and .status == "draft")' "$DRAFTS_FILE")
+  if [[ -z "$draft" ]]; then
+    echo '{"ok":false,"error":"Draft not found or already sent"}' | jq .
+    return 1
+  fi
+
+  local channel_id message
+  channel_id=$(echo "$draft" | jq -r '.channel_id')
+  message=$(echo "$draft" | jq -r '.message')
+
+  echo "About to send to channel $channel_id:" >&2
+  echo "$message" >&2
+  echo >&2
+  read -p "Confirm send? [y/N] " -r confirm
+  if [[ "$confirm" != "y" && "$confirm" != "Y" ]]; then
+    echo '{"ok":false,"action":"cancelled"}' | jq .
+    return 0
+  fi
+
+  local encoded_message
+  encoded_message=$(echo -n "$message" | _urlencode)
+
+  local response
+  response=$(_api chat.postMessage "channel=$channel_id&text=$encoded_message")
+
+  local ok
+  ok=$(echo "$response" | jq -r '.ok')
+  if [[ "$ok" == "true" ]]; then
+    jq --arg id "$draft_id" '[.[] | if .id == $id then .status = "sent" else . end]' "$DRAFTS_FILE" > "${DRAFTS_FILE}.tmp"
+    mv "${DRAFTS_FILE}.tmp" "$DRAFTS_FILE"
+    echo "$response" | jq '{ok, action:"sent", channel:.channel, ts:.ts}'
+  else
+    echo "$response" | jq '{ok, error}'
+  fi
+}
+
+cmd_channels() {
+  _check_creds
+  local response
+  response=$(_api search.messages "query=from:me&count=100&sort=timestamp&sort_dir=desc")
+  echo "$response" | jq '{
+    ok: .ok,
+    channels: [.messages.matches[]? | {name:.channel.name, id:.channel.id}] | unique_by(.id) | sort_by(.name)
+  }'
+}
+
+cmd_dms() {
+  _check_creds
+  local response
+  response=$(_api search.messages "query=from:me&count=50&sort=timestamp&sort_dir=desc")
+  echo "$response" | jq '{
+    ok: .ok,
+    recent_dms: [.messages.matches[]? | select(.channel.is_im == true or (.channel.name | test("^D|^mpdm"))) | {
+      channel:.channel.name, channel_id:.channel.id,
+      last_message:.text[0:100],
+      date: (.ts | split(".")[0] | tonumber | strftime("%Y-%m-%d %H:%M:%S"))
+    }] | unique_by(.channel_id)
+  }'
+}
+
+cmd_userinfo() {
+  _check_creds
+  local user="${1:-}"
+  if [[ -z "$user" ]]; then
+    echo '{"ok":false,"error":"Usage: slack-cli userinfo <user_id_or_email>"}' | jq .
+    return 1
+  fi
+
+  local response
+  if [[ "$user" == *"@"* ]]; then
+    response=$(_api users.lookupByEmail "email=$user")
+  elif [[ "$user" =~ ^U[A-Z0-9]+$ ]]; then
+    response=$(_api users.info "user=$user")
+  else
+    response=$(_api search.messages "query=from:@$user&count=1")
+    echo "$response" | jq '{ok, note:"Partial match via search. Use user ID or email for exact lookup.", match:(.messages.matches[0]? | {username, text:.text[0:100], channel:.channel.name})}'
+    return 0
+  fi
+
+  echo "$response" | jq '{ok, user:{id:.user.id, name:.user.name, real_name:.user.real_name, display_name:.user.profile.display_name, email:.user.profile.email, title:.user.profile.title, status:.user.profile.status_text, tz:.user.tz}}'
+}
+
+cmd_whoami() {
+  _check_creds
+  _api auth.test | jq '{ok, user, user_id, team, team_id, url}'
+}
+
+cmd_config() {
+  if [[ -f "$CREDS_FILE" ]]; then
+    jq '{domain, team, user, user_id, team_id, extracted_at}' "$CREDS_FILE"
+  else
+    echo '{"error":"Not configured. Run: slack-cli auth --domain <workspace>.slack.com"}' | jq .
+  fi
+}
+
+cmd_help() {
+  cat << 'EOF'
+slack-cli - Slack CLI for coding agents
+
+SETUP:
+  slack-cli auth --domain <workspace>.slack.com
+    Opens a browser to extract API tokens from your authenticated Slack session.
+    Requires: playwright (npm i -g playwright), Chrome browser with active Slack login.
+
+COMMANDS:
+  auth [--domain <dom>]      Extract tokens from browser session
+  whoami                     Show current authenticated user
+  config                     Show current configuration
+  search <query>             Search messages (full Slack query syntax)
+  read <channel> [count]     Read messages from a channel (name or ID)
+  unreads                    Show recent activity
+  draft <channel> <message>  Save a draft locally (does NOT send)
+  drafts                     List saved drafts
+  send <draft_id>            Send a draft (interactive confirmation)
+  channels                   List your channels
+  dms                        List recent DMs
+  userinfo <user>            Look up user by ID, email, or name
+  help                       Show this help
+
+SEARCH MODIFIERS:
+  from:@name / from:me       Messages from a person
+  in:#channel / in:@user     Messages in a channel or DM
+  before:YYYY-MM-DD          Before a date
+  after:YYYY-MM-DD           After a date
+  on:YYYY-MM-DD              On exact date
+  during:month               During a month or year
+  has::emoji: / has:pin      Has reaction or pin
+  is:saved / is:thread       Saved or thread messages
+  "exact phrase"             Exact match
+  -word                      Exclude word
+  wild*                      Wildcard (min 3 chars)
+
+ENVIRONMENT VARIABLES:
+  SLACK_CLI_HOME             Config directory (default: ~/.slack-cli)
+  SLACK_CLI_CHROME_PROFILE   Chrome profile path for auth (default: ~/.slack-cli/chrome-profile)
+  SLACK_CLI_COUNT            Results per page (default: 20)
+  SLACK_CLI_SORT             Sort by: timestamp or score (default: timestamp)
+  SLACK_CLI_SORT_DIR         Sort direction: asc or desc (default: desc)
+
+EXAMPLES:
+  slack-cli auth --domain mycompany.slack.com
+  slack-cli search "from:me in:#engineering after:2025-01-01"
+  slack-cli search "deployment error has::eyes:"
+  slack-cli read engineering 10
+  slack-cli draft general "Hey team, the fix is ready for review"
+  slack-cli userinfo user@company.com
+
+All output is structured JSON for easy parsing by scripts and AI agents.
+EOF
+}
+
+# ── Main ─────────────────────────────────────────────────────────────────────
+
+_check_deps
+
+case "${1:-help}" in
+  auth)      shift; cmd_auth "$@" ;;
+  search)    shift; cmd_search "$@" ;;
+  read)      shift; cmd_read "$@" ;;
+  history)   shift; cmd_read "$@" ;;
+  unreads)   cmd_unreads ;;
+  draft)     shift; cmd_draft "$@" ;;
+  drafts)    cmd_drafts ;;
+  send)      shift; cmd_send "$@" ;;
+  channels)  cmd_channels ;;
+  dms)       cmd_dms ;;
+  userinfo)  shift; cmd_userinfo "$@" ;;
+  whoami)    cmd_whoami ;;
+  config)    cmd_config ;;
+  help|--help|-h) cmd_help ;;
+  *)         echo "Unknown command: $1. Run 'slack-cli help'." >&2; exit 1 ;;
+esac

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@alankyshum/slack-cli",
+  "version": "1.0.0",
+  "description": "Slack CLI for coding agents — search, read, and draft messages via the Slack Web API using browser-extracted tokens",
+  "bin": {
+    "slack-cli": "./bin/slack-cli"
+  },
+  "scripts": {
+    "lint:shell": "shellcheck bin/slack-cli",
+    "lint:python": "ruff check slack_cli/",
+    "lint": "npm run lint:shell && npm run lint:python",
+    "format": "ruff format slack_cli/"
+  },
+  "keywords": [
+    "slack",
+    "cli",
+    "agent",
+    "search",
+    "messages",
+    "automation"
+  ],
+  "author": "Alan Shum",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alankyshum/slack-cli.git"
+  },
+  "homepage": "https://github.com/alankyshum/slack-cli#readme",
+  "bugs": {
+    "url": "https://github.com/alankyshum/slack-cli/issues"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "files": [
+    "bin/slack-cli"
+  ]
+}