@dealmachine/cli 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +1141 -0
- package/dist/agents/dealmachine-playbook.md +936 -0
- package/dist/commands/account.d.ts +5 -0
- package/dist/commands/account.d.ts.map +1 -0
- package/dist/commands/account.js +17 -0
- package/dist/commands/account.js.map +1 -0
- package/dist/commands/activity.d.ts +16 -0
- package/dist/commands/activity.d.ts.map +1 -0
- package/dist/commands/activity.js +110 -0
- package/dist/commands/activity.js.map +1 -0
- package/dist/commands/addresses.d.ts +9 -0
- package/dist/commands/addresses.d.ts.map +1 -0
- package/dist/commands/addresses.js +63 -0
- package/dist/commands/addresses.js.map +1 -0
- package/dist/commands/agents.d.ts +10 -0
- package/dist/commands/agents.d.ts.map +1 -0
- package/dist/commands/agents.js +115 -0
- package/dist/commands/agents.js.map +1 -0
- package/dist/commands/comps.d.ts +16 -0
- package/dist/commands/comps.d.ts.map +1 -0
- package/dist/commands/comps.js +131 -0
- package/dist/commands/comps.js.map +1 -0
- package/dist/commands/config.d.ts +7 -0
- package/dist/commands/config.d.ts.map +1 -0
- package/dist/commands/config.js +83 -0
- package/dist/commands/config.js.map +1 -0
- package/dist/commands/crm.d.ts +122 -0
- package/dist/commands/crm.d.ts.map +1 -0
- package/dist/commands/crm.js +519 -0
- package/dist/commands/crm.js.map +1 -0
- package/dist/commands/dev.d.ts +8 -0
- package/dist/commands/dev.d.ts.map +1 -0
- package/dist/commands/dev.js +102 -0
- package/dist/commands/dev.js.map +1 -0
- package/dist/commands/dialer.d.ts +79 -0
- package/dist/commands/dialer.d.ts.map +1 -0
- package/dist/commands/dialer.js +389 -0
- package/dist/commands/dialer.js.map +1 -0
- package/dist/commands/enrich.d.ts +46 -0
- package/dist/commands/enrich.d.ts.map +1 -0
- package/dist/commands/enrich.js +649 -0
- package/dist/commands/enrich.js.map +1 -0
- package/dist/commands/exports.d.ts +13 -0
- package/dist/commands/exports.d.ts.map +1 -0
- package/dist/commands/exports.js +92 -0
- package/dist/commands/exports.js.map +1 -0
- package/dist/commands/fields.d.ts +12 -0
- package/dist/commands/fields.d.ts.map +1 -0
- package/dist/commands/fields.js +43 -0
- package/dist/commands/fields.js.map +1 -0
- package/dist/commands/filters.d.ts +12 -0
- package/dist/commands/filters.d.ts.map +1 -0
- package/dist/commands/filters.js +41 -0
- package/dist/commands/filters.js.map +1 -0
- package/dist/commands/lists.d.ts +62 -0
- package/dist/commands/lists.d.ts.map +1 -0
- package/dist/commands/lists.js +329 -0
- package/dist/commands/lists.js.map +1 -0
- package/dist/commands/locations.d.ts +15 -0
- package/dist/commands/locations.d.ts.map +1 -0
- package/dist/commands/locations.js +68 -0
- package/dist/commands/locations.js.map +1 -0
- package/dist/commands/login.d.ts +11 -0
- package/dist/commands/login.d.ts.map +1 -0
- package/dist/commands/login.js +144 -0
- package/dist/commands/login.js.map +1 -0
- package/dist/commands/logout.d.ts +5 -0
- package/dist/commands/logout.d.ts.map +1 -0
- package/dist/commands/logout.js +24 -0
- package/dist/commands/logout.js.map +1 -0
- package/dist/commands/mail.d.ts +112 -0
- package/dist/commands/mail.d.ts.map +1 -0
- package/dist/commands/mail.js +727 -0
- package/dist/commands/mail.js.map +1 -0
- package/dist/commands/people.d.ts +36 -0
- package/dist/commands/people.d.ts.map +1 -0
- package/dist/commands/people.js +226 -0
- package/dist/commands/people.js.map +1 -0
- package/dist/commands/phones.d.ts +9 -0
- package/dist/commands/phones.d.ts.map +1 -0
- package/dist/commands/phones.js +53 -0
- package/dist/commands/phones.js.map +1 -0
- package/dist/commands/properties.d.ts +38 -0
- package/dist/commands/properties.d.ts.map +1 -0
- package/dist/commands/properties.js +225 -0
- package/dist/commands/properties.js.map +1 -0
- package/dist/commands/subscription.d.ts +7 -0
- package/dist/commands/subscription.d.ts.map +1 -0
- package/dist/commands/subscription.js +36 -0
- package/dist/commands/subscription.js.map +1 -0
- package/dist/commands/tasks.d.ts +28 -0
- package/dist/commands/tasks.d.ts.map +1 -0
- package/dist/commands/tasks.js +128 -0
- package/dist/commands/tasks.js.map +1 -0
- package/dist/commands/usage.d.ts +7 -0
- package/dist/commands/usage.d.ts.map +1 -0
- package/dist/commands/usage.js +41 -0
- package/dist/commands/usage.js.map +1 -0
- package/dist/commands/whoami.d.ts +9 -0
- package/dist/commands/whoami.d.ts.map +1 -0
- package/dist/commands/whoami.js +40 -0
- package/dist/commands/whoami.js.map +1 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +1942 -0
- package/dist/index.js.map +1 -0
- package/dist/lib/api.d.ts +53 -0
- package/dist/lib/api.d.ts.map +1 -0
- package/dist/lib/api.js +110 -0
- package/dist/lib/api.js.map +1 -0
- package/dist/lib/client.d.ts +18 -0
- package/dist/lib/client.d.ts.map +1 -0
- package/dist/lib/client.js +88 -0
- package/dist/lib/client.js.map +1 -0
- package/dist/lib/config.d.ts +22 -0
- package/dist/lib/config.d.ts.map +1 -0
- package/dist/lib/config.js +65 -0
- package/dist/lib/config.js.map +1 -0
- package/dist/lib/output.d.ts +36 -0
- package/dist/lib/output.d.ts.map +1 -0
- package/dist/lib/output.js +164 -0
- package/dist/lib/output.js.map +1 -0
- package/dist/lib/searchProtocol.d.ts +10 -0
- package/dist/lib/searchProtocol.d.ts.map +1 -0
- package/dist/lib/searchProtocol.js +46 -0
- package/dist/lib/searchProtocol.js.map +1 -0
- package/package.json +52 -0
package/README.md
ADDED
|
@@ -0,0 +1,1141 @@
|
|
|
1
|
+
# @dealmachine/cli
|
|
2
|
+
|
|
3
|
+
DealMachine CLI (`dm`) -- property intelligence from the command line.
|
|
4
|
+
|
|
5
|
+
A standalone Commander.js CLI that talks to the DealMachine REST API. Provides **17 command groups** covering agent guidance, authentication, property search, people lookup, enrichment, comps, list management, and developer utilities. Compiles to a single ESM bundle via `tsc`.
|
|
6
|
+
|
|
7
|
+
This package has **zero** `@dealmachine/*` dependencies -- it is a self-contained binary that communicates exclusively through the public API.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Table of Contents
|
|
12
|
+
|
|
13
|
+
- [Installation](#installation)
|
|
14
|
+
- [Authentication](#authentication)
|
|
15
|
+
- [Configuration](#configuration)
|
|
16
|
+
- [Commands](#commands)
|
|
17
|
+
- [Agents](#agents-commands) -- `agents`, `agents guide`, `agents playbook`
|
|
18
|
+
- [Auth](#auth-commands) -- `login`, `logout`, `whoami`
|
|
19
|
+
- [Config](#config-commands) -- `config get`, `config set`, `config path`
|
|
20
|
+
- [Account](#account-commands) -- `account`
|
|
21
|
+
- [Usage](#usage-commands) -- `usage`
|
|
22
|
+
- [Properties](#properties-commands) -- `search`, `count`, `get`, `ids`, `export`
|
|
23
|
+
- [People](#people-commands) -- `search`, `count`, `get`, `ids`, `export`
|
|
24
|
+
- [Enrich](#enrich-commands) -- `address`, `latlng`, `apn`, `email`, `phone`, `name`
|
|
25
|
+
- [Comps](#comps-commands) -- comparable property analysis
|
|
26
|
+
- [Lists](#lists-commands) -- `search`, `create`, `get`, `update`, `delete`, `build`, `import`, `items`, `add`, `remove`, `export`
|
|
27
|
+
- [Filters](#filters-commands) -- list available search filters
|
|
28
|
+
- [Fields](#fields-commands) -- list available data fields
|
|
29
|
+
- [Activity](#activity-commands) -- `search`, `get`
|
|
30
|
+
- [Addresses](#addresses-commands) -- `validate`
|
|
31
|
+
- [Dev](#dev-commands) -- `license add`, `license list`, `license remove`
|
|
32
|
+
- [Global Options](#global-options)
|
|
33
|
+
- [Input Methods](#input-methods)
|
|
34
|
+
- [Project Structure](#project-structure)
|
|
35
|
+
- [Building](#building)
|
|
36
|
+
- [Adding New Commands](#adding-new-commands)
|
|
37
|
+
- [Dependencies](#dependencies)
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## Installation
|
|
42
|
+
|
|
43
|
+
### From npm (global)
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npm install -g @dealmachine/cli
|
|
47
|
+
dm login
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### From source
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
cd packages/cli
|
|
54
|
+
npm run build
|
|
55
|
+
node dist/index.js whoami
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### Link for local development
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
cd packages/cli
|
|
62
|
+
npm link
|
|
63
|
+
dm --version
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
The binary entry is `dist/index.js`, declared in `package.json` under `bin.dm`. Requires Node.js >= 18.
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## Authentication
|
|
71
|
+
|
|
72
|
+
The CLI supports two authentication methods.
|
|
73
|
+
|
|
74
|
+
### Device Auth Flow (RFC 8628)
|
|
75
|
+
|
|
76
|
+
The default `dm login` command uses the OAuth 2.0 Device Authorization Grant (RFC 8628). This is the recommended flow for interactive use:
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
dm login
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
1. The CLI requests a device code from `POST /v1/auth/device/code` with client ID `dealmachine-next-cli` and your machine's hostname.
|
|
83
|
+
2. A verification URL and user code are displayed. The browser opens automatically (unless `--no-browser`).
|
|
84
|
+
3. You authorize the device in the browser by entering the user code.
|
|
85
|
+
4. The CLI polls `POST /v1/auth/device/token` at the server-specified interval.
|
|
86
|
+
5. On success, the API key, key ID, and organization details are stored to `~/.dealmachine/config.json`.
|
|
87
|
+
|
|
88
|
+
The polling handles all RFC 8628 responses: `authorization_pending`, `slow_down` (backs off by 5s), `access_denied`, and `expired_token`.
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
# Skip auto-opening the browser
|
|
92
|
+
dm login --no-browser
|
|
93
|
+
|
|
94
|
+
# Target a specific environment
|
|
95
|
+
dm login --env local
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Direct API Key Login
|
|
99
|
+
|
|
100
|
+
For CI pipelines, scripts, or local development, pass an API key directly:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
dm login --key dm_sk_live_abc123...
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
The key is verified against `GET /v1/account` before being stored. If verification fails, the CLI exits with a non-zero code.
|
|
107
|
+
|
|
108
|
+
### Switching Environments
|
|
109
|
+
|
|
110
|
+
If you are already logged in, you can switch the target API environment without logging out:
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
dm login --env local # Switch to http://localhost:3001/v1
|
|
114
|
+
dm login --env production # Switch to https://api.v2.dealmachine.com/v1
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### Logout
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
dm logout
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Removes the config file at `~/.dealmachine/config.json`.
|
|
124
|
+
|
|
125
|
+
---
|
|
126
|
+
|
|
127
|
+
## Configuration
|
|
128
|
+
|
|
129
|
+
Credentials are stored at `~/.dealmachine/config.json` with file permissions `0600` (owner read/write only). The config directory `~/.dealmachine/` is created with mode `0700`.
|
|
130
|
+
|
|
131
|
+
### Config File Schema
|
|
132
|
+
|
|
133
|
+
```json
|
|
134
|
+
{
|
|
135
|
+
"apiKey": "dm_sk_live_...",
|
|
136
|
+
"keyId": "key_abc123",
|
|
137
|
+
"organizationId": 42,
|
|
138
|
+
"organizationName": "Acme Corp",
|
|
139
|
+
"organizationSlug": "acme-corp",
|
|
140
|
+
"apiEnvironment": "production"
|
|
141
|
+
}
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### Environment Variables
|
|
145
|
+
|
|
146
|
+
The CLI checks these environment variables for API URL resolution (in priority order):
|
|
147
|
+
|
|
148
|
+
| Variable | Purpose | Example |
|
|
149
|
+
| ------------------------------------ | ------------------- | -------------------------- |
|
|
150
|
+
| `DM_API_URL` / `DEALMACHINE_API_URL` | Direct URL override | `http://localhost:3001/v1` |
|
|
151
|
+
| `DM_ENV` / `DEALMACHINE_ENVIRONMENT` | Environment name | `local` or `production` |
|
|
152
|
+
|
|
153
|
+
If none are set, the CLI falls back to the `apiEnvironment` field in the config file, then defaults to `local`.
|
|
154
|
+
|
|
155
|
+
### API Environments
|
|
156
|
+
|
|
157
|
+
| Environment | URL |
|
|
158
|
+
| ------------ | ----------------------------------- |
|
|
159
|
+
| `local` | `http://localhost:3001/v1` |
|
|
160
|
+
| `production` | `https://api.v2.dealmachine.com/v1` |
|
|
161
|
+
|
|
162
|
+
---
|
|
163
|
+
|
|
164
|
+
## Commands
|
|
165
|
+
|
|
166
|
+
### Agents Commands
|
|
167
|
+
|
|
168
|
+
#### `dm agents`
|
|
169
|
+
|
|
170
|
+
Print concise guidance for agents using the CLI. This is the recommended first command when an agent has access to `dm` but has not loaded the DealMachine Playbook yet.
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
dm agents
|
|
174
|
+
dm agents --json
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
The guide tells agents to use `--json` and `--quiet`, verify auth, fetch live filters and fields before searches, count before credit-consuming work, and confirm expected credit usage before fetching records or exporting.
|
|
178
|
+
|
|
179
|
+
#### `dm agents guide`
|
|
180
|
+
|
|
181
|
+
Print the same concise agent guidance explicitly.
|
|
182
|
+
|
|
183
|
+
```bash
|
|
184
|
+
dm agents guide
|
|
185
|
+
dm agents guide --json
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
#### `dm agents playbook`
|
|
189
|
+
|
|
190
|
+
Print the bundled DealMachine Playbook Markdown. Agents should load this before translating natural language property, people, contact, enrichment, list, export, comps, or credit-usage requests into CLI commands.
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
dm agents playbook
|
|
194
|
+
dm agents playbook --json
|
|
195
|
+
dm agents skill # alias
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
The Playbook is copied from `packages/playbooks/playbook/SKILL.md` into `dist/agents/dealmachine-playbook.md` during `npm run build`, so the command works from a published CLI package as well as a local source checkout.
|
|
199
|
+
|
|
200
|
+
---
|
|
201
|
+
|
|
202
|
+
### Auth Commands
|
|
203
|
+
|
|
204
|
+
#### `dm login`
|
|
205
|
+
|
|
206
|
+
Authenticate with your DealMachine account.
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
dm login # Device auth flow (opens browser)
|
|
210
|
+
dm login --no-browser # Device auth, manual code entry
|
|
211
|
+
dm login --key dm_sk_live_abc123 # Direct API key
|
|
212
|
+
dm login --env local # Target local API
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
| Option | Description |
|
|
216
|
+
| --------------------- | ---------------------------------------------- |
|
|
217
|
+
| `--no-browser` | Do not automatically open the browser |
|
|
218
|
+
| `--key <api-key>` | Login directly with an API key (skips browser) |
|
|
219
|
+
| `--env <environment>` | API environment: `local` or `production` |
|
|
220
|
+
|
|
221
|
+
#### `dm logout`
|
|
222
|
+
|
|
223
|
+
Remove stored credentials.
|
|
224
|
+
|
|
225
|
+
```bash
|
|
226
|
+
dm logout
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
#### `dm whoami`
|
|
230
|
+
|
|
231
|
+
Show current authentication status.
|
|
232
|
+
|
|
233
|
+
```bash
|
|
234
|
+
dm whoami # Show stored credentials
|
|
235
|
+
dm whoami --verify # Verify credentials against the API
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
| Option | Description |
|
|
239
|
+
| ---------- | ------------------------------- |
|
|
240
|
+
| `--verify` | Verify credentials with the API |
|
|
241
|
+
|
|
242
|
+
---
|
|
243
|
+
|
|
244
|
+
### Config Commands
|
|
245
|
+
|
|
246
|
+
#### `dm config get [key]`
|
|
247
|
+
|
|
248
|
+
Get a configuration value, or display all values when no key is given.
|
|
249
|
+
|
|
250
|
+
```bash
|
|
251
|
+
dm config get # Show all config values
|
|
252
|
+
dm config get apiEnvironment # Show specific value
|
|
253
|
+
dm config get apiKey # Shows truncated key (first 20 chars)
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
Available keys: `organizationName`, `organizationSlug`, `organizationId`, `apiEnvironment`, `keyId`, `apiKey`.
|
|
257
|
+
|
|
258
|
+
#### `dm config set <key> <value>`
|
|
259
|
+
|
|
260
|
+
Set a configuration value. Only `apiEnvironment` is editable.
|
|
261
|
+
|
|
262
|
+
```bash
|
|
263
|
+
dm config set apiEnvironment local
|
|
264
|
+
dm config set apiEnvironment production
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
#### `dm config path`
|
|
268
|
+
|
|
269
|
+
Print the absolute path to the config file.
|
|
270
|
+
|
|
271
|
+
```bash
|
|
272
|
+
dm config path
|
|
273
|
+
# /Users/you/.dealmachine/config.json
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
---
|
|
277
|
+
|
|
278
|
+
### Account Commands
|
|
279
|
+
|
|
280
|
+
#### `dm account`
|
|
281
|
+
|
|
282
|
+
Display account information including organization name, ID, creation date, and auth type.
|
|
283
|
+
|
|
284
|
+
```bash
|
|
285
|
+
dm account
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
Output:
|
|
289
|
+
|
|
290
|
+
```
|
|
291
|
+
Account
|
|
292
|
+
────────────────────────────────────────
|
|
293
|
+
Organization: Acme Corp
|
|
294
|
+
Org ID: 42
|
|
295
|
+
Created: Jan 15, 2025
|
|
296
|
+
Auth Type: api_key
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
---
|
|
300
|
+
|
|
301
|
+
### Usage Commands
|
|
302
|
+
|
|
303
|
+
#### `dm usage`
|
|
304
|
+
|
|
305
|
+
Show credit usage for the current billing cycle.
|
|
306
|
+
|
|
307
|
+
```bash
|
|
308
|
+
dm usage # Human-readable table
|
|
309
|
+
dm usage --json # Machine-readable JSON
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
Output:
|
|
313
|
+
|
|
314
|
+
```
|
|
315
|
+
Credit Usage
|
|
316
|
+
──────────────────────────────────────────────────
|
|
317
|
+
Plan: Pro
|
|
318
|
+
Cycle: Mar 1, 2026 — Mar 31, 2026
|
|
319
|
+
|
|
320
|
+
Credits: 4,200 / 10,000 (42%)
|
|
321
|
+
Remaining: 5,800
|
|
322
|
+
|
|
323
|
+
Breakdown:
|
|
324
|
+
Properties: 3,100
|
|
325
|
+
People: 1,100
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
---
|
|
329
|
+
|
|
330
|
+
### Properties Commands
|
|
331
|
+
|
|
332
|
+
#### `dm properties search`
|
|
333
|
+
|
|
334
|
+
Search properties with filters and locations.
|
|
335
|
+
|
|
336
|
+
```bash
|
|
337
|
+
# Inline JSON body
|
|
338
|
+
dm properties search --body '{
|
|
339
|
+
"locations": [{"type": "zip_code", "code": "78704"}],
|
|
340
|
+
"filters": [{"filter_id": "property_type", "operator": "is_any_of", "value": ["single_family"]}]
|
|
341
|
+
}'
|
|
342
|
+
|
|
343
|
+
# From a file
|
|
344
|
+
dm properties search -f search.json
|
|
345
|
+
|
|
346
|
+
# Pipe from stdin
|
|
347
|
+
cat search.json | dm properties search
|
|
348
|
+
|
|
349
|
+
# Machine-readable output
|
|
350
|
+
dm properties search -f search.json --json
|
|
351
|
+
|
|
352
|
+
# Query Builder protocol filters
|
|
353
|
+
dm properties search --include-lists 123,456 --exclude-previously-exported --body '{"locations":[]}'
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
| Option | Description |
|
|
357
|
+
| --------------------------------- | ----------------------------------------------------------------------------- |
|
|
358
|
+
| `--body <json>` | Request body as JSON string |
|
|
359
|
+
| `-f, --file <path>` | Read request body from a JSON file |
|
|
360
|
+
| `--include-lists <ids>` | Comma-separated list IDs to include |
|
|
361
|
+
| `--exclude-lists <ids>` | Comma-separated list IDs to exclude |
|
|
362
|
+
| `--exclude-previously-exported` | Exclude records already exported by your organization |
|
|
363
|
+
| `--bigquery-data-environment <n>` | Query Builder data environment (`1` production, `2` staging, `3` development) |
|
|
364
|
+
| `--json` | Output as JSON |
|
|
365
|
+
|
|
366
|
+
#### `dm properties count`
|
|
367
|
+
|
|
368
|
+
Count properties matching filters without consuming credits.
|
|
369
|
+
|
|
370
|
+
```bash
|
|
371
|
+
dm properties count --body '{"locations": [{"type": "state", "code": "TX"}]}'
|
|
372
|
+
dm properties count -f filters.json --json
|
|
373
|
+
```
|
|
374
|
+
|
|
375
|
+
#### `dm properties get <id>`
|
|
376
|
+
|
|
377
|
+
Get a single property by its DealMachine ID.
|
|
378
|
+
|
|
379
|
+
```bash
|
|
380
|
+
dm properties get prop_12345
|
|
381
|
+
dm properties get prop_12345 --contact-audience owners_and_family
|
|
382
|
+
dm properties get prop_12345 --json
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
| Option | Description |
|
|
386
|
+
| ------------------------------- | ------------------------------------------------------------ |
|
|
387
|
+
| `--contact-audience <audience>` | `owners`, `owners_and_family`, `renters`, `residents`, `all` |
|
|
388
|
+
| `--json` | Output as JSON |
|
|
389
|
+
|
|
390
|
+
#### `dm properties ids [ids...]`
|
|
391
|
+
|
|
392
|
+
Get multiple properties by their IDs in a single batch request.
|
|
393
|
+
|
|
394
|
+
```bash
|
|
395
|
+
# Positional arguments
|
|
396
|
+
dm properties ids prop_111 prop_222 prop_333
|
|
397
|
+
|
|
398
|
+
# Via JSON body
|
|
399
|
+
dm properties ids --body '{"ids": ["prop_111", "prop_222"]}'
|
|
400
|
+
|
|
401
|
+
# From file
|
|
402
|
+
dm properties ids -f ids.json --contact-audience owners
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
| Option | Description |
|
|
406
|
+
| ------------------------------- | ------------------------------------------------------------------------------ |
|
|
407
|
+
| `--body <json>` | Request body as JSON string |
|
|
408
|
+
| `-f, --file <path>` | Read request body from a JSON file |
|
|
409
|
+
| `--contact-audience <audience>` | Include contacts: `owners`, `owners_and_family`, `renters`, `residents`, `all` |
|
|
410
|
+
| `--json` | Output as JSON |
|
|
411
|
+
|
|
412
|
+
#### `dm properties export`
|
|
413
|
+
|
|
414
|
+
Export properties as CSV (up to 1,000,000 records). Returns signed download URLs.
|
|
415
|
+
|
|
416
|
+
```bash
|
|
417
|
+
dm properties export -f search.json
|
|
418
|
+
dm properties export -f search.json --require-phone --scrub-dnc
|
|
419
|
+
dm properties export --body '{"locations": [...]}' --mobile-only --json
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
| Option | Description |
|
|
423
|
+
| ------------------- | ----------------------------------------------------------- |
|
|
424
|
+
| `--body <json>` | Request body as JSON string |
|
|
425
|
+
| `-f, --file <path>` | Read request body from a JSON file |
|
|
426
|
+
| `--require-phone` | Only include records where the contact has a phone number |
|
|
427
|
+
| `--require-email` | Only include records where the contact has an email address |
|
|
428
|
+
| `--mobile-only` | Only include mobile phone numbers |
|
|
429
|
+
| `--landline-only` | Only include landline phone numbers |
|
|
430
|
+
| `--scrub-dnc` | Exclude contacts on the Do Not Call registry |
|
|
431
|
+
| `--json` | Output as JSON |
|
|
432
|
+
|
|
433
|
+
---
|
|
434
|
+
|
|
435
|
+
### People Commands
|
|
436
|
+
|
|
437
|
+
#### `dm people search`
|
|
438
|
+
|
|
439
|
+
Search people with filters and locations.
|
|
440
|
+
|
|
441
|
+
```bash
|
|
442
|
+
dm people search --body '{
|
|
443
|
+
"locations": [{"type": "zip_code", "code": "78704"}],
|
|
444
|
+
"filters": [{"filter_id": "age", "operator": "between", "value": [30, 50]}]
|
|
445
|
+
}'
|
|
446
|
+
dm people search -f people-search.json --json
|
|
447
|
+
dm people search --include-lists 123 --exclude-lists 456 --exclude-previously-exported --body '{"locations":[]}'
|
|
448
|
+
```
|
|
449
|
+
|
|
450
|
+
#### `dm people count`
|
|
451
|
+
|
|
452
|
+
Count people matching filters without consuming credits.
|
|
453
|
+
|
|
454
|
+
```bash
|
|
455
|
+
dm people count -f filters.json
|
|
456
|
+
```
|
|
457
|
+
|
|
458
|
+
#### `dm people get <id>`
|
|
459
|
+
|
|
460
|
+
Get a single person by their DealMachine ID.
|
|
461
|
+
|
|
462
|
+
```bash
|
|
463
|
+
dm people get per_12345
|
|
464
|
+
dm people get per_12345 --include-properties
|
|
465
|
+
dm people get per_12345 --json
|
|
466
|
+
```
|
|
467
|
+
|
|
468
|
+
| Option | Description |
|
|
469
|
+
| ---------------------- | ----------------------------- |
|
|
470
|
+
| `--include-properties` | Include associated properties |
|
|
471
|
+
| `--json` | Output as JSON |
|
|
472
|
+
|
|
473
|
+
#### `dm people ids [ids...]`
|
|
474
|
+
|
|
475
|
+
Get multiple people by their IDs in a single batch request.
|
|
476
|
+
|
|
477
|
+
```bash
|
|
478
|
+
dm people ids per_111 per_222 per_333
|
|
479
|
+
dm people ids --body '{"ids": ["per_111", "per_222"]}' --include-properties
|
|
480
|
+
```
|
|
481
|
+
|
|
482
|
+
#### `dm people export`
|
|
483
|
+
|
|
484
|
+
Export people as CSV (up to 1,000,000 records). Returns signed download URLs.
|
|
485
|
+
|
|
486
|
+
```bash
|
|
487
|
+
dm people export -f search.json --require-email
|
|
488
|
+
dm people export -f search.json --mobile-only --scrub-dnc --json
|
|
489
|
+
```
|
|
490
|
+
|
|
491
|
+
Contact filter options are the same as `dm properties export`.
|
|
492
|
+
|
|
493
|
+
---
|
|
494
|
+
|
|
495
|
+
### Enrich Commands
|
|
496
|
+
|
|
497
|
+
All enrichment commands support three input modes: a positional argument for single-item lookup, `--body`/`-f` for JSON payloads, and `-f` with a `.csv` file for batch enrichment from CSV. Batches larger than 250 items are automatically chunked.
|
|
498
|
+
|
|
499
|
+
#### `dm enrich address [address]`
|
|
500
|
+
|
|
501
|
+
Look up a property by street address.
|
|
502
|
+
|
|
503
|
+
```bash
|
|
504
|
+
# Single address
|
|
505
|
+
dm enrich address "123 Main St, Austin, TX 78704"
|
|
506
|
+
|
|
507
|
+
# Batch from JSON
|
|
508
|
+
dm enrich address --body '{"data": [{"full_address": "123 Main St, Austin, TX"}]}'
|
|
509
|
+
|
|
510
|
+
# Batch from CSV (auto-detected by .csv extension)
|
|
511
|
+
dm enrich address -f addresses.csv --contact-audience owners
|
|
512
|
+
|
|
513
|
+
# CSV columns: full_address (or street, city, state, zip)
|
|
514
|
+
```
|
|
515
|
+
|
|
516
|
+
| Option | Description |
|
|
517
|
+
| ------------------------------- | ----------------------------------------------------- |
|
|
518
|
+
| `--body <json>` | Request body as JSON string |
|
|
519
|
+
| `-f, --file <path>` | Read from JSON or CSV file |
|
|
520
|
+
| `--contact-audience <audience>` | `owners`, `owners_and_family`, `renters`, `residents` |
|
|
521
|
+
| `--json` | Output as JSON |
|
|
522
|
+
|
|
523
|
+
#### `dm enrich latlng [coords]`
|
|
524
|
+
|
|
525
|
+
Look up a property by latitude/longitude coordinates.
|
|
526
|
+
|
|
527
|
+
```bash
|
|
528
|
+
dm enrich latlng 30.25,-97.75
|
|
529
|
+
dm enrich latlng -f coordinates.csv
|
|
530
|
+
# CSV columns: latitude, longitude (or lat, lng/lon/long)
|
|
531
|
+
```
|
|
532
|
+
|
|
533
|
+
#### `dm enrich apn [apn]`
|
|
534
|
+
|
|
535
|
+
Look up a property by Assessor's Parcel Number. Narrow results with `--state` or `--zip`.
|
|
536
|
+
|
|
537
|
+
```bash
|
|
538
|
+
dm enrich apn "0123-456-789" --state TX
|
|
539
|
+
dm enrich apn -f parcels.csv --zip 78704
|
|
540
|
+
# CSV columns: apn (or parcel_id, parcel_number)
|
|
541
|
+
```
|
|
542
|
+
|
|
543
|
+
| Option | Description |
|
|
544
|
+
| ------------------------------- | ----------------------------------------------------- |
|
|
545
|
+
| `--state <code>` | Narrow by state (e.g., TX) |
|
|
546
|
+
| `--zip <code>` | Narrow by ZIP code |
|
|
547
|
+
| `--contact-audience <audience>` | `owners`, `owners_and_family`, `renters`, `residents` |
|
|
548
|
+
|
|
549
|
+
#### `dm enrich email [email]`
|
|
550
|
+
|
|
551
|
+
Look up a person by email address.
|
|
552
|
+
|
|
553
|
+
```bash
|
|
554
|
+
dm enrich email jane@example.com
|
|
555
|
+
dm enrich email jane@example.com --include-properties
|
|
556
|
+
dm enrich email -f emails.csv --json
|
|
557
|
+
# CSV columns: email (or email_address)
|
|
558
|
+
```
|
|
559
|
+
|
|
560
|
+
| Option | Description |
|
|
561
|
+
| ---------------------- | ----------------------------- |
|
|
562
|
+
| `--include-properties` | Include associated properties |
|
|
563
|
+
|
|
564
|
+
#### `dm enrich phone [phone]`
|
|
565
|
+
|
|
566
|
+
Look up a person by phone number.
|
|
567
|
+
|
|
568
|
+
```bash
|
|
569
|
+
dm enrich phone 5125551234
|
|
570
|
+
dm enrich phone -f phones.csv --include-properties
|
|
571
|
+
# CSV columns: phone (or phone_number)
|
|
572
|
+
```
|
|
573
|
+
|
|
574
|
+
#### `dm enrich name [name]`
|
|
575
|
+
|
|
576
|
+
Look up people by name. Supports "First Last" or just "Last" format.
|
|
577
|
+
|
|
578
|
+
```bash
|
|
579
|
+
dm enrich name "Jane Doe"
|
|
580
|
+
dm enrich name "Doe" --state TX --page 2
|
|
581
|
+
dm enrich name "Jane Doe" --zip 78704 --include-properties
|
|
582
|
+
```
|
|
583
|
+
|
|
584
|
+
| Option | Description |
|
|
585
|
+
| ---------------------- | ----------------------------- |
|
|
586
|
+
| `--state <code>` | Narrow by state |
|
|
587
|
+
| `--zip <code>` | Narrow by ZIP code |
|
|
588
|
+
| `--include-properties` | Include associated properties |
|
|
589
|
+
| `--page <n>` | Page number |
|
|
590
|
+
| `--per-page <n>` | Results per page |
|
|
591
|
+
|
|
592
|
+
---
|
|
593
|
+
|
|
594
|
+
### Comps Commands
|
|
595
|
+
|
|
596
|
+
#### `dm comps [property_ids...]`
|
|
597
|
+
|
|
598
|
+
Find comparable properties (sales comps) for one or more properties.
|
|
599
|
+
|
|
600
|
+
```bash
|
|
601
|
+
# Single property with defaults
|
|
602
|
+
dm comps prop_12345
|
|
603
|
+
|
|
604
|
+
# Multiple properties with options
|
|
605
|
+
dm comps prop_12345 prop_67890 --radius 2 --timeframe 12months --limit 50
|
|
606
|
+
|
|
607
|
+
# Full control via JSON body
|
|
608
|
+
dm comps --body '{
|
|
609
|
+
"property_ids": ["prop_12345"],
|
|
610
|
+
"location": {"type": "radius", "radius_miles": 1.5},
|
|
611
|
+
"criteria": {"timeframe": "6months", "sort_by": "match", "limit": 25}
|
|
612
|
+
}'
|
|
613
|
+
```
|
|
614
|
+
|
|
615
|
+
| Option | Description |
|
|
616
|
+
| ------------------------ | ---------------------------------------------------------- |
|
|
617
|
+
| `--body <json>` | Request body as JSON string |
|
|
618
|
+
| `-f, --file <path>` | Read request body from a JSON file |
|
|
619
|
+
| `--radius <miles>` | Search radius in miles (default: 1) |
|
|
620
|
+
| `--timeframe <period>` | `3months`, `6months`, `12months`, `all` (default: 6months) |
|
|
621
|
+
| `--limit <n>` | Max comps per property (default: 25, max: 100) |
|
|
622
|
+
| `--sort-by <field>` | `distance`, `price`, `date`, `match` (default: match) |
|
|
623
|
+
| `--sort-direction <dir>` | `asc`, `desc` (default: desc) |
|
|
624
|
+
| `--include-foreclosures` | Include foreclosure sales |
|
|
625
|
+
| `--json` | Output as JSON |
|
|
626
|
+
|
|
627
|
+
Output includes subject property details, value estimation with confidence interval, summary statistics (average/median price, price per sqft), and a table of comparable properties.
|
|
628
|
+
|
|
629
|
+
---
|
|
630
|
+
|
|
631
|
+
### Lists Commands
|
|
632
|
+
|
|
633
|
+
#### `dm lists search`
|
|
634
|
+
|
|
635
|
+
Search and list all saved lists.
|
|
636
|
+
|
|
637
|
+
```bash
|
|
638
|
+
dm lists search
|
|
639
|
+
dm lists search --search "Austin" --source-type properties --sort newest
|
|
640
|
+
dm lists search --page 2 --per-page 50 --json
|
|
641
|
+
```
|
|
642
|
+
|
|
643
|
+
| Option | Description |
|
|
644
|
+
| ---------------------- | ----------------------------------- |
|
|
645
|
+
| `--search <term>` | Search lists by name |
|
|
646
|
+
| `--source-type <type>` | `properties` or `people` |
|
|
647
|
+
| `--sort <order>` | `newest`, `oldest`, `name`, `count` |
|
|
648
|
+
| `-p, --page <n>` | Page number |
|
|
649
|
+
| `--per-page <n>` | Results per page |
|
|
650
|
+
|
|
651
|
+
#### `dm lists create`
|
|
652
|
+
|
|
653
|
+
Create a new list.
|
|
654
|
+
|
|
655
|
+
```bash
|
|
656
|
+
# Empty list
|
|
657
|
+
dm lists create --name "Austin Leads"
|
|
658
|
+
|
|
659
|
+
# Pre-populated with record IDs (max 250)
|
|
660
|
+
dm lists create --name "Hot Leads" --source-type properties --ids 123,456,789
|
|
661
|
+
|
|
662
|
+
# With search filters for a list build
|
|
663
|
+
dm lists create --name "TX SFR" -f search-filters.json
|
|
664
|
+
```
|
|
665
|
+
|
|
666
|
+
| Option | Description |
|
|
667
|
+
| ---------------------- | ---------------------------------------------------- |
|
|
668
|
+
| `--name <name>` | List name (required) |
|
|
669
|
+
| `--source-type <type>` | `properties` or `people` |
|
|
670
|
+
| `--ids <csv>` | Comma-separated record IDs to pre-populate (max 250) |
|
|
671
|
+
| `--body <json>` | Request body as JSON (filters/locations) |
|
|
672
|
+
| `-f, --file <path>` | Read request body from a JSON file |
|
|
673
|
+
|
|
674
|
+
#### `dm lists get <id>`
|
|
675
|
+
|
|
676
|
+
Get details of a specific list including status, progress, and error state.
|
|
677
|
+
|
|
678
|
+
```bash
|
|
679
|
+
dm lists get list_abc123
|
|
680
|
+
```
|
|
681
|
+
|
|
682
|
+
#### `dm lists update <id>`
|
|
683
|
+
|
|
684
|
+
Rename a list.
|
|
685
|
+
|
|
686
|
+
```bash
|
|
687
|
+
dm lists update list_abc123 --name "New Name"
|
|
688
|
+
```
|
|
689
|
+
|
|
690
|
+
#### `dm lists delete <id>`
|
|
691
|
+
|
|
692
|
+
Delete a list and all its items.
|
|
693
|
+
|
|
694
|
+
```bash
|
|
695
|
+
dm lists delete list_abc123
|
|
696
|
+
```
|
|
697
|
+
|
|
698
|
+
#### `dm lists build <id>`
|
|
699
|
+
|
|
700
|
+
Build a list from search filters. This is an asynchronous operation -- poll with `dm lists get` for status.
|
|
701
|
+
|
|
702
|
+
```bash
|
|
703
|
+
dm lists build list_abc123 -f search-filters.json
|
|
704
|
+
```
|
|
705
|
+
|
|
706
|
+
#### `dm lists import <id>`
|
|
707
|
+
|
|
708
|
+
Import record IDs into an existing list.
|
|
709
|
+
|
|
710
|
+
```bash
|
|
711
|
+
dm lists import list_abc123 --ids 111,222,333 --source-type properties
|
|
712
|
+
dm lists import list_abc123 -f import-payload.json
|
|
713
|
+
```
|
|
714
|
+
|
|
715
|
+
#### `dm lists items <id>`
|
|
716
|
+
|
|
717
|
+
List items in a list with pagination.
|
|
718
|
+
|
|
719
|
+
```bash
|
|
720
|
+
dm lists items list_abc123
|
|
721
|
+
dm lists items list_abc123 --page 2 --per-page 100 --json
|
|
722
|
+
```
|
|
723
|
+
|
|
724
|
+
#### `dm lists add <id>`
|
|
725
|
+
|
|
726
|
+
Add items to a list by ID.
|
|
727
|
+
|
|
728
|
+
```bash
|
|
729
|
+
dm lists add list_abc123 --ids 111,222,333
|
|
730
|
+
dm lists add list_abc123 --ids 111,222 --id-type internal_property_id
|
|
731
|
+
```
|
|
732
|
+
|
|
733
|
+
| Option | Description |
|
|
734
|
+
| ------------------ | ---------------------------------------------- |
|
|
735
|
+
| `--ids <csv>` | Comma-separated list of IDs to add (required) |
|
|
736
|
+
| `--id-type <type>` | `internal_property_id` or `internal_person_id` |
|
|
737
|
+
|
|
738
|
+
#### `dm lists remove <id>`
|
|
739
|
+
|
|
740
|
+
Remove items from a list by ID.
|
|
741
|
+
|
|
742
|
+
```bash
|
|
743
|
+
dm lists remove list_abc123 --ids 111,222,333
|
|
744
|
+
```
|
|
745
|
+
|
|
746
|
+
#### `dm lists export <id>`
|
|
747
|
+
|
|
748
|
+
Export list items. Credits are charged per record.
|
|
749
|
+
|
|
750
|
+
```bash
|
|
751
|
+
dm lists export list_abc123
|
|
752
|
+
dm lists export list_abc123 --fields "full_address,estimated_value,owner_name" --anchor property
|
|
753
|
+
```
|
|
754
|
+
|
|
755
|
+
| Option | Description |
|
|
756
|
+
| ----------------- | ---------------------------------------- |
|
|
757
|
+
| `--fields <csv>` | Comma-separated list of fields to export |
|
|
758
|
+
| `--anchor <type>` | `property` or `person` |
|
|
759
|
+
|
|
760
|
+
---
|
|
761
|
+
|
|
762
|
+
### Filters Commands
|
|
763
|
+
|
|
764
|
+
#### `dm filters`
|
|
765
|
+
|
|
766
|
+
List available search filters with their types, operators, and groupings.
|
|
767
|
+
|
|
768
|
+
```bash
|
|
769
|
+
dm filters
|
|
770
|
+
dm filters --source-type properties --search "bed"
|
|
771
|
+
dm filters --group-id building_information --json
|
|
772
|
+
```
|
|
773
|
+
|
|
774
|
+
| Option | Description |
|
|
775
|
+
| ---------------------- | ------------------------ |
|
|
776
|
+
| `--source-type <type>` | `properties` or `people` |
|
|
777
|
+
| `--group-id <id>` | Filter by group ID |
|
|
778
|
+
| `--search <term>` | Search filters by name |
|
|
779
|
+
| `--page <n>` | Page number |
|
|
780
|
+
| `--per-page <n>` | Results per page |
|
|
781
|
+
|
|
782
|
+
---
|
|
783
|
+
|
|
784
|
+
### Fields Commands
|
|
785
|
+
|
|
786
|
+
#### `dm fields`
|
|
787
|
+
|
|
788
|
+
List available data fields with filterable/sortable flags.
|
|
789
|
+
|
|
790
|
+
```bash
|
|
791
|
+
dm fields
|
|
792
|
+
dm fields --source-type people --search "phone"
|
|
793
|
+
dm fields --group-id contact_info --json
|
|
794
|
+
```
|
|
795
|
+
|
|
796
|
+
| Option | Description |
|
|
797
|
+
| ---------------------- | ------------------------ |
|
|
798
|
+
| `--source-type <type>` | `properties` or `people` |
|
|
799
|
+
| `--group-id <id>` | Filter by group ID |
|
|
800
|
+
| `--search <term>` | Search fields by name |
|
|
801
|
+
| `--page <n>` | Page number |
|
|
802
|
+
| `--per-page <n>` | Results per page |
|
|
803
|
+
|
|
804
|
+
---
|
|
805
|
+
|
|
806
|
+
### Activity Commands
|
|
807
|
+
|
|
808
|
+
#### `dm activity search`
|
|
809
|
+
|
|
810
|
+
Search past API activity with type filters and free-text search.
|
|
811
|
+
|
|
812
|
+
```bash
|
|
813
|
+
dm activity search -t search_properties enrich_address
|
|
814
|
+
dm activity search -q "Austin" --page 2
|
|
815
|
+
dm activity search --body '{"types": ["search_properties"], "page": 1}'
|
|
816
|
+
```
|
|
817
|
+
|
|
818
|
+
| Option | Description |
|
|
819
|
+
| ------------------------ | ------------------------------------------ |
|
|
820
|
+
| `--body <json>` | Request body as JSON string |
|
|
821
|
+
| `-f, --file <path>` | Read request body from a JSON file |
|
|
822
|
+
| `-t, --types <types...>` | Filter by activity types (space-separated) |
|
|
823
|
+
| `-q, --query <text>` | Free-text search across activity |
|
|
824
|
+
| `--page <n>` | Page number |
|
|
825
|
+
| `--per-page <n>` | Results per page |
|
|
826
|
+
|
|
827
|
+
#### `dm activity get <id>`
|
|
828
|
+
|
|
829
|
+
Get full details of a specific activity record, including the original request, result summary, and entity IDs (people and properties).
|
|
830
|
+
|
|
831
|
+
```bash
|
|
832
|
+
dm activity get act_abc123
|
|
833
|
+
dm activity get act_abc123 --json
|
|
834
|
+
```
|
|
835
|
+
|
|
836
|
+
---
|
|
837
|
+
|
|
838
|
+
### Addresses Commands
|
|
839
|
+
|
|
840
|
+
#### `dm addresses validate [address]`
|
|
841
|
+
|
|
842
|
+
Validate and standardize addresses via USPS.
|
|
843
|
+
|
|
844
|
+
```bash
|
|
845
|
+
# Single address
|
|
846
|
+
dm addresses validate "123 Main St, Austin, TX 78704"
|
|
847
|
+
|
|
848
|
+
# Batch via JSON
|
|
849
|
+
dm addresses validate --body '{"data": [{"full_address": "123 Main St, Austin TX"}]}'
|
|
850
|
+
|
|
851
|
+
# From file
|
|
852
|
+
dm addresses validate -f addresses.json --json
|
|
853
|
+
```
|
|
854
|
+
|
|
855
|
+
Output shows each address as valid, corrected (with corrections listed), or invalid (with reason).
|
|
856
|
+
|
|
857
|
+
---
|
|
858
|
+
|
|
859
|
+
### Dev Commands
|
|
860
|
+
|
|
861
|
+
Local 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).
|
|
862
|
+
|
|
863
|
+
#### `dm dev license add <key_id>`
|
|
864
|
+
|
|
865
|
+
Add a license to an API key in the local database.
|
|
866
|
+
|
|
867
|
+
```bash
|
|
868
|
+
dm dev license add key_abc123 --type state --code TX
|
|
869
|
+
dm dev license add key_abc123 --type zip_code --code 78704
|
|
870
|
+
dm dev license add key_abc123 --type unlimited
|
|
871
|
+
dm dev license add key_abc123 --type county --code 48453 --expires 2026-12-31
|
|
872
|
+
```
|
|
873
|
+
|
|
874
|
+
| Option | Description |
|
|
875
|
+
| ------------------ | -------------------------------------------------------- |
|
|
876
|
+
| `--type <type>` | `state`, `county`, `zip_code`, or `unlimited` (required) |
|
|
877
|
+
| `--code <code>` | Location code: state abbreviation, FIPS code, or ZIP |
|
|
878
|
+
| `--expires <date>` | Expiration date in ISO format |
|
|
879
|
+
|
|
880
|
+
#### `dm dev license list [key_id]`
|
|
881
|
+
|
|
882
|
+
List all licenses, optionally filtered by key ID.
|
|
883
|
+
|
|
884
|
+
```bash
|
|
885
|
+
dm dev license list
|
|
886
|
+
dm dev license list key_abc123
|
|
887
|
+
```
|
|
888
|
+
|
|
889
|
+
#### `dm dev license remove <license_id>`
|
|
890
|
+
|
|
891
|
+
Remove a license by its numeric ID.
|
|
892
|
+
|
|
893
|
+
```bash
|
|
894
|
+
dm dev license remove 42
|
|
895
|
+
```
|
|
896
|
+
|
|
897
|
+
---
|
|
898
|
+
|
|
899
|
+
## Global Options
|
|
900
|
+
|
|
901
|
+
Every command supports these flags:
|
|
902
|
+
|
|
903
|
+
| Flag | Description |
|
|
904
|
+
| ----------- | ---------------------------------------------------------- |
|
|
905
|
+
| `--json` | Output as machine-readable JSON (for scripting and piping) |
|
|
906
|
+
| `--quiet` | Suppress spinners and decorative output for agents/scripts |
|
|
907
|
+
| `--help` | Show usage information for any command |
|
|
908
|
+
| `--version` | Show the CLI version |
|
|
909
|
+
|
|
910
|
+
---
|
|
911
|
+
|
|
912
|
+
## Input Methods
|
|
913
|
+
|
|
914
|
+
Commands that accept a request body support three input methods, checked in this order:
|
|
915
|
+
|
|
916
|
+
1. **`--body <json>`** -- Inline JSON string.
|
|
917
|
+
2. **`-f, --file <path>`** -- Read from a JSON file. Enrichment commands also accept `.csv` files for batch processing.
|
|
918
|
+
3. **Stdin pipe** -- Read JSON from piped input (detected when stdin is not a TTY).
|
|
919
|
+
|
|
920
|
+
```bash
|
|
921
|
+
# Inline
|
|
922
|
+
dm properties search --body '{"locations": [...]}'
|
|
923
|
+
|
|
924
|
+
# File
|
|
925
|
+
dm properties search -f query.json
|
|
926
|
+
|
|
927
|
+
# Pipe
|
|
928
|
+
cat query.json | dm properties search
|
|
929
|
+
|
|
930
|
+
# CSV enrichment (enrich commands only)
|
|
931
|
+
dm enrich address -f addresses.csv
|
|
932
|
+
```
|
|
933
|
+
|
|
934
|
+
### CSV Batch Enrichment
|
|
935
|
+
|
|
936
|
+
The `enrich` commands detect `.csv` files by extension and auto-parse them. Expected column names per command:
|
|
937
|
+
|
|
938
|
+
| Command | Required Columns | Alternative Column Names |
|
|
939
|
+
| ---------------- | ----------------------- | ------------------------------------ |
|
|
940
|
+
| `enrich address` | `full_address` | or `street` + `city`, `state`, `zip` |
|
|
941
|
+
| `enrich latlng` | `latitude`, `longitude` | `lat`, `lng`/`lon`/`long` |
|
|
942
|
+
| `enrich apn` | `apn` | `parcel_id`, `parcel_number` |
|
|
943
|
+
| `enrich email` | `email` | `email_address` |
|
|
944
|
+
| `enrich phone` | `phone` | `phone_number` |
|
|
945
|
+
|
|
946
|
+
Batches 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.
|
|
947
|
+
|
|
948
|
+
---
|
|
949
|
+
|
|
950
|
+
## Project Structure
|
|
951
|
+
|
|
952
|
+
```
|
|
953
|
+
packages/cli/
|
|
954
|
+
scripts/
|
|
955
|
+
copy-agent-assets.mjs # Bundles the Playbook Markdown into dist/agents
|
|
956
|
+
src/
|
|
957
|
+
index.ts # Program entrypoint -- registers all 17 command groups
|
|
958
|
+
lib/
|
|
959
|
+
config.ts # Read/write ~/.dealmachine/config.json (mode 0600)
|
|
960
|
+
client.ts # HTTP client wrapper (apiRequest, formatDate, getApiKey)
|
|
961
|
+
api.ts # Device auth flow client (requestDeviceCode, pollForToken, verifyCredentials)
|
|
962
|
+
output.ts # Formatting helpers (printTable, printJson, printKeyValue, parseRequestBody)
|
|
963
|
+
commands/
|
|
964
|
+
agents.ts # dm agents -- agent guide and Playbook output
|
|
965
|
+
login.ts # dm login -- device auth + API key login
|
|
966
|
+
logout.ts # dm logout -- remove credentials
|
|
967
|
+
whoami.ts # dm whoami -- show/verify auth status
|
|
968
|
+
config.ts # dm config -- get, set, path
|
|
969
|
+
account.ts # dm account -- show account info
|
|
970
|
+
usage.ts # dm usage -- credit usage
|
|
971
|
+
properties.ts # dm properties -- search, count, get, ids, export
|
|
972
|
+
people.ts # dm people -- search, count, get, ids, export
|
|
973
|
+
enrich.ts # dm enrich -- address, latlng, apn, email, phone, name
|
|
974
|
+
comps.ts # dm comps -- comparable properties
|
|
975
|
+
lists.ts # dm lists -- full CRUD + build, import, export
|
|
976
|
+
filters.ts # dm filters -- list available filters
|
|
977
|
+
fields.ts # dm fields -- list available fields
|
|
978
|
+
activity.ts # dm activity -- search, get
|
|
979
|
+
addresses.ts # dm addresses -- validate
|
|
980
|
+
dev.ts # dm dev -- local license management
|
|
981
|
+
dist/ # Compiled output (ESM)
|
|
982
|
+
package.json
|
|
983
|
+
tsconfig.json
|
|
984
|
+
```
|
|
985
|
+
|
|
986
|
+
### Key Modules
|
|
987
|
+
|
|
988
|
+
| Module | Responsibility |
|
|
989
|
+
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
990
|
+
| `lib/config.ts` | Manages `~/.dealmachine/config.json`. Enforces `0600` file permissions and `0700` directory permissions. Provides typed read/write/delete helpers. |
|
|
991
|
+
| `lib/client.ts` | Central HTTP client. Resolves the API base URL from env vars, config, or defaults. Attaches the `Authorization: Bearer` header and `User-Agent: dm-cli/0.1.0`. Exits with a non-zero code on HTTP errors. |
|
|
992
|
+
| `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. |
|
|
993
|
+
| `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. |
|
|
994
|
+
|
|
995
|
+
---
|
|
996
|
+
|
|
997
|
+
## Building
|
|
998
|
+
|
|
999
|
+
```bash
|
|
1000
|
+
npm run build # Compile TypeScript and bundle agent Playbook assets to dist/
|
|
1001
|
+
npm run dev # Watch mode (tsc --watch)
|
|
1002
|
+
```
|
|
1003
|
+
|
|
1004
|
+
### Standalone Binary
|
|
1005
|
+
|
|
1006
|
+
The 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.
|
|
1007
|
+
|
|
1008
|
+
For distribution as a standalone binary without npm:
|
|
1009
|
+
|
|
1010
|
+
```bash
|
|
1011
|
+
# Build
|
|
1012
|
+
cd packages/cli
|
|
1013
|
+
npm run build
|
|
1014
|
+
|
|
1015
|
+
# The entire dist/ directory is the distributable artifact
|
|
1016
|
+
# dist/index.js is the entrypoint (requires Node.js >= 18 on the target machine)
|
|
1017
|
+
```
|
|
1018
|
+
|
|
1019
|
+
The `files` array in `package.json` ensures only `dist/` is included in the published package.
|
|
1020
|
+
|
|
1021
|
+
### TypeScript Configuration
|
|
1022
|
+
|
|
1023
|
+
- Target: ES2022
|
|
1024
|
+
- Module: NodeNext (ESM)
|
|
1025
|
+
- Strict mode enabled
|
|
1026
|
+
- Outputs declarations, declaration maps, and source maps
|
|
1027
|
+
- No project references (standalone compilation)
|
|
1028
|
+
|
|
1029
|
+
---
|
|
1030
|
+
|
|
1031
|
+
## Adding New Commands
|
|
1032
|
+
|
|
1033
|
+
### Step 1: Create the command file
|
|
1034
|
+
|
|
1035
|
+
Create `src/commands/mycommand.ts`:
|
|
1036
|
+
|
|
1037
|
+
```typescript
|
|
1038
|
+
/**
|
|
1039
|
+
* MyCommand -- description of what this command does
|
|
1040
|
+
*/
|
|
1041
|
+
|
|
1042
|
+
import chalk from 'chalk';
|
|
1043
|
+
import ora from 'ora';
|
|
1044
|
+
import { apiRequest } from '../lib/client.js';
|
|
1045
|
+
import { printJson, printHeader, printKeyValue } from '../lib/output.js';
|
|
1046
|
+
|
|
1047
|
+
interface MyResponse {
|
|
1048
|
+
data: { id: string; name: string };
|
|
1049
|
+
}
|
|
1050
|
+
|
|
1051
|
+
export async function myCommand(options: { json?: boolean }): Promise<void> {
|
|
1052
|
+
const spinner = ora('Doing something...').start();
|
|
1053
|
+
const data = await apiRequest<MyResponse>('/my-endpoint');
|
|
1054
|
+
spinner.stop();
|
|
1055
|
+
|
|
1056
|
+
if (options.json) {
|
|
1057
|
+
printJson(data);
|
|
1058
|
+
return;
|
|
1059
|
+
}
|
|
1060
|
+
|
|
1061
|
+
printHeader('My Command');
|
|
1062
|
+
printKeyValue({
|
|
1063
|
+
ID: data.data.id,
|
|
1064
|
+
Name: data.data.name,
|
|
1065
|
+
});
|
|
1066
|
+
console.log();
|
|
1067
|
+
}
|
|
1068
|
+
```
|
|
1069
|
+
|
|
1070
|
+
### Step 2: Register in index.ts
|
|
1071
|
+
|
|
1072
|
+
Import and wire up the command in `src/index.ts`:
|
|
1073
|
+
|
|
1074
|
+
```typescript
|
|
1075
|
+
import { myCommand } from './commands/mycommand.js';
|
|
1076
|
+
|
|
1077
|
+
// Top-level command
|
|
1078
|
+
program
|
|
1079
|
+
.command('mycommand')
|
|
1080
|
+
.description('Description shown in --help')
|
|
1081
|
+
.option('--json', 'Output as JSON')
|
|
1082
|
+
.action(async (options) => {
|
|
1083
|
+
await myCommand(options);
|
|
1084
|
+
});
|
|
1085
|
+
|
|
1086
|
+
// Or as a subcommand group
|
|
1087
|
+
const myGroup = program.command('mygroup').description('Group description');
|
|
1088
|
+
|
|
1089
|
+
myGroup
|
|
1090
|
+
.command('sub1')
|
|
1091
|
+
.description('Subcommand description')
|
|
1092
|
+
.action(async (options) => {
|
|
1093
|
+
await mySub1(options);
|
|
1094
|
+
});
|
|
1095
|
+
```
|
|
1096
|
+
|
|
1097
|
+
### Step 3: Build and test
|
|
1098
|
+
|
|
1099
|
+
```bash
|
|
1100
|
+
npm run build
|
|
1101
|
+
node dist/index.js mycommand --json
|
|
1102
|
+
```
|
|
1103
|
+
|
|
1104
|
+
### Conventions
|
|
1105
|
+
|
|
1106
|
+
- One file per command group in `src/commands/`.
|
|
1107
|
+
- Always support `--json` for machine-readable output.
|
|
1108
|
+
- Use `ora` for spinners during API calls.
|
|
1109
|
+
- Use `chalk` for colored terminal output.
|
|
1110
|
+
- Use `apiRequest<T>` from `lib/client.ts` for all API calls -- it handles auth, errors, and exits.
|
|
1111
|
+
- Use `parseRequestBody` from `lib/output.ts` when the command accepts `--body`, `-f`, or stdin input.
|
|
1112
|
+
- Use `printHeader`, `printTable`, `printKeyValue`, `printCredits`, `printPagination` for consistent output formatting.
|
|
1113
|
+
- All imports must use the `.js` extension (ESM requirement with NodeNext resolution).
|
|
1114
|
+
|
|
1115
|
+
---
|
|
1116
|
+
|
|
1117
|
+
## Dependencies
|
|
1118
|
+
|
|
1119
|
+
### Runtime
|
|
1120
|
+
|
|
1121
|
+
| Package | Version | Purpose |
|
|
1122
|
+
| ----------- | ------- | ---------------------------------------------------------------------- |
|
|
1123
|
+
| `commander` | ^12.1.0 | CLI framework -- command registration, option parsing, help generation |
|
|
1124
|
+
| `chalk` | ^5.3.0 | Terminal string styling (colors, bold, dim) |
|
|
1125
|
+
| `ora` | ^8.1.0 | Spinner animations for async operations |
|
|
1126
|
+
| `open` | ^10.1.0 | Opens the browser for the device auth flow |
|
|
1127
|
+
|
|
1128
|
+
### Dev
|
|
1129
|
+
|
|
1130
|
+
| Package | Version | Purpose |
|
|
1131
|
+
| ------------- | ------- | ------------------------ |
|
|
1132
|
+
| `typescript` | ^5.6.3 | TypeScript compiler |
|
|
1133
|
+
| `@types/node` | ^22.0.0 | Node.js type definitions |
|
|
1134
|
+
|
|
1135
|
+
### Internal Package Dependencies
|
|
1136
|
+
|
|
1137
|
+
**None.** This package is a fully standalone binary with zero `@dealmachine/*` dependencies. It communicates exclusively through the public REST API.
|
|
1138
|
+
|
|
1139
|
+
### Used By
|
|
1140
|
+
|
|
1141
|
+
The **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`.
|