v0.2.0

What's new

ML-powered PII redaction

The regex-based name detector has been replaced with a multilingual NER (Named Entity Recognition) model. Person names in freeform text — conversation bodies, subjects, notes — are now detected by an ML model and replaced with consistent fake identities. No more false positives on phrases like "Technical Support" or "New Zealand".

• 10 languages supported: Arabic, Chinese, Dutch, English, French, German, Italian, Latvian, Portuguese, Spanish
• Deterministic pseudonyms: same real identity → same fake name, email, and phone across commands and sessions
• Mode-aware: customers mode redacts only customer data; all mode redacts everyone
• Runs locally: the model runs entirely on your machine via ONNX Runtime — no API calls, no data leaves your system

The model bundle (~100 MB) is downloaded on first use:

hs pii-model install     # download the model
hs pii-model status      # check install status
hs pii-model uninstall   # remove from disk

Without the model installed, freeform text fields are hidden with a notice. Structured field redaction (names, emails, phones) always works regardless.

Keyring fallback for headless Linux

Credential storage now falls back gracefully to the config file on headless Linux systems where no keyring backend (GNOME Keyring, KWallet, etc.) is available.

Documentation

• README restructured into a focused landing page with links to full API references
• New Inbox API reference — complete command and flag documentation
• New Docs API reference — previously undocumented despite being fully implemented
• New Developer guide — project structure, build, test architecture, release process

Changelog

• feat: replace regex name detection with ML-based NER
• feat: keyring fallback to config file on headless Linux
• fix: mode-aware PII redaction, long-text chunking
• fix: patch onnxruntime-purego AddCleanup double-free
• refactor: rename ner commands to pii-model for user-facing consistency
• docs: split README into focused docs, add full Docs API reference
• ci: add pii-model release workflow, guard npm-publish

PII Model v0.2.0

PII redaction model bundle (distilbert-base-multilingual-cased-ner-hrl, INT8 quantized) + ONNX Runtime.

v0.1.1

Changelog

• 774c1df Update readme
• 4223d89 fix: npm postinstall asset filename mismatch

v0.1.0

hs-cli v0.1.0

First official release of the HelpScout CLI — a command-line interface and embedded MCP server for the HelpScout Inbox and Docs APIs.

Install

# macOS
brew install operator-kit/tap/hs

# Linux / macOS (one-liner)
curl -sSL https://raw.githubusercontent.com/operator-kit/hs-cli/main/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/operator-kit/hs-cli/main/install.ps1 | iex

# npm (zero-install MCP usage)
npx -y @operatorkit/hs mcp -t stdio

# From source
go install github.com/operator-kit/hs-cli/cmd/hs@latest

Inbox API — full coverage

Complete CRUD support for all HelpScout Inbox API v2 resources:

• Conversations — list, search, get, create, update, delete, tags, custom fields, snooze
• Threads — list, reply, note, create (chat/customer/phone), update, source, source-rfc822
• Customers — list, search, get, create, update, overwrite, delete
• Mailboxes — list, get, folders, custom fields, routing
• Tags — list, get
• Users — list, get, me, delete, status
• Teams — list, members
• Organizations — full CRUD, conversations, customers, properties
• Workflows — list, run, update-status
• Webhooks — full CRUD
• Saved Replies — full CRUD
• Reports — all 9 report families (chats, company, conversations, customers, docs, email, productivity, ratings, users)
• Properties — customer and conversation property definitions
• Ratings — get
• Attachments — upload, list, get, delete

Docs API — full coverage

Complete CRUD support for all HelpScout Docs API v1 resources:

• Articles — list, search, get, create, update, delete, upload, revisions, drafts, related, view count
• Categories — list, get, create, update, reorder, delete
• Collections — list, get, create, update, delete
• Sites — list, get, create, update, delete, restrictions
• Redirects — list, get, find, create, update, delete
• Assets — article upload, settings upload

MCP server

Embedded MCP server with 124 auto-discovered tools (85 inbox + 39 docs). Start with:

hs mcp -t stdio

MCP client config (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "helpscout": {
      "command": "npx",
      "args": ["-y", "@operatorkit/hs", "mcp", "-t", "stdio"],
      "env": {
        "HS_INBOX_APP_ID": "your-app-id",
        "HS_INBOX_APP_SECRET": "your-app-secret",
        "HS_INBOX_PERMISSIONS": "*:read"
      }
    }
  }
}

Output formats

• Table — human-readable (default)
• JSON — clean output with HAL noise stripped, HTML→markdown, fields normalized
• JSON-full — raw API passthrough
• CSV — RFC 4180

Safety features

• PII redaction — deterministic, layered pipeline covering structured fields, free-text, and source payloads. Modes: off, customers, all. Gated --unredacted override.
• Permissions — allowlist-based resource:operation pairs. Restrict exactly which commands are permitted via HS_INBOX_PERMISSIONS / HS_DOCS_PERMISSIONS.
• Rate limiting — built-in rate limiters respect API quotas (Inbox: 200/min, Docs: 2000/10min).

Other features

• Self-update — hs update checks GitHub Releases and replaces the binary in-place. Background daily check with stderr notice.
• Pagination — --page, --per-page, --no-paginate (fetch all pages).
• Debug logging — --debug logs full HTTP request/response to hs-debug.log.
• Shell completion — bash, zsh, fish, powershell.
• Config — YAML config file + env var overrides + OS keyring credential storage.
• Workflow tools — hs inbox tools briefing for aggregated team/agent conversation data.

Platforms

OS	Arch
Linux	amd64, arm64
macOS	amd64 (Intel), arm64 (Apple Silicon)
Windows	amd64, arm64