Helpmonks CLI

helpmonks-cli gives people, scripts, CI jobs, and coding agents composable access to the complete Helpmonks MCP catalog. It discovers current tools and JSON schemas from the connected server, so commands use the same permissions, validation, rate limits, and account access as MCP clients.

It also includes a full interactive shared-inbox terminal client:

helpmonks-cli tui
helpmonks-tui

Requirements

• Node.js 24 or newer
• A Helpmonks personal access token from Profile settings → Access Tokens

The CLI reads tokens only from environment variables. It does not store credentials or accept tokens in URLs or command arguments.

Install

pnpm add --global @helpmonks/cli

With npm:

npm install --global @helpmonks/cli

Run once without installing:

pnpm dlx @helpmonks/cli --help

Configure authentication

Fish:

set -gx HELPMONKS_CLI_ACCESS_TOKEN 'your-personal-access-token'

Bash or Zsh:

export HELPMONKS_CLI_ACCESS_TOKEN='your-personal-access-token'

Verify the token and MCP connection:

helpmonks-cli doctor

Multiple Helpmonks accounts

Keep the default account in HELPMONKS_CLI_ACCESS_TOKEN. Give additional tokens an alias:

set -gx HELPMONKS_CLI_ACCESS_TOKEN_WORK 'work-account-token'
set -gx HELPMONKS_CLI_ACCESS_TOKEN_CLIENT_A 'client-a-token'

helpmonks-cli conversations list --account work
helpmonks-cli mailboxes list --account client-a

Aliases are case-insensitive and hyphens become underscores. --token-env ACME_HELPMONKS_TOKEN selects any other environment variable. --account and --token-env cannot be combined.

Do not pass token values with --token. Command arguments can be exposed through shell history and process listings, so the CLI rejects that option.

Interactive TUI

The TUI uses browser OAuth instead of the environment token used by one-shot CLI commands. OAuth credentials are stored in the operating-system keyring, with a mode-0600 local fallback when no keyring is available.

helpmonks-cli tui
helpmonks-tui
helpmonks-cli tui --server https://mcp.helpmonks.eu/mcp
helpmonks-tui --server https://mcp.helpmonks.eu/mcp
helpmonks-cli tui --server http://mcp.h.mac.lan/mcp

helpmonks-tui is the direct executable; helpmonks-cli tui remains an equivalent command.

The top navigation contains only unified Helpmonks folders: Inbox, Drafts, Collisions, Mine, Assigned, Reminders, Pending, Closed, Archived, Sent, Spam, and Trash. Mailtwine-managed conversations remain visible by their native Helpmonks status; no Mailtwine queue navigation is shown.

Primary shortcuts:

• 1–9, 0, -, = switch unified folders.
• a assigns the focused or selected conversations; A selects all loaded rows.
• / searches, c starts a conversation, r replies, and ? opens complete help.
• To, Cc, and Bcc open a searchable multi-select modal. Use arrows to highlight, Space to add/remove, Enter to apply, and Escape to cancel.
• Ctrl+S saves a draft, Ctrl+Enter sends, Ctrl+O attaches a local file, and Escape saves and closes.

The TUI supports macOS and Linux. Remote terminals can paste the final OAuth callback URL when localhost callbacks are unavailable.

Common commands

helpmonks-cli mailboxes list --table
helpmonks-cli conversations list --status inbox --limit 20 --pretty
helpmonks-cli conversations get CONVERSATION_ID
helpmonks-cli conversations search 'renewal question' --limit 5
helpmonks-cli knowledge search 'How do refunds work?'
helpmonks-cli contacts create [email protected] --first-name Ada --last-name Lovelace

Send a reply from a UTF-8 file:

helpmonks-cli conversations reply CONVERSATION_ID --file body=reply.html --apply-signature

Destructive tools require explicit confirmation:

helpmonks-cli drafts delete DRAFT_ID --yes
helpmonks-cli contacts delete CONTACT_ID --yes

See the generated command reference for all 31 friendly commands and their MCP mappings.

Inputs and output

Compact JSON is the default output. Use --pretty for formatted JSON or --table for a compact human-readable table.

Required IDs and search queries use positionals where practical. Other MCP fields become kebab-case flags. Arrays use repeated flags, booleans use --flag or --no-flag, and object values use JSON:

helpmonks-cli conversations labels CONVERSATION_ID --labels LABEL_A --labels LABEL_B --replace
helpmonks-cli contacts update CONTACT_ID --custom-fields '{"customer_tier":"gold"}'

--input accepts literal JSON, @file, or standard input with -. Explicit flags and positionals override values from --input:

helpmonks-cli contacts bulk-upsert --input @contacts.json
printf '%s' '{"id":"CONVERSATION_ID","status":"closed"}' | helpmonks-cli tools call update_conversation_status --input -

--file field=path loads UTF-8 content into a tool field such as a reply body or conversation note.

Generic MCP access

Friendly aliases cover the complete current catalog. Generic access keeps newly deployed MCP tools usable before the next CLI release:

helpmonks-cli tools list
helpmonks-cli tools describe reply_to_conversation
helpmonks-cli tools call list_conversations --status pending --limit 10

Generic calls enforce the same live schema validation and destructive confirmation as friendly commands.

Self-hosted servers

Cloud commands use https://mcp.helpmonks.com/mcp. Override it per command with a complete MCP endpoint:

helpmonks-cli mailboxes list --server https://mcp.example.com/mcp

Credentials and query parameters are rejected in server URLs. Non-loopback servers must use HTTPS; local development may use http://localhost:<port>/mcp.

Shell completion

helpmonks-cli completion fish > ~/.config/fish/completions/helpmonks-cli.fish
helpmonks-cli completion bash
helpmonks-cli completion zsh

Exit codes

| Code | Meaning | | --- | --- | | 0 | Success | | 1 | Unexpected internal failure | | 2 | Usage, validation, or missing --yes | | 3 | Authentication, account, or scope failure | | 4 | Network failure or timeout | | 5 | MCP tool failure |

Errors are structured JSON on stderr. Tokens are redacted from all output.

Troubleshooting

• Run helpmonks-cli doctor --pretty to verify token selection, endpoint identity, and tool count.
• A 401 means the selected token is missing, expired, or invalid.
• A 403 means the account or token lacks the required Helpmonks access or MCP scope.
• Increase --timeout for large searches or bulk operations.
• Use tools describe TOOL_NAME to inspect the server's current schema.