@hostreach/cli

Official CLI, MCP server, and Agent Skill for the Hostreach public API. Manage campaigns, extract leads from real-estate portals, run WhatsApp outreach, valuations, fichas, and scheduling — from your terminal or inside AI coding agents (Cursor, Claude Desktop, Codex).

API docs: docs.hostreach.io/api

Requirements

• Node.js 18+
• A Hostreach API key (hr_live_... or hr_test_...) from Settings › Workspace › Acceso API in the dashboard

Install

# Global install (recommended)
npm install -g @hostreach/cli

# Or run without installing
npx -p @hostreach/cli hostreach --help

Note: The package name is @hostreach/cli, but the CLI binary is hostreach. Use npx -p @hostreach/cli hostreach … — not npx @hostreach/cli (that fails because there is no cli executable).

Binaries included

| Command | Description | |---------|-------------| | hostreach | CLI — call any public API endpoint | | hostreach-mcp | MCP server (stdio) for AI agents | | mcp-hostreach | Alias of hostreach-mcp |

Quick start

# 1. Authenticate (interactive — saves to ~/.config/hostreach/)
hostreach auth login

# 2. Verify
hostreach auth status

# 3. Check workspace and quota
hostreach me list

# 4. List available API resources
hostreach list

# 5. List campaigns
hostreach campaigns list --pretty

Authentication

Credentials are resolved in this order:

| Priority | Method | Example | |----------|--------|---------| | 1 | --api-key flag | hostreach campaigns list --api-key hr_live_... | | 2 | Config file | hostreach auth login → ~/.config/hostreach/config.json | | 3 | Environment variable | export HOSTREACH_API_KEY=hr_live_... |

hostreach auth login    # save API key + base URL
hostreach auth status   # show masked key and base URL
hostreach auth logout   # remove stored config

Optional: point to a custom API host (e.g. staging):

export HOSTREACH_API_BASE_URL=https://api.hostreach.io
hostreach auth login

CLI usage

Commands are auto-generated from the OpenAPI spec (/v1/public/v1/openapi.json), so they stay in sync with the API.

hostreach <resource> <action> [--flags]

Discover endpoints

hostreach list                      # all resources
hostreach list campaigns            # actions for campaigns
hostreach campaigns list --help     # parameters for one action

Examples

# Campaigns
hostreach campaigns list
hostreach campaigns create --name "Valencia Q3" --platform idealista
hostreach campaigns execute --id <campaignId>
hostreach campaigns stats --id <campaignId>

# Leads
hostreach leads list --status PENDING --limit 20
hostreach leads get --id <leadId>

# Extractions
hostreach platforms locations --platform idealista --q "Valencia"
hostreach extractions create --platform idealista --filters '{"operation":"rent"}'
hostreach extractions get --id <extractionId>

# Messaging
hostreach messaging conversations --limit 20

Output options

| Flag | Effect | |------|--------| | --pretty | Pretty-printed JSON | | --format table | ASCII table | | --format csv | CSV (stdout) | | --format markdown | Markdown table | | --output <path> | Save to file; print only the path | | --clean | Strip nulls and empty values | | --refresh | Force refresh of cached OpenAPI spec |

Status messages go to stderr; data goes to stdout (safe for piping).

MCP server (Cursor / Claude Desktop)

Expose 49 curated tools for campaigns, leads, extractions, messaging, webhooks, templates, valuations, fichas, and scheduling.

Auto-configure

hostreach auth login
hostreach agent add cursor     # project: ./.cursor/mcp.json (use --project)
hostreach agent add claude     # ~/.claude/claude_desktop_config.json
hostreach agent add codex      # ~/.codex/mcp.json

Restart the agent after adding the server.

Manual configuration

{
  "mcpServers": {
    "hostreach": {
      "command": "npx",
      "args": ["-y", "--package=@hostreach/cli", "hostreach-mcp"],
      "env": {
        "HOSTREACH_API_KEY": "hr_live_your_key_here"
      }
    }
  }
}

Agent Skill

Teach coding agents how to use Hostreach (workflows, scopes, pagination, error handling):

Install via CLI

hostreach skill install                    # Cursor (default), global
hostreach skill install --agent claude     # Claude Code, global
hostreach skill install --agent codex      # Codex, global
hostreach skill install --agent opencode   # OpenCode, global
hostreach skill install --all              # all supported agents, global
hostreach skill install --all --project    # all agents, project-level (cwd)
hostreach skill print                      # dump to stdout — paste anywhere

Install without the CLI

npx skills add hostreach/agent-skills                   # interactive
npx skills add hostreach/agent-skills -g -a cursor      # global, Cursor
npx skills add hostreach/agent-skills -g -a claude-code # global, Claude Code
npx skills add hostreach/agent-skills -g --all          # global, all agents

Requires the skills CLI (runs via npx, no install needed).

Use MCP + Skill together for the best experience: MCP gives direct tool access; the Skill documents best practices and common workflows.

API scopes

When creating a limited API key, pick scopes that match your use case. An empty scopes array means full access.

| Scope | Access | |-------|--------| | campaigns:read / write | Campaigns CRUD and lifecycle | | leads:read / write | Leads and notes | | extractions:read / write | Portal extractions | | platforms:read | Filters and location search | | messaging:read / write | WhatsApp inbox | | templates:read / write | Message templates | | accounts:read / write | WhatsApp accounts | | valuations:read / write | Property valuations | | fichas:read / write | Listing sheets | | scheduling:read / write | Calendar and appointments | | webhooks:read / write | Event webhooks |

Development (from source)

git clone <repo>
cd mcp-hostreach
npm install
npm run build
node dist/cli.js --help
HOSTREACH_API_KEY=hr_live_... node dist/index.js   # MCP server

Links

• Hostreach
• API documentation
• npm package

Support

[email protected]