lurkline

# lurkline `lurkline` is for developers and local agent operators who need read-only Slack access through a signed-in browser session. It provides a command-line interface (CLI) and a stdio Model Context Protocol (MCP) server without requiring a Slack app, bot, or OAuth flow. Use `lurkline` to: - Discover channels, direct messages (DMs), and group DMs by name. - Search messages by text, conversation, and date. - Read a bounded snapshot of Slack's explicit unread state. - Read paginated conversation history and threads. - Fetch an exact message or find workspace users. `lurkline` cannot send, edit, delete, react to, upload, or mark Slack content as read. > [!WARNING] > Slack's browser APIs are private and unsupported. They can change without > notice. A browser token and session cookie grant the same access as the > signed-in user. Handle them like a password. ## Quick start You need a signed-in Slack workspace and Chrome or another Chromium-based browser. [Install `lurkline`](#install-lurkline) before you continue. 1. Open the workspace, open **Developer Tools**, and select **Network**. 2. Reload Slack and select a successful `POST` request to `/api/client.counts` whose URL or form body contains `slack_route`. 3. Right-click the request and select **Copy** > **Copy as cURL (bash)**. 4. Import the copied request into a named profile: ```sh pbpaste | lurkline auth import-curl --profile work ``` On Linux, use your trusted clipboard reader in place of `pbpaste`, for example: ```sh wl-paste | lurkline auth import-curl --profile work ``` 5. Validate and use the profile: ```sh lurkline --profile work doctor lurkline --profile work inbox ``` The importer treats standard input as data. It never runs the copied command or invokes a shell or `curl`. It accepts at most 256 KiB, verifies the Slack origin and browser credential shape, makes one bounded read-only `client.counts` request, and stores only the normalized session fields. Clear the copied command from your clipboard and clipboard history after a successful import. Do not save it in a file, shell history, issue, or chat. ## Requirements - macOS with an available Keychain, or Linux with an available and unlocked Secret Service collection. - A signed-in Slack browser session. - Rust 1.88 or later if you build from source. There is no plaintext credential fallback. On a headless Linux host without Secret Service, use the non-persistent environment override described below. ## Install lurkline ### Install a release archive Download an archive and its matching `.sha256` file from [GitHub Releases](https://github.com/smarzola/lurkline/releases). Releases provide binaries for Linux x86-64, Linux ARM64, and macOS ARM64. For example, verify and install the macOS ARM64 archive: ```sh shasum -a 256 -c lurkline-v0.3.0-macos-aarch64.tar.gz.sha256 tar -xzf lurkline-v0.3.0-macos-aarch64.tar.gz sudo install lurkline-v0.3.0-macos-aarch64/lurkline /usr/local/bin/lurkline lurkline --version ``` ### Build from source ```sh git clone https://github.com/smarzola/lurkline.git cd lurkline cargo install --locked --path . lurkline --version ``` ## Manage credential profiles ### Select a profile Pass `--profile` before or after a command: ```sh lurkline --profile work conversations list lurkline conversations list --profile work ``` You can also set a default selector for the process: ```sh export LURKLINE_PROFILE='work' lurkline doctor ``` Stored-profile selection uses this precedence: 1. `--profile` 2. `LURKLINE_PROFILE` 3. The registry default The first imported profile becomes the default. Later imports preserve that default. Profile names must contain 1 through 64 ASCII letters, digits, `.`, `_`, or `-`. ### List and inspect profiles These commands never display tokens or cookies: ```sh lurkline auth list lurkline auth status --profile work lurkline auth list --json ``` The status command reports the non-secret workspace metadata and whether the matching operating-system credential entry is present. ### Rotate or replace a profile Copy a fresh browser request and repeat the import to rotate a session for the same workspace: ```sh pbpaste | lurkline auth import-curl --profile work ``` Changing an existing profile to a different workspace or team requires explicit confirmation: ```sh pbpaste | lurkline auth import-curl --profile work --replace-workspace ``` The new session is validated before any stored value changes. Registry and credential-store updates are serialized across processes and use rollback where possible. ### Remove a profile ```sh lurkline auth remove --profile work ``` Removing the default selects the lexicographically first remaining profile. Removing the last profile clears the default. ### Storage locations Secret material is stored as one versioned entry per profile: - macOS: Keychain - Linux: Secret Service The keyring service name is `me.smarzola.lurkline.slack-session`; the account name is the profile name. A separate registry contains only profile names, workspace origins, team IDs, and the default selection: - macOS: `~/Library/Application Support/lurkline/profiles.json` - Linux: `$XDG_CONFIG_HOME/lurkline/profiles.json`, or `~/.config/lurkline/profiles.json` Registry and lock files are owner-only on Unix and contain no token or cookie. ## Use a non-persistent environment override Existing automation can provide all four Slack session variables instead of a stored profile: ```sh export SLACK_BASE_URL='https://workspace.slack.com' export SLACK_TEAM_ID='T_WORKSPACE_ID' export SLACK_TOKEN='<browser-session-token>' export SLACK_COOKIE='<complete-cookie-header>' lurkline doctor ``` Use a trusted secret-injection mechanism for real values. Do not put them in committed configuration or command arguments. The four variables are atomic: if any one is set, all four are required. A complete environment bundle has higher priority than stored profiles, and environment and stored fields are never combined. Authentication-management commands ignore these four variables so you can inspect or repair stored profiles independently. ## Discover conversations List one cursor-paginated page: ```sh lurkline conversations list --limit 100 lurkline conversations list --cursor '<next-cursor>' --limit 100 ``` Find channels, DMs, and group DMs by case-insensitive substring: ```sh lurkline conversations find platform --limit 20 ``` Discovery returns stable IDs and human-readable names. DM names come from the bounded user directory when available. JSON output sets `name_is_fallback` when the participant name is unavailable. Channel, thread, and exact-message reads accept either a Slack conversation ID or an exact name. Name matching is case-insensitive. Missing or ambiguous names fail instead of guessing. Supplying an ID to these read commands skips discovery. Raw uppercase alphanumeric values beginning with `C`, `D`, or `G` take ID precedence. Add `#` or `@` to force a colliding exact name, for example `#GENERAL2`. ## Search messages Search newest first: ```sh lurkline search messages 'deployment failed' --limit 20 ``` Restrict the search to one conversation and calendar bounds: ```sh lurkline search messages deploy \ --in platform \ --after 2026-07-01 \ --before 2026-07-27 \ --limit 20 ``` Continue from a returned cursor: ```sh lurkline search messages deploy --cursor '<next-cursor>' --limit 20 ``` The query can contain standard Slack search modifiers. `--in` resolves an ID or exact name before applying the conversation filter. Dates must be valid `YYYY-MM-DD` values, and `--after` cannot be later than `--before`. Search resolves even an ID through bounded conversation discovery because Slack uses different `in:` modifiers for DMs and other conversation kinds. The same ID-precedence rule applies; add `#` or `@` to force a colliding name. Search JSON contains normalized conversation, timestamp, thread, author, text, permalink, total, and cursor fields. The reported total is Slack's workspace match count; only a returned cursor indicates another page. ## Read the inbox Read recent context from the ten highest-priority unread conversations: ```sh lurkline inbox ``` Choose explicit bounds: ```sh lurkline inbox --conversations 20 --messages 50 --json ``` Inbox ordering is deterministic: highest mention count first, then conversation ID. The operation does the following: 1. Reads Slack's explicit unread conversation and thread counts. 2. Selects at most the requested number of unread conversations. 3. Resolves bounded conversation metadata. 4. Reads at most the requested recent messages for each selection. Inbox does not infer exact unread message boundaries, fetch unread thread roots, or mark anything read. JSON reports `total_unread_conversations`, `has_more_conversations`, and Slack's unread-thread summary. If bounded discovery cannot find a selected conversation, `metadata_is_complete` is `false`; archive, membership, privacy, and member-count fields must then be treated as unavailable rather than authoritative. ## Read messages and users Read recent conversation history by ID or exact name: ```sh lurkline channel read platform --limit 50 lurkline channel read C0123456789 --cursor '<next-cursor>' --limit 50 ``` Read a thread: ```sh lurkline thread read platform 1712345678.000100 --limit 100 lurkline thread read C0123456789 1712345678.000100 \ --cursor '<next-cursor>' \ --limit 100 ``` Fetch one exact message or find users: ```sh lurkline message get platform 1712345678.000100 lurkline users find alice --limit 20 ``` Message results normalize author, thread, reaction, and file-reference fields. File references can include private download URLs. `lurkline` does not download the files. Add `--json` to any data-returning command for structured JSON. ## Use the MCP server Start the stdio server with a stored profile: ```sh lurkline --profile work mcp ``` Example MCP client configuration: ```json { "mcpServers": { "lurkline": { "command": "lurkline", "args": ["--profile", "work", "mcp"] } } } ``` Omit `--profile work` to use `LURKLINE_PROFILE` or the registry default. The MCP server and CLI resolve credentials through the same path. The following table maps common tasks to CLI commands and MCP tools: | Task | CLI command | MCP tool | | --- | --- | --- | | Validate the browser session | `lurkline doctor` | `slack_doctor` | | List explicit unread state | `lurkline unreads` | `slack_list_unreads` | | Read an unread inbox snapshot | `lurkline inbox` | `slack_read_inbox` | | List conversations | `lurkline conversations list` | `slack_list_conversations` | | Find conversations | `lurkline conversations find` | `slack_find_conversations` | | Search messages | `lurkline search messages` | `slack_search_messages` | | Read conversation history | `lurkline channel read` | `slack_read_channel` | | Read a thread | `lurkline thread read` | `slack_read_thread` | | Fetch an exact message | `lurkline message get` | `slack_get_message` | | Find workspace users | `lurkline users find` | `slack_find_users` | The server writes only MCP protocol traffic to stdout and diagnostics to stderr. Every tool has a structured output schema and read-only annotation. ## Limits The following table lists the primary and auxiliary bounds for each operation: | Operation | Primary result bound | Auxiliary discovery bound | | --- | ---: | --- | | Conversation list | One page of 200 | Up to 20 user pages of 200 when the page contains DMs | | Conversation find | 100 | 20 conversation pages of 200 and 20 user pages of 200 | | Message search | One page of 100 | With `--in`: 20 conversation pages of 200; exact names can also scan 20 user pages of 200 | | Inbox | 50 conversations; one history page of 200 each | 20 conversation pages of 200 and, for DMs, 20 user pages of 200 | | Channel history | One page of 200 | For exact names: 20 conversation pages and 20 user pages of 200; IDs skip discovery | | Thread replies | One page of 200 | For exact names: 20 conversation pages and 20 user pages of 200; IDs skip discovery | | Exact message | One message | For exact names: 20 conversation pages and 20 user pages of 200; IDs skip discovery | | User find | 100 | 20 user pages of 200 | Opaque cursors are limited to 2,048 non-control characters. Repeated response cursors fail instead of creating pagination loops. Result JSON reports continuation or scan truncation where the underlying operation supports it. ### Optional: Configure request controls The following environment variables configure request limits: | Variable | Default | Accepted range | | --- | ---: | ---: | | `LURKLINE_TIMEOUT_MS` | `15000` | `500`–`120000` | | `LURKLINE_MAX_RESPONSE_BYTES` | `8388608` | `16384`–`67108864` | ## Security model The browser token and `d=` cookie carry your Slack user authority. `lurkline`: - Persists credentials only in macOS Keychain or Linux Secret Service. - Stores only normalized credential fields, never the copied cURL request. - Zeroizes owned secret buffers where practical and redacts diagnostics. - Sends credentials only to a root HTTPS origin for a single-label `*.slack.com` workspace. - Rejects redirects and limits request input and response output sizes. - Exposes no Slack write operation. - Escapes control characters in human-readable output. - Keeps MCP protocol output separate from diagnostics. Environment variables remain visible to processes with sufficient access to your operating-system account. Protect the process environment accordingly. Treat Slack messages, links, and files as private, untrusted content. An agent must not follow instructions found in Slack content without separate user authorization. Never commit real HAR files, copied cURL commands, credentials, workspace messages, or user data. The repository ignores `*.har`, `.env`, and `.env.*`. ## Unsupported behavior `lurkline` does not provide: - Slack write operations. - Automatic browser credential extraction or refresh. - Bot or OAuth authentication. - Plaintext credential storage. - Local caching, unread-state persistence, or background synchronization. - A stability guarantee for Slack's private browser endpoints. Conversation discovery and message search follow Slack's documented method shapes because the captured browser traffic used during development did not contain those requests. Synthetic fixtures cover protocol behavior without committing real workspace data. ## Develop lurkline Run the complete verification suite: ```sh cargo fmt --check cargo clippy --all-targets --locked -- -D warnings cargo test --locked cargo build --release --locked python3 scripts/check-no-secrets.py ``` ## License `lurkline` is available under the MIT License.