`                | Narrow by state (e.g., TX)                            |\n| `--zip `                  | Narrow by ZIP code                                    |\n| `--contact-audience ` | `owners`, `owners_and_family`, `renters`, `residents`, `none` |\n| `--fields `                | Comma-separated field IDs from `dm fields`            |\n\n#### `dm enrich email [email]`\n\nLook up a person by email address.\n\n```bash\ndm enrich email jane@example.com\ndm enrich email jane@example.com --include-properties\ndm enrich email -f emails.csv --fields estimated_household_income,estimated_value --json\n# CSV columns: email (or email_address)\n```\n\n| Option                 | Description                                    |\n| ---------------------- | ---------------------------------------------- |\n| `--include-properties` | Include associated properties                  |\n| `--fields `       | Comma-separated field IDs from `dm fields`     |\n\n#### `dm enrich phone [phone]`\n\nLook up a person by phone number.\n\n```bash\ndm enrich phone 5125551234\ndm enrich phone -f phones.csv --include-properties --fields estimated_value\n# CSV columns: phone (or phone_number)\n```\n\n| Option                 | Description                                |\n| ---------------------- | ------------------------------------------ |\n| `--include-properties` | Include associated properties              |\n| `--fields `       | Comma-separated field IDs from `dm fields` |\n\n#### `dm enrich name [name]`\n\nLook up people by name. Supports \"First Last\" or just \"Last\" format.\n\n```bash\ndm enrich name \"Jane Doe\" --state TX --estimate-cost\ndm enrich name \"Jane Doe\" --state TX --json --yes\ndm enrich name \"Doe\" --state TX --page 2\ndm enrich name \"Jane Doe\" --zip 78704 --include-properties\ndm enrich name \"Jane Doe\" --fields estimated_household_income,estimated_value\n```\n\n| Option                 | Description                   |\n| ---------------------- | ----------------------------- |\n| `--state `       | Narrow by state               |\n| `--zip `         | Narrow by ZIP code            |\n| `--include-properties` | Include associated properties |\n| `--fields `       | Field IDs from `dm fields`     |\n| `--estimate-cost`      | Preview count and credits     |\n| `--yes`                | Confirm approved credit spend |\n| `--page `           | Page number                   |\n| `--per-page `       | Results per page              |\n\n---\n\n### Comps Commands\n\n#### `dm comps [property_ids...]`\n\nFind comparable properties (sales comps) for one or more properties.\n\n```bash\n# Single property with defaults\ndm comps prop_12345\n\n# Multiple properties with options\ndm comps prop_12345 prop_67890 --radius 2 --timeframe 12months --limit 50\n\n# Full control via JSON body\ndm comps --body '{\n  \"property_ids\": [\"prop_12345\"],\n  \"location\": {\"type\": \"radius\", \"radius_miles\": 1.5},\n  \"criteria\": {\"timeframe\": \"6months\", \"sort_by\": \"match\", \"limit\": 25}\n}'\n```\n\n| Option                   | Description                                                |\n| ------------------------ | ---------------------------------------------------------- |\n| `--body `          | Request body as JSON string                                |\n| `-f, --file `      | Read request body from a JSON file                         |\n| `--radius `       | Search radius in miles (default: 1)                        |\n| `--timeframe `   | `3months`, `6months`, `12months`, `all` (default: 6months) |\n| `--limit `            | Max comps per property (default: 25, max: 100)             |\n| `--sort-by `      | `distance`, `price`, `date`, `match` (default: match)      |\n| `--sort-direction ` | `asc`, `desc` (default: desc)                              |\n| `--include-foreclosures` | Include foreclosure sales                                  |\n| `--json`                 | Output as JSON                                             |\n\nOutput includes subject property details, value estimation with confidence interval, summary statistics (average/median price, price per sqft), and a table of comparable properties.\n\n---\n\n### Lists Commands\n\n#### `dm lists search`\n\nSearch and list all saved lists.\n\n```bash\ndm lists search\ndm lists search --search \"Austin\" --source-type properties --sort newest\ndm lists search --page 2 --per-page 50 --json\n```\n\n| Option                 | Description                         |\n| ---------------------- | ----------------------------------- |\n| `--search `      | Search lists by name                |\n| `--source-type ` | `properties` or `people`            |\n| `--sort `       | `newest`, `oldest`, `name`, `count` |\n| `-p, --page `       | Page number                         |\n| `--per-page `       | Results per page                    |\n\n#### `dm lists create`\n\nCreate a new list.\n\n```bash\n# Empty list\ndm lists create --name \"Austin Leads\"\n\n# Pre-populated with record IDs (max 250)\ndm lists create --name \"Hot Leads\" --source-type properties --ids 123,456,789\n\n# With search filters for a list build\ndm lists create --name \"TX SFR\" -f search-filters.json\n```\n\n| Option                 | Description                                          |\n| ---------------------- | ---------------------------------------------------- |\n| `--name `        | List name (required)                                 |\n| `--source-type ` | `properties` or `people`                             |\n| `--ids `          | Comma-separated record IDs to pre-populate (max 250) |\n| `--body `        | Request body as JSON (filters/locations)             |\n| `-f, --file `    | Read request body from a JSON file                   |\n\n#### `dm lists get `\n\nGet details of a specific list including status, progress, and error state.\n\n```bash\ndm lists get list_abc123\n```\n\n#### `dm lists update `\n\nRename a list.\n\n```bash\ndm lists update list_abc123 --name \"New Name\"\n```\n\n#### `dm lists delete `\n\nDelete a list and all its items.\n\n```bash\ndm lists delete list_abc123\n```\n\n#### `dm lists build `\n\nBuild a list from search filters. This is an asynchronous operation -- poll with `dm lists get` for status.\n\n```bash\ndm lists build list_abc123 -f search-filters.json\n```\n\n#### `dm lists import `\n\nImport record IDs into an existing list.\n\n```bash\ndm lists import list_abc123 --ids 111,222,333 --source-type properties\ndm lists import list_abc123 -f import-payload.json\n```\n\n#### `dm lists items `\n\nList items in a list with pagination.\n\n```bash\ndm lists items list_abc123\ndm lists items list_abc123 --page 2 --per-page 100 --json\n```\n\n#### `dm lists add `\n\nAdd items to a list by ID.\n\n```bash\ndm lists add list_abc123 --ids 111,222,333\ndm lists add list_abc123 --ids 111,222 --id-type internal_property_id\n```\n\n| Option             | Description                                    |\n| ------------------ | ---------------------------------------------- |\n| `--ids `      | Comma-separated list of IDs to add (required)  |\n| `--id-type ` | `internal_property_id` or `internal_person_id` |\n\n#### `dm lists remove `\n\nRemove items from a list by ID.\n\n```bash\ndm lists remove list_abc123 --ids 111,222,333\n```\n\n#### `dm lists export `\n\nExport list items. Credits are charged per record.\n\n```bash\ndm lists export list_abc123\ndm lists export list_abc123 --fields \"full_address,estimated_value,owner_name\" --anchor property\n```\n\n| Option            | Description                              |\n| ----------------- | ---------------------------------------- |\n| `--fields `  | Comma-separated list of fields to export |\n| `--anchor ` | `property` or `person`                   |\n\n---\n\n### Filters Commands\n\n#### `dm filters`\n\nList available search filters with their types, operators, and groupings.\n\n```bash\ndm filters\ndm filters --source-type properties --search \"bed\"\ndm filters --group-id building_information --json\n```\n\n| Option                 | Description              |\n| ---------------------- | ------------------------ |\n| `--source-type ` | `properties` or `people` |\n| `--group-id `      | Filter by group ID       |\n| `--search `      | Search filters by name   |\n| `--page `           | Page number              |\n| `--per-page `       | Results per page         |\n\n---\n\n### Fields Commands\n\n#### `dm fields`\n\nList available data fields with filterable/sortable flags.\n\n```bash\ndm fields\ndm fields --source-type people --search \"phone\"\ndm fields --group-id contact_info --json\n```\n\n| Option                 | Description              |\n| ---------------------- | ------------------------ |\n| `--source-type ` | `properties` or `people` |\n| `--group-id `      | Filter by group ID       |\n| `--search `      | Search fields by name    |\n| `--page `           | Page number              |\n| `--per-page `       | Results per page         |\n\n---\n\n### Locations Commands\n\nSearch and retrieve DealMachine locations.\n\n```bash\ndm locations search -q \"Harris\" --type county --state TX --json\ndm locations get loc_city_48106 --json\n```\n\n`dm locations autocomplete` remains available as a deprecated alias for `dm addresses autocomplete`.\n\n---\n\n### Activity Commands\n\n#### `dm activity search`\n\nSearch past API activity with type filters and free-text search.\n\n```bash\ndm activity search -t search_properties enrich_address\ndm activity search -q \"Austin\" --page 2\ndm activity search --body '{\"types\": [\"search_properties\"], \"page\": 1}'\n```\n\n| Option                   | Description                                |\n| ------------------------ | ------------------------------------------ |\n| `--body `          | Request body as JSON string                |\n| `-f, --file `      | Read request body from a JSON file         |\n| `-t, --types ` | Filter by activity types (space-separated) |\n| `-q, --query `     | Free-text search across activity           |\n| `--page `             | Page number                                |\n| `--per-page `         | Results per page                           |\n\n#### `dm activity get `\n\nGet full details of a specific activity record, including the original request, result summary, and entity IDs (people and properties).\n\n```bash\ndm activity get act_abc123\ndm activity get act_abc123 --json\n```\n\n---\n\n### Addresses Commands\n\n#### `dm addresses autocomplete `\n\nReturn free, bounded address and normalized location suggestions.\n\n```bash\ndm addresses autocomplete \"1200 Barton Springs\" --state TX\ndm addresses autocomplete \"saint louis 63101\" --scope location --limit 5 --json\n```\n\n| Option                 | Description                                      |\n| ---------------------- | ------------------------------------------------ |\n| `--scope `      | `all`, `address`, or `location`, default `all`   |\n| `--state `       | Prefer a two-letter state abbreviation           |\n| `--limit `          | Maximum suggestions, default 5 and max 10        |\n| `--latitude `  | Latitude for nearby ranking, requires longitude  |\n| `--longitude ` | Longitude for nearby ranking, requires latitude  |\n| `--json`               | Output raw JSON response                          |\n\nAutocomplete does not request fields, perform enrichment, or consume data credits.\n\n#### `dm addresses validate [address]`\n\nValidate and standardize addresses via USPS.\n\n```bash\n# Single address\ndm addresses validate \"123 Main St, Austin, TX 78704\"\n\n# Batch via JSON\ndm addresses validate --body '{\"data\": [{\"full_address\": \"123 Main St, Austin TX\"}]}'\n\n# From file\ndm addresses validate -f addresses.json --json\n```\n\nOutput shows each address as valid, corrected (with corrections listed), or invalid (with reason).\n\n---\n\n### Dev Commands\n\nLocal development utilities that operate directly against the Docker MySQL container (`dealmachine-next-mysql`). These require the local database to be running (`npm run db:start` from the repo root).\n\n#### `dm dev license add `\n\nAdd a license to an API key in the local database.\n\n```bash\ndm dev license add key_abc123 --type state --code TX\ndm dev license add key_abc123 --type zip_code --code 78704\ndm dev license add key_abc123 --type unlimited\ndm dev license add key_abc123 --type county --code 48453 --expires 2026-12-31\n```\n\n| Option             | Description                                              |\n| ------------------ | -------------------------------------------------------- |\n| `--type `    | `state`, `county`, `zip_code`, or `unlimited` (required) |\n| `--code `    | Location code: state abbreviation, FIPS code, or ZIP     |\n| `--expires ` | Expiration date in ISO format                            |\n\n#### `dm dev license list [key_id]`\n\nList all licenses, optionally filtered by key ID.\n\n```bash\ndm dev license list\ndm dev license list key_abc123\n```\n\n#### `dm dev license remove `\n\nRemove a license by its numeric ID.\n\n```bash\ndm dev license remove 42\n```\n\n---\n\n## Global Options\n\nEvery command supports these flags:\n\n| Flag        | Description                                                |\n| ----------- | ---------------------------------------------------------- |\n| `--json`    | Output as machine-readable JSON (for scripting and piping) |\n| `--quiet`   | Suppress spinners and decorative output for agents/scripts |\n| `--help`    | Show usage information for any command                     |\n| `--version` | Show the CLI version                                       |\n\n---\n\n## Input Methods\n\nCommands that accept a request body support three input methods, checked in this order:\n\n1. **`--body `** -- Inline JSON string.\n2. **`-f, --file `** -- Read from a JSON file. Enrichment commands also accept `.csv` files for batch processing.\n3. **Stdin pipe** -- Read JSON from piped input (detected when stdin is not a TTY).\n\n```bash\n# Inline\ndm properties search --body '{\"locations\": [...]}'\n\n# File\ndm properties search -f query.json\n\n# Pipe\ncat query.json | dm properties search\n\n# CSV enrichment (enrich commands only)\ndm enrich address -f addresses.csv\n```\n\n### CSV Batch Enrichment\n\nThe `enrich` commands detect `.csv` files by extension and auto-parse them. Expected column names per command:\n\n| Command          | Required Columns        | Alternative Column Names             |\n| ---------------- | ----------------------- | ------------------------------------ |\n| `enrich address` | `full_address`          | or `street` + `city`, `state`, `zip` |\n| `enrich latlng`  | `latitude`, `longitude` | `lat`, `lng`/`lon`/`long`            |\n| `enrich apn`     | `apn`                   | `parcel_id`, `parcel_number`         |\n| `enrich email`   | `email`                 | `email_address`                      |\n| `enrich phone`   | `phone`                 | `phone_number`                       |\n\nBatches larger than 250 items are automatically chunked with progress spinners. If an export limit is reached mid-batch, the CLI stops and returns results collected so far.\n\n---\n\n## Project Structure\n\n```\npackages/cli/\n  scripts/\n    copy-agent-assets.mjs      # Bundles the Playbook Markdown into dist/agents\n  src/\n    index.ts                  # Program entrypoint -- registers all 17 command groups\n    lib/\n      config.ts               # Read/write ~/.dealmachine/config.json (mode 0600)\n      client.ts               # HTTP client wrapper (apiRequest, formatDate, getApiKey)\n      api.ts                  # Device auth flow client (requestDeviceCode, pollForToken, verifyCredentials)\n      output.ts               # Formatting helpers (printTable, printJson, printKeyValue, parseRequestBody)\n    commands/\n      agents.ts               # dm agents    -- agent guide and Playbook output\n      login.ts                # dm login     -- device auth + API key login\n      logout.ts               # dm logout    -- remove credentials\n      whoami.ts               # dm whoami    -- show/verify auth status\n      config.ts               # dm config    -- get, set, path\n      account.ts              # dm account   -- show account info\n      usage.ts                # dm usage     -- credit usage\n      properties.ts           # dm properties -- search, count, get, ids, export\n      people.ts               # dm people    -- search, count, get, ids, export\n      enrich.ts               # dm enrich    -- address, latlng, apn, email, phone, name\n      comps.ts                # dm comps     -- comparable properties\n      lists.ts                # dm lists     -- full CRUD + build, import, export\n      filters.ts              # dm filters   -- list available filters\n      fields.ts               # dm fields    -- list available fields\n      activity.ts             # dm activity  -- search, get\n      addresses.ts            # dm addresses -- validate\n      dev.ts                  # dm dev       -- local license management\n  dist/                       # Compiled output (ESM)\n  package.json\n  tsconfig.json\n```\n\n### Key Modules\n\n| Module          | Responsibility                                                                                                                                                                                                                                          |\n| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `lib/config.ts` | Manages `~/.dealmachine/config.json`. Enforces `0600` file permissions and `0700` directory permissions. Provides typed read/write/delete helpers.                                                                                                      |\n| `lib/client.ts` | Central HTTP client. Resolves the API base URL from env vars, config, or defaults. Attaches the `Authorization: Bearer` header and versioned `User-Agent`. Exits with a non-zero code on HTTP errors.                                                        |\n| `lib/api.ts`    | Device authorization flow implementation. Handles `POST /v1/auth/device/code` and `POST /v1/auth/device/token` with RFC 8628-compliant polling and error mapping. Also provides `verifyCredentials` for key validation.                                 |\n| `lib/output.ts` | All output formatting: `printTable` (auto-width columns), `printJson`, `printKeyValue`, `printPagination`, `printCredits`, `printTotals`, `printWarning`, `printHeader`. Also exports `parseRequestBody` which handles `--body`, `-f`, and stdin input. |\n\n---\n\n## Building\n\n```bash\nnpm run build      # Compile TypeScript and bundle agent Playbook assets to dist/\nnpm run dev        # Watch mode (tsc --watch)\nnpm run eval:cold-start:local      # Verify a clean local install and routing contract\nnpm run eval:cold-start:published  # Verify the latest public npm artifact\nnpm run eval:cold-start:deployed   # Verify deployed documentation and skill assets\n```\n\nThe published and deployed checks are release gates. They are expected to fail before a release is\npublished or the documentation deployment reaches production. The scenario catalog is stored in\n`evals/claude-code-name-lookup.json` so the same prompt variants remain visible and reviewable.\n\n### Standalone Binary\n\nThe compiled `dist/index.js` includes a `#!/usr/bin/env node` shebang and is declared in `package.json` under `bin.dm`. When installed globally via npm, it becomes available as `dm` on the PATH.\n\nFor distribution as a standalone binary without npm:\n\n```bash\n# Build\ncd packages/cli\nnpm run build\n\n# The entire dist/ directory is the distributable artifact\n# dist/index.js is the entrypoint (requires Node.js >= 18 on the target machine)\n```\n\nThe `files` array in `package.json` ensures only `dist/` is included in the published package.\n\n### TypeScript Configuration\n\n- Target: ES2022\n- Module: NodeNext (ESM)\n- Strict mode enabled\n- Outputs declarations, declaration maps, and source maps\n- No project references (standalone compilation)\n\n---\n\n## Adding New Commands\n\n### Step 1: Create the command file\n\nCreate `src/commands/mycommand.ts`:\n\n```typescript\n/**\n * MyCommand -- description of what this command does\n */\n\nimport chalk from 'chalk';\nimport ora from 'ora';\nimport { apiRequest } from '../lib/client.js';\nimport { printJson, printHeader, printKeyValue } from '../lib/output.js';\n\ninterface MyResponse {\n  data: { id: string; name: string };\n}\n\nexport async function myCommand(options: { json?: boolean }): Promise {\n  const spinner = ora('Doing something...').start();\n  const data = await apiRequest('/my-endpoint');\n  spinner.stop();\n\n  if (options.json) {\n    printJson(data);\n    return;\n  }\n\n  printHeader('My Command');\n  printKeyValue({\n    ID: data.data.id,\n    Name: data.data.name,\n  });\n  console.log();\n}\n```\n\n### Step 2: Register in index.ts\n\nImport and wire up the command in `src/index.ts`:\n\n```typescript\nimport { myCommand } from './commands/mycommand.js';\n\n// Top-level command\nprogram\n  .command('mycommand')\n  .description('Description shown in --help')\n  .option('--json', 'Output as JSON')\n  .action(async (options) => {\n    await myCommand(options);\n  });\n\n// Or as a subcommand group\nconst myGroup = program.command('mygroup').description('Group description');\n\nmyGroup\n  .command('sub1')\n  .description('Subcommand description')\n  .action(async (options) => {\n    await mySub1(options);\n  });\n```\n\n### Step 3: Build and test\n\n```bash\nnpm run build\nnode dist/index.js mycommand --json\n```\n\n### Conventions\n\n- One file per command group in `src/commands/`.\n- Always support `--json` for machine-readable output.\n- Use `ora` for spinners during API calls.\n- Use `chalk` for colored terminal output.\n- Use `apiRequest` from `lib/client.ts` for all API calls -- it handles auth, errors, and exits.\n- Use `parseRequestBody` from `lib/output.ts` when the command accepts `--body`, `-f`, or stdin input.\n- Use `printHeader`, `printTable`, `printKeyValue`, `printCredits`, `printPagination` for consistent output formatting.\n- All imports must use the `.js` extension (ESM requirement with NodeNext resolution).\n\n---\n\n## Dependencies\n\n### Runtime\n\n| Package     | Version | Purpose                                                                |\n| ----------- | ------- | ---------------------------------------------------------------------- |\n| `commander` | ^12.1.0 | CLI framework -- command registration, option parsing, help generation |\n| `chalk`     | ^5.3.0  | Terminal string styling (colors, bold, dim)                            |\n| `ora`       | ^8.1.0  | Spinner animations for async operations                                |\n| `open`      | ^10.1.0 | Opens the browser for the device auth flow                             |\n\n### Dev\n\n| Package       | Version | Purpose                  |\n| ------------- | ------- | ------------------------ |\n| `typescript`  | ^5.6.3  | TypeScript compiler      |\n| `@types/node` | ^22.0.0 | Node.js type definitions |\n\n### Internal Package Dependencies\n\n**None.** This package is a fully standalone binary with zero `@dealmachine/*` dependencies. It communicates exclusively through the public REST API.\n\n### Used By\n\nThe **Playbook** at `packages/playbooks/playbook/` uses `dm` commands to execute property intelligence workflows. The CLI is the primary interface through which the Playbook interacts with DealMachine data. Agents can load the bundled Playbook directly with `dm agents playbook`.\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays","iconType","image","upstream",{"_114":115,"_116":117,"_118":119,"_120":121,"_122":123,"_124":125},"requiredSecrets",[],"tags",[100,101,102,103,19,104,105,106,107,108,109,110,111,112,113],"assets",[],"stats",{"_98":59,"_99":59},"ratingAvg","reviewCount","agent-skills","cli","company-search","contact-data","enrichment","gemini-cli-extension","lead-generation","marketing","people-search","property-data","property-intelligence","prospecting","real-estate","sales-intelligence","topics",[100,126,101,102,103,19,104,105,106,107,127,128,108,109,110,111,112,113],"license","MIT","language","TypeScript","registryName","io.github.DealMachine/dealmachine","homepage","https://api.docs.dealmachine.com","packages",[],"api","mcp","mcp-server","ENV",{"_131":132,"_133":134,"_135":136},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]