> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hostreach.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Call any Hostreach API endpoint from your terminal. Auto-generated from the OpenAPI spec.

The Hostreach CLI (`hostreach`) is included in the `@hostreach/cli` npm package. Every public API endpoint is available as a subcommand, auto-generated from the OpenAPI spec and always in sync.

## Install

```bash theme={null}
npm install -g @hostreach/cli
```

Or run without installing:

```bash theme={null}
npx -p @hostreach/cli hostreach --help
```

## Authenticate

```bash theme={null}
hostreach auth login      # interactive — saves key + base URL to ~/.config/hostreach/
hostreach auth status     # show current auth
hostreach auth logout     # remove stored credentials
```

You can also pass credentials inline or via environment variable:

```bash theme={null}
# Flag (highest priority)
hostreach campaigns list --api-key hr_live_your_key_here

# Environment variable
export HOSTREACH_API_KEY=hr_live_your_key_here
hostreach campaigns list
```

## Usage

```bash theme={null}
hostreach <resource> <action> [--flags]
```

### Discover endpoints

```bash theme={null}
hostreach list                      # all resources
hostreach list campaigns            # actions for campaigns
hostreach campaigns list --help     # parameters for one action
```

### Examples

```bash theme={null}
# Identity
hostreach me list

# Platforms
hostreach platforms list
hostreach platforms locations --platform idealista --q "Valencia"

# Extractions
hostreach extractions create --platform idealista --filters '{"operation":"rent","location":"..."}' --max-results 50
hostreach extractions get --id <id>        # poll until status=COMPLETED
hostreach extractions leads --id <id>

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

# Leads
hostreach leads list --status PENDING --limit 20
hostreach leads update --id <id> --status CONTACTED

# Messaging
hostreach messaging conversations --limit 20
hostreach messaging send --lead-id <id> --message "Hola!"
```

### Output formats

| Flag                | Output                         |
| ------------------- | ------------------------------ |
| *(default)*         | Compact JSON                   |
| `--pretty`          | Pretty-printed JSON            |
| `--format table`    | ASCII table                    |
| `--format csv`      | CSV (stdout)                   |
| `--format markdown` | Markdown table                 |
| `--output <path>`   | Save to file; prints file path |
| `--clean`           | Strip nulls and empty values   |

```bash theme={null}
hostreach leads list --format csv > leads.csv
hostreach campaigns list --format markdown
hostreach leads list --output ./leads.json
```

All status messages go to **stderr**; data goes to **stdout** — safe for piping.

### Refresh OpenAPI cache

```bash theme={null}
hostreach campaigns list --refresh    # force re-fetch of OpenAPI spec
```