# LeadDemon agent setup

Public guide: https://leaddemon.io/agents
CLI version: 0.2.0

## Requirements

- Python 3.11 or newer
- pipx
- A LeadDemon account with subscription or demo access
- A human account owner available once to approve CLI authorization

Install pipx for the current operating system: https://pipx.pypa.io/latest/how-to/install-pipx.html

No repository access is required. Never put LeadDemon credentials, HubSpot tokens, or provider keys in a prompt, repository, or log.

## Install

```bash
python3 --version
pipx install https://leaddemon.io/downloads/leaddemon-0.2.0-py3-none-any.whl
```

## Authorize and verify

```bash
leaddemon login
leaddemon whoami --json
leaddemon workspace status --json
```

The login command opens a short-lived browser authorization page. Confirm that `whoami` shows the intended user and `workspace status` shows the intended HubSpot portal before sending business data.

## Install agent instructions

```bash
leaddemon agent init --target codex
# Claude Code:
leaddemon agent init --target claude
```

Optional Facebook business-research instructions:

```bash
leaddemon agent init --skill facebook-prospecting --target codex
```

## Plan and run free discovery

Download an example configuration from https://leaddemon.io/agents/run.example.json, customize the company profile and geography, then plan before starting.

```bash
leaddemon run plan --config run.json --json
leaddemon run start --config run.json --json
leaddemon run watch RUN_ID --json
leaddemon run download RUN_ID --output ./leaddemon-results --json
```

Paid providers require a reviewed plan and explicit human approval of that exact plan. Do not add `--approve-paid` unless the user has approved the displayed request count and cost.

## Dedupe an existing prospect file

Use this workflow instead of discovery when the user already has a CSV or XLSX prospect list:

```bash
leaddemon workspace status --json
leaddemon dedupe prospects.xlsx --sheet Prospects --dry-run --json
leaddemon dedupe prospects.xlsx --sheet Prospects \
  --against hubspot --output ./dedupe-results --json
```

Each submitted dedupe request pulls current non-archived companies from the connected HubSpot portal. It performs no discovery and no CRM writes. Treat `net_new.csv` as unmatched review data, not outreach clearance.

## Human-only actions

Use the handoff URLs returned by `leaddemon workspace status --json` for:

- HubSpot connect or disconnect
- Stripe subscription setup, management, or cancellation
- CLI authorization and session revocation
- Paid-provider policy or spend approval

## Recovery and safety

- If credentials are invalid or expired, run `leaddemon login` again.
- Prefer `--json` so agents can parse responses reliably.
- After a timeout, inspect `leaddemon run list --json` and the existing run before submitting anything again.
- For a lost dedupe response, reuse its printed `--request-id` only with the identical input.
- Run `leaddemon logout` to revoke the local CLI session.
- Set `LEADDEMON_CONFIG_DIR` only when credentials must live outside the default user config directory.