Help Scout Inbox CLI

Read-first Help Scout Inbox API surface for support operations and agent workflows.

Created by @debgotwired (Deb Mukherjee).

Quick Start

1. Install

See Install above.

2. Set Up Credentials

Get your access token from your API provider's developer portal, then store it:

help-scout-pp-cli auth set-token YOUR_TOKEN_HERE

Or set it via environment variable:

export HELP_SCOUT_BEARER_AUTH="your-token-here"

3. Verify Setup

help-scout-pp-cli doctor

This checks your configuration and credentials.

4. Try Your First Command

help-scout-pp-cli conversations list

Usage

Run help-scout-pp-cli --help for the full command reference and flag list.

Commands

conversations

Manage conversations

• help-scout-pp-cli conversations get - Get a conversation by ID.
• help-scout-pp-cli conversations get-v3 - Get a conversation by ID using the v3 conversation representation.
• help-scout-pp-cli conversations list - List conversations.

customers

Manage customers

• help-scout-pp-cli customers get - Get a customer by ID.
• help-scout-pp-cli customers list - List customers.

mailboxes

Manage mailboxes

• help-scout-pp-cli mailboxes get-mailbox - Get a Help Scout mailbox by ID.
• help-scout-pp-cli mailboxes list - List Help Scout mailboxes.

reports

Manage reports

• help-scout-pp-cli reports get-conversation - Get conversation reporting metrics.
• help-scout-pp-cli reports get-happiness - Get customer happiness reporting metrics.
• help-scout-pp-cli reports get-productivity - Get productivity reporting metrics.

tags

Manage tags

• help-scout-pp-cli tags - List Help Scout tags.

teams

Manage teams

• help-scout-pp-cli teams - List Help Scout teams.

users

Manage users

• help-scout-pp-cli users get - Get a Help Scout user by ID.
• help-scout-pp-cli users get-current - Get the authenticated Help Scout user.
• help-scout-pp-cli users list - List Help Scout users.

webhooks

Manage webhooks

• help-scout-pp-cli webhooks - List webhook subscriptions.

workflows

Manage workflows

• help-scout-pp-cli workflows - List Help Scout workflows.

Output Formats

# Human-readable table (default in terminal, JSON when piped)
help-scout-pp-cli conversations list

# JSON for scripting and agents
help-scout-pp-cli conversations list --json

# Filter to specific fields
help-scout-pp-cli conversations list --json --select id,name,status

# Dry run — show the request without sending
help-scout-pp-cli conversations list --dry-run

# Agent mode — JSON + compact + no prompts in one flag
help-scout-pp-cli conversations list --agent

Agent Usage

This CLI is designed for AI agent consumption:

• Non-interactive - never prompts, every input is a flag
• Pipeable - --json output to stdout, errors to stderr
• Filterable - --select id,name returns only fields you need
• Previewable - --dry-run shows the request without sending
• Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
• Offline-friendly - sync/search commands can use the local SQLite store when available
• Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.

Health Check

help-scout-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/help-scout-inbox-pp-cli/config.toml

Static request headers can be configured under headers; per-command header overrides take precedence.

Environment variables:

Name	Kind	Required	Description
HELP_SCOUT_BEARER_AUTH	per_call	Yes	Set to your API credential.

agentcookie (optional)

If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, help-scout-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.

Troubleshooting

Authentication errors (exit code 4)

• Run help-scout-pp-cli doctor to check credentials
• Verify the environment variable is set: echo $HELP_SCOUT_BEARER_AUTH Not found errors (exit code 3)
• Check the resource ID is correct
• Run the list command to see available items

---

Generated by CLI Printing Press