slkcli AGENTS.md

AGENTS.md — slk Development Guide

This is the full loop for working on slk. Follow this every time you add, change, or fix something.

Project Structure

slk/
├── bin/slk.js          # CLI entry point — command routing, help text, aliases
├── src/
│   ├── api.js          # Slack API wrapper — fetch, auth headers, pagination
│   ├── auth.js         # Credential extraction — Keychain, LevelDB, token cache
│   ├── commands.js     # All command implementations (read, send, saved, etc.)
│   └── drafts.js       # Draft-specific commands (create, list, drop)
├── package.json        # Version, bin mapping, metadata
├── README.md           # Full documentation for users
├── SKILL.md            # Agent skill file (used by Moltbot/ClawdBot)
├── AGENTS.md           # This file — dev guide for AI agents
└── CLAUDE.md           # Quick reference for Claude Code / Codex

The Full Loop: Adding a New Feature

1. Write the Code

Add your command implementation in src/commands.js:

• Export an async function
• Use slackApi() or slackPaginate() from api.js
• Use existing helpers: getUsers(), resolveChannel(), formatTs(), userName()
• Follow the existing pattern: fetch data → format → console.log output
• Handle errors with console.error + process.exit(1)

If your new API endpoint needs POST (most Slack endpoints do), add it to the writeMethods array in src/api.js.

2. Wire Up the CLI

In bin/slk.js:

• Add the command to the HELP string (with alias and description)
• Add a case in the switch block
• Follow the pattern: validate args → call command function → handle aliases

3. Test It

# Run directly (no install needed)
node bin/slk.js <your-command>

# Or if globally linked:
slk <your-command>

# Test edge cases:
# - No args (should show usage)
# - Invalid channel
# - Auth expired (should auto-refresh)

4. Update Documentation

All three must be updated:

1. README.md — Add to:
   • Commands table
   • Quickstart examples (if user-facing)
   • Flags table (if new flags)
   • Agent usage patterns (if relevant)