DealMachine

DealMachine CLI

メンテナー：エージェント向けの指示、開発、現在のコマンドリファレンス、npm リリース。

DealMachine CLI（dm）――コマンドラインから不動産情報を活用できます。

DealMachine REST API と通信する、単独で動作する Commander.js CLI です。認証、不動産と人物の調査、エンリッチメント、リスト、見込み客、タグ、Webhook、郵送、開発者向けユーティリティのコマンドを提供します。tsc を使って ESM JavaScript にコンパイルします。

このパッケージには @dealmachine/* への依存関係が一切なく、公開 API のみを介して通信する自己完結型のバイナリです。

---

AI エージェント連携

このリポジトリは、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 をサポートしています。また、ベアラートークンの設定に対応する開発者向けクライアントでは、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 エージェント連携
• インストール
• 認証
• 設定
• コマンド
  • エージェント -- agents、agents guide、agents playbook、agents install、agents permissions
  • 認証 -- login、logout、whoami
  • 設定 -- 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 は 2 つの認証方法をサポートしています。

デバイス認証フロー（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、5 秒のバックオフを行う slow_down、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

---

コマンド

エージェントコマンド

dm agents

CLI を使用するエージェント向けの簡潔なガイダンスを表示します。dm を利用できるものの、DealMachine Playbook をまだ読み込んでいないエージェントが最初に実行するコマンドとして推奨されます。

dm agents
dm agents --json

このガイドでは、エージェントに --json と --quiet の使用、認証の確認、検索前の最新のフィルターとフィールドの取得、クレジットを消費する作業の前の件数確認、レコードの取得やエクスポート前の想定クレジット使用量の確認を促します。

dm agents guide

同じ簡潔なエージェント向けガイダンスを明示的に表示します。

dm agents guide
dm agents guide --json

dm agents playbook

バンドルされているDealMachine PlaybookのMarkdownを出力します。エージェントは、自然言語による物件、人物、連絡先、情報補完、リスト、エクスポート、比較物件、クレジット使用量に関するリクエストを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を含む）には表示されません。エージェントからは次の形式を使用してください。

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":[]}'

Option	Description
--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

Option	Description
--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 で指定し、1 回のバッチリクエストで取得します。

# 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

Option	Description
--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	Do Not Call 登録簿に掲載されている連絡先を除外します
--json	JSON として出力します

---

People コマンド

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":[]}'

非対話型の People Search では、--yes を指定しない限り、無料の見積もりが返されます。名前で特定の人物を検索する場合は、People Search ではなく dm enrich name を使用します。

dm people count

クレジットを消費せずに、フィルターに一致する人物の数をカウントします。

dm people count -f filters.json

dm people get <id>

DealMachine ID を指定して、1 人の人物を取得します。

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 で指定し、1 回のバッチリクエストで取得します。

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 と同じです。

---

Enrich コマンド

すべてのエンリッチメントコマンドは、3 種類の入力方法に対応しています。単一項目の検索には位置引数、JSON ペイロードには --body／-f、CSV からの一括エンリッチメントには .csv ファイルを指定した -f を使用します。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]

Assessor's Parcel Number から物件を検索します。--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]

名前から人物を検索します。「First Last」または「Last」の形式に対応しています。

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>	1 ページあたりの検索結果数

---

Comps コマンド

dm comps [property_ids...]

1 件以上の物件について、類似物件（売買事例）を検索します。

# 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}
}'

オプション	説明
--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

オプション	説明
--search <term>	リスト名で検索します
--source-type <type>	properties または people
--sort <order>	newest、oldest、name、count
-p, --page <n>	ページ番号
--per-page <n>	1 ページあたりの結果数

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

オプション	説明
--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

オプション	説明
--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

オプション	説明
--fields <csv>	エクスポートするフィールドのカンマ区切りリスト
--anchor <type>	property または person

---

フィルターコマンド

dm filters

利用可能な検索フィルターと、そのタイプ、演算子、グループ分けを一覧表示します。

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

Option	Description
--source-type <type>	properties or people
--group-id <id>	グループ ID で絞り込みます
--search <term>	フィルター名で検索します
--page <n>	ページ番号
--per-page <n>	1 ページあたりの結果数

---

フィールドコマンド

dm fields

フィルター可能・並べ替え可能なフラグを含む、利用可能なデータフィールドを一覧表示します。

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

Option	Description
--source-type <type>	properties or people
--group-id <id>	グループ ID で絞り込みます
--search <term>	フィールド名で検索します
--page <n>	ページ番号
--per-page <n>	1 ページあたりの結果数

---

ロケーションコマンド

DealMachine のロケーションを検索して取得します。

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

dm locations autocomplete は、非推奨のエイリアスとして引き続き利用できます。代わりに dm addresses autocomplete を使用してください。

---

アクティビティコマンド

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}'

Option	Description
--body <json>	リクエスト本文を JSON 文字列で指定します
-f, --file <path>	JSON ファイルからリクエスト本文を読み込みます
-t, --types <types...>	アクティビティタイプで絞り込みます（スペース区切り）
-q, --query <text>	アクティビティ全体をフリーテキストで検索します
--page <n>	ページ番号
--per-page <n>	1 ページあたりの結果数

dm activity get <id>

特定のアクティビティレコードの詳細をすべて取得します。元のリクエスト、結果の概要、エンティティ ID（人物と物件）が含まれます。

dm activity get act_abc123
dm activity get act_abc123 --json

---

住所コマンド

dm addresses autocomplete <query>

無料で、件数に上限のある住所および正規化済みロケーションの候補を返します。

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

Option	Description
--scope <scope>	all、address、または location。デフォルトは all
--state <code>	2 文字の州略称を優先します
--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

出力では、各住所が有効、修正済み（修正内容を表示）、または無効（理由を表示）として示されます。

---

開発コマンド

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

Option	Description
--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	エージェントやスクリプト向けに、スピナーや装飾的な出力を抑制します
--help	任意のコマンドの使用方法を表示します
--version	CLI のバージョンを表示します

---

入力方法

リクエスト本文を受け取るコマンドでは、次の 3 つの入力方法をこの順序で確認します。

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	デバイス認証フローの実装です。RFC 8628 に準拠したポーリングとエラーマッピングを使用して、POST /v1/auth/device/code と POST /v1/auth/device/token を処理します。また、キー検証用の 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 バイナリを DM_API_URL で指定した API に対して実行し、DM_API_KEY で認証します。どちらも必須ですが、キーが表示されることはありません。各コマンドは一時的なホームディレクトリで実行されるため、スモークテストがご自身の 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 のシバンが含まれており、package.json の bin.dm に登録されています。npm 経由でグローバルにインストールすると、PATH 上で dm として利用できます。

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/ にコマンドグループごとのファイルを 1 つ作成します。
• 機械可読な出力に対応するため、常に --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 のデータを操作するための主要なインターフェースです。エージェントは dm agents playbook を使って、バンドルされた Playbook を直接読み込めます。

Factory のステージング作業の追跡

factory-release-intake.yml ワークフローは master で管理され、ステージングからマージ済みの PR を読み取ります。ソースと、登録されている場合は正確なステージングデプロイを Factory Releases に報告し、Linear のリンクを再利用するか、設定可能なパイロット追跡用の issue を 1 件作成します。スケジュールされた照合により、イベントの見逃しを重複 issue を作成せずに再試行します。このワークフローは、このリポジトリのデプロイ、QA の実行、本番環境の承認は行いません。

コレクターは Factory から生成されます。設定、ソースの所有権、再生成、復旧については、ステージングの自動取り込みをご覧ください。報告ワークフローは master にありますが、確認対象のブランチは引き続きステージングです。