DealMachine

DealMachine CLI

维护者：Agent 指引、开发、当前命令参考和 npm 版本发布。

DealMachine CLI (dm)——在命令行中获取房产情报。

一个独立的 Commander.js CLI，可与 DealMachine REST API 通信。提供用于身份验证、房产和人员调查、数据丰富、列表、潜在客户、标签、webhook、邮件和开发者实用功能的命令。通过 tsc 编译为 ESM JavaScript。

此软件包没有 @dealmachine/* 依赖——它是一个独立的二进制程序，仅通过公开 API 通信。

---

AI Agent 集成

此代码库也是 DealMachine MCP 服务和 DealMachine 技能的公开分发软件包。

• 托管 MCP 服务：https://mcp.dealmachine.com
• API 文档：https://api.docs.dealmachine.com
• 账户和 API 密钥：https://dealmachine.com/settings/developer
• 隐私政策：https://dealmachine.com/privacy-policy
• 服务条款：https://dealmachine.com/terms-of-service
• 支持：[email protected]

MCP 服务支持 ChatGPT、Claude、Cursor、Codex 和其他兼容客户端使用 OAuth 2.1。它也可在支持 bearer token 配置的开发者客户端中使用 DealMachine API 密钥。

插件软件包包含：

• 用于房产、人员、数据丰富、可比销售和账户工具的托管 MCP 连接
• 一项注重额度的技能，可发现筛选条件和字段、先计数，并在执行大量付费操作前进行确认
• 适用于兼容客户端的可移植 Agent Plugins 软件包
• OpenAI、Claude、Cursor、GitHub Copilot 和 Gemini 的清单
• server.json 中的官方 MCP Registry 元数据

可移植软件包遵循 Agent Plugins 1.0.0：

dealmachine-cli/
├── plugin.json
├── mcp.json
└── skills/
    └── dealmachine/
        ├── SKILL.md
        ├── REFERENCE.md
        └── SETUP.md

兼容客户端会从 skills/dealmachine/ 发现 DealMachine 技能，并连接到 mcp.json 中声明的托管 Streamable HTTP MCP 服务。代码库中保留了特定于客户端的清单，以确保兼容性、提供市场元数据和更丰富的展示效果。

请求示例：

• “查找 Austin 的高净值、非自住业主房产，并先估算额度成本。”
• “查询此房产的业主，并查找可用的联系数据。”
• “查找此房产的可比销售。”
• “调查符合这些条件的人员，以创建有针对性的潜在客户名单。”

直接安装技能：

npx skills add DealMachine/dealmachine-cli

---

目录

• AI Agent 集成
• 安装
• 身份验证
• 配置
• 命令
  • Agents -- agents、agents guide、agents playbook、agents install、agents permissions
  • Auth -- login、logout、whoami
  • Config -- config get、config set、config path
  • 账户 -- account
  • 用量 -- usage
  • 房产 -- search、count、get、ids、export
  • 人员 -- search、count、get、ids、export
  • 数据丰富 -- address、latlng、apn、email、phone、name
  • 可比房产 -- 可比房产分析
  • 列表 -- search、create、get、update、delete、build、import、items、add、remove、export
  • 筛选条件 -- 列出可用的搜索筛选条件
  • 字段 -- 列出可用的数据字段
  • 活动 -- search、get
  • 地址 -- autocomplete、validate
  • 开发者 -- license add、license list、license remove
• 全局选项
• 输入方式
• 项目结构
• 构建
• 添加新命令
• 依赖项

---

安装

从 npm 全局安装

npm install -g dealmachine
dm login

规范实现包是 @dealmachine/cli。dealmachine 包是简短的安装别名，并提供相同的 dm 命令。

从源码安装

cd dealmachine-cli
npm run build
node dist/index.js whoami

链接以供本地开发

cd dealmachine-cli
npm link
dm --version

二进制入口为 dist/index.js，在 package.json 的 bin.dm 中声明。需要 Node.js >= 18。

---

身份验证

CLI 支持两种身份验证方式。

设备身份验证流程（RFC 8628）

默认的 dm login 命令使用 OAuth 2.0 设备授权许可（RFC 8628）。这是交互式使用的推荐流程：

dm login

1. CLI 使用客户端 ID dealmachine-next-cli 和你机器的主机名，向 POST /v1/auth/device/code 请求设备代码。
2. 屏幕会显示验证 URL 和用户代码。浏览器会自动打开（除非指定 --no-browser）。
3. 在浏览器中输入用户代码，以授权设备。
4. CLI 按照服务器指定的时间间隔轮询 POST /v1/auth/device/token。
5. 成功后，API 密钥、密钥 ID 和组织详情会保存到 ~/.dealmachine/config.json。

轮询会处理 RFC 8628 的所有响应：authorization_pending、slow_down（延迟 5 秒后重试）、access_denied 和 expired_token。

# Skip auto-opening the browser
dm login --no-browser

# Target a specific environment
dm login --env local
dm login --env staging

直接使用 API 密钥登录

对于 CI 流水线、脚本或本地开发，可直接传入 API 密钥：

dm login --key dm_sk_live_abc123...

密钥会在保存前通过 GET /v1/account 验证。如果验证失败，CLI 会以非零代码退出。

如果你还没有 API 密钥，请使用 dm signup <email> --login 或 dm login。免费账户可以在付费前统计匹配项并估算费用。公开方案结账仅接受共享方案目录中的自助式 Basic 和 Pro 价格，且每月数据积分上限为 60,000。

切换环境

如果你已经登录，可以切换目标 API 环境，而无需退出登录：

dm login --env local       # Switch to http://localhost:3001/v1
dm login --env staging     # Switch to https://api-staging.v2.dealmachine.com/v1
dm login --env production  # Switch to https://api.v2.dealmachine.com/v1

退出登录

dm logout

移除 ~/.dealmachine/config.json 配置文件。

---

配置

凭据保存在 ~/.dealmachine/config.json，文件权限为 0600（仅所有者可读写）。配置目录 ~/.dealmachine/ 创建时的权限为 0700。

配置文件架构

{
  "apiKey": "dm_sk_live_...",
  "keyId": "key_abc123",
  "organizationId": 42,
  "organizationName": "Acme Corp",
  "organizationSlug": "acme-corp",
  "apiEnvironment": "production"
}

环境变量

CLI 按以下优先级检查这些环境变量，以解析 API URL：

变量	用途	示例
DM_API_URL / DEALMACHINE_API_URL	直接覆盖 URL	http://localhost:3001/v1
DM_ENV / DEALMACHINE_ENVIRONMENT	环境名称	local、staging 或 production

如果均未设置，CLI 会回退到配置文件中的 apiEnvironment 字段，然后默认使用 production。

API 环境

环境	URL
local	http://localhost:3001/v1
staging	https://api-staging.v2.dealmachine.com/v1
production	https://api.v2.dealmachine.com/v1

---

命令

Agent 命令

dm agents

为使用 CLI 的 Agent 输出简明指南。如果 Agent 可以使用 dm，但尚未加载 DealMachine Playbook，这是建议优先运行的命令。

dm agents
dm agents --json

该指南会指导 Agent 使用 --json 和 --quiet、验证身份验证、在搜索前获取实时筛选条件和字段、在消耗积分的操作前先统计数量，并在获取记录或导出之前确认预期的积分用量。

dm agents guide

显式输出相同的简明 Agent 指南。

dm agents guide
dm agents guide --json

dm agents playbook

打印随附的 DealMachine Playbook Markdown。Agent 应在将有关房产、人员、联系人、数据增强、列表、导出、可比房产或额度用量的自然语言请求转换为 CLI 命令之前加载此文件。

dm agents playbook
dm agents playbook --json
dm agents skill        # alias

公开 CLI 源代码将随附的 Playbook 保存在 playbook/PLAYBOOK.md。构建过程会将选定的源文件写入 dist/agents/dealmachine-playbook.md，因此该命令在已发布的 CLI 软件包和本地源代码检出中均可使用。

dm agents install claude-code

将 Playbook 安装为原生 Claude Code 技能。默认使用个人范围。项目范围会安装到当前仓库中。

dm agents install claude-code
dm agents install claude-code --project

dm agents permissions

打印用于免费发现和计数命令的精简 Claude Code 允许列表。付费和修改类命令不会预先获准。

dm agents permissions
dm agents permissions --json

---

身份验证命令

dm signup

创建公开 API 账户并获取 API 密钥。使用 --login 时，凭据会保存在本地且不会出现在输出中（包括 JSON）；Agent 请使用此形式：

dm signup [email protected] --first-name Ada --last-name Lovelace --phone-number +15551234567
dm signup [email protected] --login

dm plans

列出当前可自助使用的套餐、包含的额度、功能和免费 API 访问权限。已连接的客户会看到其工作区价格：

dm plans
dm plans --json

dm checkout

使用 dm plans 中当前的价格 ID 预览周期性条款。客户批准确切的价格、计费间隔和数量后，添加 --yes 以创建 Stripe 结账链接：

dm checkout --price-id price_xxx_monthly --quantity 1 --json
# Only after approval:
dm checkout --price-id price_xxx_monthly --quantity 1 --yes --json

付款通过 Stripe 完成。创建结账不会激活套餐；付款后，请检查 dm account --json 和 dm usage，再重试数据增强。计数不会发放额度。免费操作仍需身份验证，并受权限和速率限制约束。

dm login

使用你的 DealMachine 账户进行身份验证。

dm login                            # Device auth flow (opens browser)
dm login --no-browser               # Device auth, manual code entry
dm login --key dm_sk_live_abc123    # Direct API key
dm login --env local                # Target local API

选项	说明
--no-browser	不自动打开浏览器
--key <api-key>	直接使用 API 密钥登录（跳过浏览器）
--env <environment>	API 环境：local、staging 或 production

dm logout

删除已存储的凭据。

dm logout

dm whoami

显示当前身份验证状态。

dm whoami               # Show stored credentials
dm whoami --verify      # Verify credentials against the API

选项	说明
--verify	使用 API 验证凭据

---

配置命令

dm config get [key]

获取配置值；若未提供键，则显示所有值。

dm config get                   # Show all config values
dm config get apiEnvironment    # Show specific value
dm config get apiKey            # Shows truncated key (first 20 chars)

可用键：organizationName、organizationSlug、organizationId、apiEnvironment、keyId、apiKey。

dm config set <key> <value>

设置配置值。只有 apiEnvironment 可编辑。

dm config set apiEnvironment local
dm config set apiEnvironment staging
dm config set apiEnvironment production

dm config path

打印配置文件的绝对路径。

dm config path
# /Users/you/.dealmachine/config.json

---

账户命令

dm account

显示账户信息，包括组织名称、ID、创建日期和身份验证类型。

dm account

输出：

Account
────────────────────────────────────────
Organization:  Acme Corp
Org ID:        42
Created:       Jan 15, 2025
Auth Type:     api_key

---

用量命令

dm usage

显示当前计费周期的额度用量。

dm usage           # Human-readable table
dm usage --json    # Machine-readable JSON

输出：

Credit Usage
──────────────────────────────────────────────────
  Plan:         Pro
  Cycle:        Mar 1, 2026 : Mar 31, 2026

  Credits:      4,200 / 10,000 (42%)
  Remaining:    5,800

  Breakdown:
    Properties: 3,100
    People:     1,100

---

房产命令

dm properties search

按筛选条件和地点搜索房产。

# Inline JSON body
dm properties search --body '{
  "locations": [{"type": "zip_code", "code": "78704"}],
  "filters": [{"filter_id": "property_type", "operator": "is_any_of", "value": ["single_family"]}]
}'

# From a file
dm properties search -f search.json

# Pipe from stdin
cat search.json | dm properties search

# Machine-readable output
dm properties search -f search.json --json              # Free estimate for scripts and agents
dm properties search -f search.json --json --yes        # Run after approval

# Explicit free estimate
dm properties search -f search.json --estimate-cost

# Query Builder protocol filters
dm properties search --include-lists 123,456 --exclude-previously-exported --body '{"locations":[]}'

选项	描述
--body <json>	以 JSON 字符串形式提供请求正文
-f, --file <path>	从 JSON 文件读取请求正文
--include-lists <ids>	要包含的列表 ID，以逗号分隔
--exclude-lists <ids>	要排除的列表 ID，以逗号分隔
--exclude-previously-exported	排除组织已导出的记录
--bigquery-data-environment <n>	Query Builder 数据环境（1 生产环境、2 暂存环境、3 开发环境）
--estimate-cost	预览数量和积分费用，不消耗积分
--yes	在非交互式执行中确认已批准的积分支出
--json	以 JSON 格式输出

dm properties count

统计符合筛选条件的房产数量，不消耗积分。

dm properties count --body '{"locations": [{"type": "state", "code": "TX"}]}'
dm properties count -f filters.json --json

dm properties get <id>

根据 DealMachine ID 获取单个房产。

dm properties get prop_12345
dm properties get prop_12345 --contact-audience owners_and_family
dm properties get prop_12345 --contact-audience none
dm properties get prop_12345 --fields estimated_value,equity
dm properties get prop_12345 --json

选项	描述
--contact-audience <audience>	owners、owners_and_family、renters、residents、all、none
--fields <csv>	从 dm fields 获取的房产字段 ID，以逗号分隔
--json	以 JSON 格式输出

房产查询默认使用 owners。如果只需要房产数据，请使用 --contact-audience none。这样会省略联系人信息，并避免消耗人员积分。

dm properties ids [ids...]

通过单个批量请求，根据多个 ID 获取房产。

# Positional arguments
dm properties ids prop_111 prop_222 prop_333

# Via JSON body
dm properties ids --body '{"ids": ["prop_111", "prop_222"]}'

# From file
dm properties ids -f ids.json --contact-audience owners
dm properties ids -f ids.json --contact-audience none

选项	描述
--body <json>	以 JSON 字符串形式提供请求正文
-f, --file <path>	从 JSON 文件读取请求正文
--contact-audience <audience>	包含联系人：owners、owners_and_family、renters、residents、all、none
--json	以 JSON 格式输出

dm properties export

将属性导出为 CSV（最多 1,000,000 条记录）。返回签名下载 URL。

dm properties export -f search.json
dm properties export -f search.json --require-phone --scrub-dnc
dm properties export --body '{"locations": [...]}' --mobile-only --json

选项	说明
--body <json>	将请求正文作为 JSON 字符串传入
-f, --file <path>	从 JSON 文件读取请求正文
--require-phone	仅包含联系人有电话号码的记录
--require-email	仅包含联系人有电子邮件地址的记录
--mobile-only	仅包含无线电话号码
--landline-only	仅包含固定电话号码
--scrub-dnc	排除列入勿致电登记名单的联系人
--json	以 JSON 格式输出

---

人员命令

dm people search

按筛选条件和地点搜索人员。

dm people search --body '{
  "locations": [{"type": "zip_code", "code": "78704"}],
  "filters": [{"filter_id": "age", "operator": "between", "value": [30, 50]}]
}'
dm people search -f people-search.json --json
dm people search -f people-search.json --estimate-cost
dm people search -f people-search.json --json --yes
dm people search --include-lists 123 --exclude-lists 456 --exclude-previously-exported --body '{"locations":[]}'

非交互式人员搜索会返回免费估算，除非提供 --yes。按姓名查找特定人员时，请使用 dm enrich name，而非人员搜索。

dm people count

统计符合筛选条件的人员数量，不消耗额度。

dm people count -f filters.json

dm people get <id>

通过 DealMachine ID 获取单个人员的信息。

dm people get per_12345
dm people get per_12345 --include-properties --property-limit 20
dm people get per_12345 --fields estimated_household_income,estimated_value
dm people get per_12345 --json

选项	说明
--include-properties	包含关联属性
--property-limit <n>	返回的关联属性上限，范围为 1 到 100
--fields <csv>	来自 dm fields 的逗号分隔字段 ID
--json	以 JSON 格式输出

dm people ids [ids...]

通过单个批量请求，按 ID 获取多个人员的信息。

dm people ids per_111 per_222 per_333
dm people ids --body '{"ids": ["per_111", "per_222"]}' --include-properties --property-limit 20
dm people ids per_111 per_222 --fields estimated_household_income,estimated_value

选项	说明
--include-properties	包含关联属性
--property-limit <n>	每个人员返回的关联属性上限，最多为 100
--fields <csv>	来自 dm fields 的逗号分隔字段 ID

dm people export

将人员导出为 CSV（最多 1,000,000 条记录）。返回签名下载 URL。

dm people export -f search.json --require-email
dm people export -f search.json --mobile-only --scrub-dnc --json

联系人筛选选项与 dm properties export 相同。

---

丰富信息命令

所有丰富信息命令都支持三种输入模式：使用位置参数进行单项查找，使用 --body/-f 传入 JSON 负载，以及使用 -f 指定 .csv 文件以从 CSV 批量丰富信息。超过 250 项的批次会自动分块。每个丰富信息命令都接受 --fields <csv>，并将所选字段 ID 发送至 API。电子邮件、电话和姓名匹配也会附带免费的 property_count；如需获取属性记录本身，请使用 --include-properties。

dm enrich address [address]

按街道地址查询房产。

# Single address
dm enrich address "123 Main St, Austin, TX 78704"
dm enrich address "123 Main St, Austin, TX 78704" --contact-audience none
dm enrich address "123 Main St, Austin, TX 78704" --fields estimated_value,equity

# Batch from JSON
dm enrich address --body '{"data": [{"full_address": "123 Main St, Austin, TX"}]}'

# Batch from CSV (auto-detected by .csv extension)
dm enrich address -f addresses.csv --contact-audience owners

# CSV columns: full_address (or street, city, state, zip)

选项	说明
--body <json>	JSON 字符串形式的请求正文
-f, --file <path>	从 JSON 或 CSV 文件读取
--contact-audience <audience>	owners、owners_and_family、renters、residents、none
--fields <csv>	来自 dm fields 的逗号分隔字段 ID
--json	以 JSON 格式输出

如果只需要房产信息，请使用 --contact-audience none。响应中不会包含联系人，也不会消耗人员额度。

dm enrich latlng [coords]

按纬度/经度坐标查询房产。

dm enrich latlng 30.25,-97.75
dm enrich latlng -f coordinates.csv --fields estimated_value,equity --contact-audience none
# CSV columns: latitude, longitude (or lat, lng/lon/long)

dm enrich apn [apn]

按评估员地块编号查询房产。使用 --state 或 --zip 缩小结果范围。

dm enrich apn "0123-456-789" --state TX
dm enrich apn -f parcels.csv --zip 78704 --fields estimated_value,equity
# CSV columns: apn (or parcel_id, parcel_number)

选项	说明
--state <code>	按州缩小范围（例如 TX）
--zip <code>	按 ZIP 邮政编码缩小范围
--contact-audience <audience>	owners、owners_and_family、renters、residents、none
--fields <csv>	来自 dm fields 的逗号分隔字段 ID

dm enrich email [email]

按电子邮件地址查询人员。

dm enrich email [email protected]
dm enrich email [email protected] --include-properties
dm enrich email -f emails.csv --fields estimated_household_income,estimated_value --json
# CSV columns: email (or email_address)

选项	说明
--include-properties	包含关联房产
--fields <csv>	来自 dm fields 的逗号分隔字段 ID

dm enrich phone [phone]

按电话号码查询人员。

dm enrich phone 5125551234
dm enrich phone -f phones.csv --include-properties --fields estimated_value
# CSV columns: phone (or phone_number)

选项	说明
--include-properties	包含关联房产
--fields <csv>	来自 dm fields 的逗号分隔字段 ID

dm enrich name [name]

按姓名查询人员。支持“名 姓”或仅“姓”的格式。

dm enrich name "Jane Doe" --state TX --estimate-cost
dm enrich name "Jane Doe" --state TX --json --yes
dm enrich name "Doe" --state TX --page 2
dm enrich name "Jane Doe" --zip 78704 --include-properties
dm enrich name "Jane Doe" --fields estimated_household_income,estimated_value

选项	说明
--state <code>	按州缩小范围
--zip <code>	按 ZIP 邮政编码缩小范围
--include-properties	包含关联房产
--fields <csv>	来自 dm fields 的字段 ID
--estimate-cost	预览数量和额度
--yes	确认已批准的额度支出
--page <n>	页码
--per-page <n>	每页结果数

---

可比项命令

dm comps [property_ids...]

查找一个或多个房产的可比房产（销售可比数据）。

# Single property with defaults
dm comps prop_12345

# Multiple properties with options
dm comps prop_12345 prop_67890 --radius 2 --timeframe 12months --limit 50

# Full control via JSON body
dm comps --body '{
  "property_ids": ["prop_12345"],
  "location": {"type": "radius", "radius_miles": 1.5},
  "criteria": {"timeframe": "6months", "sort_by": "match", "limit": 25}
}'

Option	Description
--body <json>	JSON 字符串格式的请求正文
-f, --file <path>	从 JSON 文件读取请求正文
--radius <miles>	搜索半径（英里，默认值：1）
--timeframe <period>	3months、6months、12months、all（默认值：6months）
--limit <n>	每个房产的可比数据上限（默认值：25，最大值：100）
--sort-by <field>	distance、price、date、match（默认值：match）
--sort-direction <dir>	asc、desc（默认值：desc）
--include-foreclosures	包含止赎销售
--json	以 JSON 格式输出

输出包含目标房产详情、带置信区间的价值估算、汇总统计信息（平均／中位价格、每平方英尺价格）以及可比房产表格。

---

列表命令

dm lists search

搜索并列出所有已保存的列表。

dm lists search
dm lists search --search "Austin" --source-type properties --sort newest
dm lists search --page 2 --per-page 50 --json

Option	Description
--search <term>	按名称搜索列表
--source-type <type>	properties 或 people
--sort <order>	newest、oldest、name、count
-p, --page <n>	页码
--per-page <n>	每页结果数

dm lists create

创建新列表。

# Empty list
dm lists create --name "Austin Leads"

# Pre-populated with record IDs (max 250)
dm lists create --name "Hot Leads" --source-type properties --ids 123,456,789

# With search filters for a list build
dm lists create --name "TX SFR" -f search-filters.json

Option	Description
--name <name>	列表名称（必填）
--source-type <type>	properties 或 people
--ids <csv>	以逗号分隔的记录 ID，用于预先填充（最多 250 个）
--body <json>	JSON 格式的请求正文（筛选条件／位置）
-f, --file <path>	从 JSON 文件读取请求正文

dm lists get <id>

获取指定列表的详情，包括状态、进度和错误状态。

dm lists get list_abc123

dm lists update <id>

重命名列表。

dm lists update list_abc123 --name "New Name"

dm lists delete <id>

删除列表及其所有项目。

dm lists delete list_abc123

dm lists build <id>

根据搜索筛选条件构建列表。这是异步操作——使用 dm lists get 轮询状态。

dm lists build list_abc123 -f search-filters.json

dm lists import <id>

将记录 ID 导入现有列表。

dm lists import list_abc123 --ids 111,222,333 --source-type properties
dm lists import list_abc123 -f import-payload.json

dm lists items <id>

分页列出列表中的项目。

dm lists items list_abc123
dm lists items list_abc123 --page 2 --per-page 100 --json

dm lists add <id>

按 ID 将项目添加到列表。

dm lists add list_abc123 --ids 111,222,333
dm lists add list_abc123 --ids 111,222 --id-type internal_property_id

Option	Description
--ids <csv>	以逗号分隔的待添加 ID 列表（必填）
--id-type <type>	internal_property_id 或 internal_person_id

dm lists remove <id>

按 ID 从列表中移除项目。

dm lists remove list_abc123 --ids 111,222,333

dm lists export <id>

导出列表项目。每条记录都会扣除积分。

dm lists export list_abc123
dm lists export list_abc123 --fields "full_address,estimated_value,owner_name" --anchor property

Option	Description
--fields <csv>	以逗号分隔的待导出字段列表
--anchor <type>	property 或 person

---

筛选命令

dm filters

列出可用的搜索筛选条件及其类型、运算符和分组。

dm filters
dm filters --source-type properties --search "bed"
dm filters --group-id building_information --json

选项	描述
--source-type <type>	properties 或 people
--group-id <id>	按组 ID 筛选
--search <term>	按名称搜索筛选条件
--page <n>	页码
--per-page <n>	每页结果数

---

Fields Commands

dm fields

列出可用的数据字段及其可筛选／可排序标记。

dm fields
dm fields --source-type people --search "phone"
dm fields --group-id contact_info --json

选项	描述
--source-type <type>	properties 或 people
--group-id <id>	按组 ID 筛选
--search <term>	按名称搜索字段
--page <n>	页码
--per-page <n>	每页结果数

---

Locations Commands

搜索并检索 DealMachine 位置。

dm locations search -q "Harris" --type county --state TX --json
dm locations get loc_city_48106 --json

dm locations autocomplete 仍可作为已弃用的 dm addresses autocomplete 别名使用。

---

Activity Commands

dm activity search

按类型筛选条件和自由文本搜索，搜索过去的 API 活动。

dm activity search -t search_properties enrich_address
dm activity search -q "Austin" --page 2
dm activity search --body '{"types": ["search_properties"], "page": 1}'

选项	描述
--body <json>	以 JSON 字符串形式提供请求正文
-f, --file <path>	从 JSON 文件读取请求正文
-t, --types <types...>	按活动类型筛选（以空格分隔）
-q, --query <text>	在活动中进行自由文本搜索
--page <n>	页码
--per-page <n>	每页结果数

dm activity get <id>

获取特定活动记录的完整详情，包括原始请求、结果摘要以及实体 ID（人员和房产）。

dm activity get act_abc123
dm activity get act_abc123 --json

---

Addresses Commands

dm addresses autocomplete <query>

返回免费的、有数量限制的地址及标准化位置建议。

dm addresses autocomplete "1200 Barton Springs" --state TX
dm addresses autocomplete "saint louis 63101" --scope location --limit 5 --json

选项	描述
--scope <scope>	all、address 或 location，默认值为 all
--state <code>	优先使用两个字母的州缩写
--limit <n>	建议结果的最大数量，默认值为 5，最大值为 10
--latitude <number>	用于附近结果排序的纬度；需要提供经度
--longitude <number>	用于附近结果排序的经度；需要提供纬度
--json	输出原始 JSON 响应

自动补全不会请求字段、执行数据增强或消耗数据额度。

dm addresses validate [address]

通过 USPS 验证并规范化地址。

# Single address
dm addresses validate "123 Main St, Austin, TX 78704"

# Batch via JSON
dm addresses validate --body '{"data": [{"full_address": "123 Main St, Austin TX"}]}'

# From file
dm addresses validate -f addresses.json --json

输出会将每个地址标记为有效、已更正（并列出更正内容）或无效（并说明原因）。

---

Dev Commands

可直接对 Docker MySQL 容器（dealmachine-next-mysql）进行操作的本地开发实用工具。使用这些工具需要本地数据库正在运行（在仓库根目录执行 npm run db:start）。

dm dev license add <key_id>

向本地数据库中的 API 密钥添加许可证。

dm dev license add key_abc123 --type state --code TX
dm dev license add key_abc123 --type zip_code --code 78704
dm dev license add key_abc123 --type unlimited
dm dev license add key_abc123 --type county --code 48453 --expires 2026-12-31

选项	描述
--type <type>	state、county、zip_code 或 unlimited（必填）
--code <code>	位置代码：州缩写、FIPS 代码或 ZIP
--expires <date>	ISO 格式的到期日期

dm dev license list [key_id]

列出所有许可证，可选择按密钥 ID 筛选。

dm dev license list
dm dev license list key_abc123

dm dev license remove <license_id>

根据数字 ID 移除许可证。

dm dev license remove 42

---

全局选项

每条命令都支持以下标志：

标志	说明
--json	输出机器可读的 JSON（用于脚本和管道）
--quiet	为 Agent/脚本隐藏加载动画和装饰性输出
--help	显示任意命令的用法信息
--version	显示 CLI 版本

---

输入方式

接受请求正文的命令支持三种输入方式，并按以下顺序检查：

1. --body <json> —— 内联 JSON 字符串。
2. -f, --file <path> —— 从 JSON 文件读取。数据增强命令也接受 .csv 文件进行批量处理。
3. 标准输入管道 —— 从管道输入读取 JSON（当标准输入不是 TTY 时检测）。

# Inline
dm properties search --body '{"locations": [...]}'

# File
dm properties search -f query.json

# Pipe
cat query.json | dm properties search

# CSV enrichment (enrich commands only)
dm enrich address -f addresses.csv

CSV 批量数据增强

enrich 命令会根据扩展名检测 .csv 文件并自动解析。各命令所需的列名如下：

命令	必需列	可选列名
enrich address	full_address	或 street + city、state、zip
enrich latlng	latitude、longitude	lat、lng/lon/long
enrich apn	apn	parcel_id、parcel_number
enrich email	email	email_address
enrich phone	phone	phone_number

超过 250 项的批次会自动分块处理，并显示进度动画。如果批次处理中途达到导出限制，CLI 会停止并返回已收集的结果。

---

项目结构

dealmachine-cli/
  scripts/
    copy-agent-assets.mjs      # Bundles the Playbook Markdown into dist/agents
  src/
    index.ts                  # Program entrypoint -- registers all 17 command groups
    lib/
      config.ts               # Read/write ~/.dealmachine/config.json (mode 0600)
      client.ts               # HTTP client wrapper (apiRequest, formatDate, getApiKey)
      api.ts                  # Device auth flow client (requestDeviceCode, pollForToken, verifyCredentials)
      output.ts               # Formatting helpers (printTable, printJson, printKeyValue, parseRequestBody)
    commands/
      agents.ts               # dm agents    -- agent guide and Playbook output
      login.ts                # dm login     -- device auth + API key login
      logout.ts               # dm logout    -- remove credentials
      whoami.ts               # dm whoami    -- show/verify auth status
      config.ts               # dm config    -- get, set, path
      account.ts              # dm account   -- show account info
      usage.ts                # dm usage     -- credit usage
      properties.ts           # dm properties -- search, count, get, ids, export
      people.ts               # dm people    -- search, count, get, ids, export
      enrich.ts               # dm enrich    -- address, latlng, apn, email, phone, name
      comps.ts                # dm comps     -- comparable properties
      lists.ts                # dm lists     -- full CRUD + build, import, export
      filters.ts              # dm filters   -- list available filters
      fields.ts               # dm fields    -- list available fields
      activity.ts             # dm activity  -- search, get
      addresses.ts            # dm addresses -- validate
      dev.ts                  # dm dev       -- local license management
  dist/                       # Compiled output (ESM)
  package.json
  tsconfig.json

关键模块

模块	职责
lib/config.ts	管理 ~/.dealmachine/config.json。强制要求文件权限为 0600、目录权限为 0700。提供带类型的读取、写入和删除辅助函数。
lib/client.ts	集中式 HTTP 客户端。从环境变量、配置或默认值解析 API 基础 URL。添加 Authorization: Bearer 标头和带版本号的 User-Agent。发生 HTTP 错误时以非零代码退出。
lib/api.ts	设备授权流程的实现。处理 POST /v1/auth/device/code 和 POST /v1/auth/device/token，支持符合 RFC 8628 的轮询和错误映射。还提供用于密钥验证的 verifyCredentials。
lib/output.ts	所有输出格式化功能：printTable（自动调整列宽）、printJson、printKeyValue、printPagination、printCredits、printTotals、printWarning、printHeader。还导出用于处理 --body、-f 和标准输入的 parseRequestBody。

---

构建

npm run build      # Compile TypeScript and bundle agent Playbook assets to dist/
npm run dev        # Watch mode (tsc --watch)
npm run eval:cold-start:local      # Verify a clean local install and routing contract
npm run eval:cold-start:published  # Verify the latest public npm artifact
npm run eval:cold-start:deployed   # Verify deployed documentation and skill assets

已发布检查和部署检查是发布门禁。预计在发布版本或文档部署进入生产环境之前，这些检查会失败。场景目录存储在 evals/claude-code-name-lookup.json 中，因此相同的提示词变体始终清晰可见且便于审查。

测试

npm test           # Unit and behavioral tests with a mocked API (no credentials)
npm run check      # Typecheck, build, tests and the public artifact guard
DM_API_URL=https://api-staging.v2.dealmachine.com/v1 DM_API_KEY=<key> npm run smoke:live:coverage

npm test 不会调用任何 API。smoke:live:coverage 会构建 CLI，并使用 DM_API_KEY 进行身份验证，通过真实的 dm 二进制文件访问 DM_API_URL 指定的 API。这两个变量都必须设置；密钥绝不会被打印。每个命令都会使用临时主目录运行，因此烟雾测试不会读取或更改你自己的 dm login 凭据。测试只运行只读且不消耗额度的命令：

命令	检查
dm --version	无需网络请求即可打印软件包版本
dm account --json	已提供组织、用户身份验证类型和套餐
dm filters --source-type properties --per-page 5 --json	筛选器包含 ID、名称、运算符和分页信息
dm fields --source-type properties --per-page 5 --json	字段包含 ID、名称和分页信息
dm properties search --body <ZIP 78704> --estimate-cost --json	返回估算结果，不含记录且不消耗额度

请求会经过本地中继；中继会拒绝所有不属于这些只读端点的请求（属性搜索必须携带 estimate_cost: true），并确认每个请求都发送了 X-DealMachine-Source: cli 和 CLI User-Agent。烟雾测试会为每条命令打印一行 PASS 或 FAIL，并且只有在所有命令都通过时才以 0 退出。

独立二进制文件

编译后的 dist/index.js 包含 #!/usr/bin/env node shebang，并在 package.json 的 bin.dm 下声明。通过 npm 全局安装后，它会以 dm 的名称添加到 PATH 中。

如需将其作为独立二进制文件分发，而不使用 npm：

# Build
cd dealmachine-cli
npm run build

# The entire dist/ directory is the distributable artifact
# dist/index.js is the entrypoint (requires Node.js >= 18 on the target machine)

package.json 中的 files 数组可确保发布的软件包仅包含 dist/。

TypeScript 配置

• 目标版本：ES2022
• 模块：NodeNext（ESM）
• 已启用严格模式
• 输出声明文件、声明映射文件和源映射文件
• 无项目引用（独立编译）

---

添加新命令

第 1 步：创建命令文件

创建 src/commands/mycommand.ts：

/**
 * MyCommand -- description of what this command does
 */

import chalk from 'chalk';
import ora from 'ora';
import { apiRequest } from '../lib/client.js';
import { printJson, printHeader, printKeyValue } from '../lib/output.js';

interface MyResponse {
  data: { id: string; name: string };
}

export async function myCommand(options: { json?: boolean }): Promise<void> {
  const spinner = ora('Doing something...').start();
  const data = await apiRequest<MyResponse>('/my-endpoint');
  spinner.stop();

  if (options.json) {
    printJson(data);
    return;
  }

  printHeader('My Command');
  printKeyValue({
    ID: data.data.id,
    Name: data.data.name,
  });
  console.log();
}

第 2 步：在 index.ts 中注册

在 src/index.ts 中导入并接入命令：

import { myCommand } from './commands/mycommand.js';

// Top-level command
program
  .command('mycommand')
  .description('Description shown in --help')
  .option('--json', 'Output as JSON')
  .action(async (options) => {
    await myCommand(options);
  });

// Or as a subcommand group
const myGroup = program.command('mygroup').description('Group description');

myGroup
  .command('sub1')
  .description('Subcommand description')
  .action(async (options) => {
    await mySub1(options);
  });

第 3 步：构建并测试

npm run build
node dist/index.js mycommand --json

约定

• 在 src/commands/ 中为每个命令组创建一个文件。
• 始终支持 --json，以便输出机器可读的内容。
• 在调用 API 时使用 ora 显示加载动画。
• 使用 chalk 为终端输出添加颜色。
• 所有 API 调用都使用 lib/client.ts 中的 apiRequest<T>——它会处理身份验证、错误和退出。
• 命令接受 --body、-f 或 stdin 输入时，使用 lib/output.ts 中的 parseRequestBody。
• 使用 printHeader、printTable、printKeyValue、printCredits、printPagination，确保输出格式一致。
• 所有导入都必须使用 .js 扩展名（NodeNext 解析下的 ESM 要求）。

---

依赖项

运行时

软件包	版本	用途
commander	^12.1.0	CLI 框架——命令注册、选项解析、帮助生成
chalk	^5.3.0	终端字符串样式（颜色、粗体、暗淡）
ora	^8.1.0	异步操作的加载动画
open	^10.1.0	为设备身份验证流程打开浏览器

开发

软件包	版本	用途
typescript	^5.6.3	TypeScript 编译器
@types/node	^22.0.0	Node.js 类型定义

内部包依赖

无。 此包是完全独立的二进制文件，不依赖任何 @dealmachine/*。它仅通过公开 REST API 进行通信。

使用方

packages/playbooks/playbook/ 中的 Playbook 使用 dm 命令执行房产情报工作流。CLI 是 Playbook 与 DealMachine 数据交互的主要接口。Agent 可以通过 dm agents playbook 直接加载捆绑的 Playbook。

工厂暂存工作跟踪

factory-release-intake.yml 工作流在 master 上维护，并从 staging 读取已合并的 PR。它会向 Factory Releases 报告来源；如果已登记，还会报告确切的 staging 部署；同时复用 Linear 链接，或创建一个可配置的试点跟踪问题。定期协调会重试遗漏的事件，且不会创建重复问题。它不会部署此仓库、运行 QA 或批准生产发布。

此收集器由 Factory 生成。有关配置、来源所有权、重新生成和恢复，请参阅自动暂存接入。尽管报告工作流位于 master 上，staging 仍是正在检查的分支。