# clacks
the default mode of degenerate communication.

## Installation

**Recommended** - install globally with uv (best for use with coding agents like Claude Code, Cursor):
```bash
uv tool install slack-clacks
```

**Alternative** - run directly without installation:
```bash
uvx --from slack-clacks clacks
```

**Alternative** - works with pip, poetry, or any package manager:
```bash
pip install slack-clacks
```

## Authentication

Authenticate via OAuth:
```bash
clacks auth login -c <context-name>
```

### Modes

clacks supports three authentication modes:

#### clacks mode (default)

Full workspace access via OAuth.

```bash
clacks auth login --mode clacks
```

Permissions: channels, groups, DMs, MPIMs, files, search

#### clacks-lite mode

Secure, DM-focused access via OAuth. Use for security-conscious environments where channel access isn't needed.

```bash
clacks auth login --mode clacks-lite
```

Permissions: DMs, MPIMs, reactions only

#### cookie mode

Browser session authentication. Use for quick testing or when OAuth is impractical.

```bash
clacks auth login --mode cookie
```

Extract xoxc token and d cookie from browser. No OAuth app needed. See [docs/cookie-auth.md](docs/cookie-auth.md) for extraction instructions.

**Warning**: Cookie mode is known to cause logout issues on Slack Enterprise workspaces and may trigger security warnings about your account.

### Scopes

Operations requiring unavailable scopes will fail with a clear error message and re-authentication instructions.

### Certificate

OAuth requires HTTPS. clacks includes a bundled self-signed certificate, so no setup is required.

To generate your own certificate:
```bash
clacks auth cert generate
```

### Account Management

View current authentication status:
```bash
clacks auth status
```

Revoke authentication:
```bash
clacks auth logout
```

## Configuration

Multiple authentication contexts supported. Initialize configuration:
```bash
clacks config init
```

List available contexts:
```bash
clacks config contexts
```

Switch between contexts:
```bash
clacks config switch -C <context-name>
```

View current configuration:
```bash
clacks config info
```

## Messaging

### Send

Send to channel:
```bash
clacks send -c "#general" -m "message text"
clacks send -c "C123456" -m "message text"
```

Send direct message:
```bash
clacks send -u "@username" -m "message text"
clacks send -u "U123456" -m "message text"
```

Reply to thread:
```bash
clacks send -c "#general" -m "reply text" -t "1234567890.123456"
```

### Read

Read messages from channel:
```bash
clacks read -c "#general"
clacks read -c "#general" -l 50
```

Read direct messages:
```bash
clacks read -u "@username"
```

Read thread:
```bash
clacks read -c "#general" -t "1234567890.123456"
```

Read specific message:
```bash
clacks read -c "#general" -m "1234567890.123456"
```

### Recent

View recent messages across all conversations:
```bash
clacks recent
clacks recent -l 50
```

## Output

All commands output JSON to stdout. Redirect to file:
```bash
clacks auth status -o output.json
```

## Requirements

- Python >= 3.13
- Slack workspace admin approval for OAuth app installation
