v0.2.3

What's Changed

Hotfix

• Fixed conversation tag parsing for Help Scout conversation responses, which use tag rather than name for attached tag objects.
• Fixed hs inbox conversations tags list <id> returning an empty tag list when tags were present.
• Fixed tags add and tags remove preserving an empty current tag list instead of the existing Help Scout tags.

Validation

• Added regression tests using Help Scout's real conversation tag response shape.
• Verified against a live test conversation that:
  • tags list reads existing tags without mutating them.
  • tags add preserves existing tags.
  • tags remove removes only the requested tag.

Notes

• This release supersedes v0.2.2 for the new conversation tag commands.
• The Windows installer default will be advanced to v0.2.3 automatically after this stable release is published.

v0.2.2

What's Changed

Conversation Tags

• Added safe conversation tag management commands:
  • hs inbox conversations tags list <id>
  • hs inbox conversations tags add <id> --tag ...
  • hs inbox conversations tags remove <id> --tag ...
  • hs inbox conversations tags clear <id>
• Kept tags set as the explicit full replacement command and updated docs to make that behavior clear.
• Allowed tags set --tag "" to intentionally send an empty tag list and remove all tags.
• Made add and remove preserve existing tags by reading the current tag list before submitting the full updated list.

Development

• Added Docker-based Go test wrappers so full local test runs use isolated auth, config, and cache state.
• Updated docs/inbox-api.md with the full conversation tag command list and replacement warnings.
• Updated DEVELOPMENT.md with Docker test wrapper usage.

Notes

• npm package versioning is driven from this release tag when the release is published.
• The Windows installer default will be advanced to v0.2.2 automatically after this stable release is published.

v0.2.1

What's Changed

Fixes

• Fixed hs inbox conversations tags set so it sends PUT /v2/conversations/{id}/tags, matching Help Scout's API and unblocking tag replacement from the CLI.
• Fixed the Windows install script so it no longer fails on GitHub's /releases/latest redirect; it now uses a CI-managed stable release pin.
• Added Windows ARM64 detection to the PowerShell installer so ARM64 machines download the windows_arm64 asset.

Internal

• Added endpoint method/path coverage across the Inbox and Docs API clients to catch GET/POST/PUT/PATCH/DELETE regressions.

Release Notes

• npm package versioning is driven from this release tag when the release is published.
• The Windows installer default will be advanced to v0.2.1 automatically after this stable release is published.

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