DealMachine

Inteligencia de propiedades, propietarios, personas y empresas para ventas inmobiliarias, marketing, prospección, enriquecimiento y generación de leads.

GitHubPrueba este MCPPatrocinado

Documentación

CLI de DealMachine

Mantenedores: instrucciones para agentes, desarrollo, referencia actual de comandos y publicaciones npm.

CLI de DealMachine (dm) -- inteligencia inmobiliaria desde la línea de comandos.

Una CLI independiente basada en Commander.js que se comunica con la API REST de DealMachine. Proporciona comandos para autenticación, investigación de propiedades y personas, enriquecimiento, listas, prospectos, etiquetas, webhooks, correo y utilidades para desarrolladores. Se compila a JavaScript ESM mediante tsc.

Este paquete tiene cero dependencias de @dealmachine/* -- es un binario autocontenido que se comunica exclusivamente a través de la API pública.

Integraciones con agentes de IA

Este repositorio también es el paquete de distribución pública para el servidor MCP de DealMachine y la skill de DealMachine.

Servidor MCP alojado: https://mcp.dealmachine.com
Documentación de la API: https://api.docs.dealmachine.com
Cuenta y claves de API: https://dealmachine.com/settings/developer
Política de privacidad: https://dealmachine.com/privacy-policy
Términos de servicio: https://dealmachine.com/terms-of-service
Soporte: support@dealmachine.com

El servidor MCP admite OAuth 2.1 para ChatGPT, Claude, Cursor, Codex y otros clientes compatibles. También puede usar una clave de API de DealMachine en clientes de desarrollo que admitan configuración de token portador.

El paquete del plugin incluye:

Una conexión MCP alojada para herramientas de propiedades, personas, enriquecimiento, ventas comparables y cuenta
Una skill consciente de créditos que descubre filtros y campos, cuenta primero y confirma operaciones pagadas de gran volumen
Un paquete portátil de Agent Plugins para clientes compatibles
Manifiestos para OpenAI, Claude, Cursor, GitHub Copilot y Gemini
Metadatos oficiales del Registro MCP en server.json

El paquete portátil sigue Agent Plugins 1.0.0:

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

Los clientes compatibles descubren la skill de DealMachine desde skills/dealmachine/ y se conectan al servidor MCP alojado Streamable HTTP declarado en mcp.json. Los manifiestos específicos de cada cliente permanecen en el repositorio por compatibilidad, metadatos de marketplace y una presentación más rica.

Ejemplos de solicitudes:

"Encuentra propiedades de alto patrimonio con propietarios ausentes en Austin y estima primero el costo de créditos."
"Busca al propietario de esta propiedad y encuentra datos de contacto disponibles."
"Encuentra ventas comparables para esta propiedad."
"Investiga personas que coincidan con estos criterios para una lista de prospección dirigida."

Instalación directa de la skill:

npx skills add DealMachine/dealmachine-cli

Tabla de Contenidos

Integraciones con agentes de IA
Instalación
Autenticación
Configuración
Comandos
- Agents -- agents, agents guide, agents playbook, agents install, agents permissions
- Auth -- login, logout, whoami
- Config -- config get, config set, config path
- Account -- account
- Usage -- usage
- Properties -- search, count, get, ids, export
- People -- search, count, get, ids, export
- Enrich -- address, latlng, apn, email, phone, name
- Comps -- análisis de propiedades comparables
- Lists -- search, create, get, update, delete, build, import, items, add, remove, export
- Filters -- lista los filtros de búsqueda disponibles
- Fields -- lista los campos de datos disponibles
- Activity -- search, get
- Addresses -- autocomplete, validate
- Dev -- license add, license list, license remove
Opciones Globales
Métodos de Entrada
Estructura del Proyecto
Compilación
Agregar Nuevos Comandos
Dependencias

Instalación

Desde npm (global)

npm install -g dealmachine
dm login

El paquete de implementación canónico es @dealmachine/cli. El paquete dealmachine es el alias corto de instalación y proporciona el mismo comando dm.

Desde el código fuente

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

Enlace para desarrollo local

cd dealmachine-cli
npm link
dm --version

La entrada binaria es dist/index.js, declarada en package.json bajo bin.dm. Requiere Node.js >= 18.

Autenticación

La CLI admite dos métodos de autenticación.

Flujo de Autenticación de Dispositivo (RFC 8628)

El comando predeterminado dm login usa la Concesión de Autorización de Dispositivo OAuth 2.0 (RFC 8628). Este es el flujo recomendado para uso interactivo:

dm login

La CLI solicita un código de dispositivo a POST /v1/auth/device/code con el ID de cliente dealmachine-next-cli y el nombre de host de tu máquina.
Se muestran una URL de verificación y un código de usuario. El navegador se abre automáticamente (a menos que --no-browser).
Autorizas el dispositivo en el navegador ingresando el código de usuario.
La CLI consulta POST /v1/auth/device/token en el intervalo especificado por el servidor.
Al tener éxito, la clave de API, el ID de clave y los detalles de la organización se almacenan en ~/.dealmachine/config.json.

La consulta maneja todas las respuestas RFC 8628: authorization_pending, slow_down (espera 5s adicionales), access_denied y expired_token.

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

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

Inicio de Sesión Directo con Clave de API

Para pipelines de CI, scripts o desarrollo local, pasa una clave de API directamente:

dm login --key dm_sk_live_abc123...

La clave se verifica contra GET /v1/account antes de almacenarse. Si la verificación falla, la CLI sale con un código distinto de cero.

Si aún no tienes una clave de API, usa dm signup, dm plans y dm checkout primero. El checkout del plan público solo acepta planes Basic y Pro de autoservicio del catálogo de planes compartido y está limitado a 60,000 créditos de datos mensuales.

Cambio de Entornos

Si ya has iniciado sesión, puedes cambiar el entorno de API de destino sin cerrar sesión:

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

Cerrar Sesión

dm logout

Elimina el archivo de configuración en ~/.dealmachine/config.json.

Configuración

Las credenciales se almacenan en ~/.dealmachine/config.json con permisos de archivo 0600 (solo lectura/escritura del propietario). El directorio de configuración ~/.dealmachine/ se crea con modo 0700.

Esquema del Archivo de Configuración

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

Variables de Entorno

La CLI verifica estas variables de entorno para la resolución de la URL de la API (en orden de prioridad):

Variable	Propósito	Ejemplo
`DM_API_URL` / `DEALMACHINE_API_URL`	Anulación directa de URL	`http://localhost:3001/v1`
`DM_ENV` / `DEALMACHINE_ENVIRONMENT`	Nombre del entorno	`local`, `staging` o `production`

Si no se establece ninguna, la CLI recurre al campo apiEnvironment en el archivo de configuración y luego al valor predeterminado production.

Entornos de API

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

Comandos

Comandos de Agents

`dm agents`

Imprime orientación concisa para agentes que usan la CLI. Este es el primer comando recomendado cuando un agente tiene acceso a dm pero aún no ha cargado el Playbook de DealMachine.

dm agents
dm agents --json

La guía indica a los agentes usar --json y --quiet, verificar la autenticación, obtener filtros y campos en vivo antes de las búsquedas, contar antes del trabajo que consume créditos y confirmar el uso esperado de créditos antes de obtener registros o exportar.

`dm agents guide`

Imprime la misma orientación concisa para agentes de forma explícita.

dm agents guide
dm agents guide --json

`dm agents playbook`

Imprime el Playbook de DealMachine en Markdown incluido. Los agentes deben cargar esto antes de traducir solicitudes en lenguaje natural sobre propiedades, personas, contactos, enriquecimiento, listas, exportación, comparables o uso de créditos en comandos de la CLI.

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

El código fuente público de la CLI mantiene su Playbook incluido en playbook/PLAYBOOK.md. La compilación escribe la fuente seleccionada en dist/agents/dealmachine-playbook.md, por lo que el comando funciona tanto desde un paquete CLI publicado como desde una copia local del código fuente.

`dm agents install claude-code`

Instala el Playbook como una skill nativa de Claude Code. El ámbito personal es el predeterminado. El ámbito de proyecto se instala en el repositorio actual.

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

`dm agents permissions`

Imprime la lista de permitidos estrecha de Claude Code para comandos gratuitos de descubrimiento y conteo. Los comandos pagados y de mutación no están preaprobados.

dm agents permissions
dm agents permissions --json

Comandos de Auth

`dm signup`

Crea una cuenta de API pública y recibe una clave de API:

dm signup developer@example.com --first-name Ada --last-name Lovelace --phone-number +15551234567
dm signup developer@example.com --login

`dm plans`

Lista los planes Basic y Pro públicos de autoservicio:

dm plans
dm plans --json

`dm checkout`

Crea una sesión de checkout de Stripe usando un ID de precio de dm plans:

dm checkout --price-id price_xxx_monthly

`dm login`

Autentícate con tu cuenta de 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

Opción	Descripción
`--no-browser`	No abrir el navegador automáticamente
`--key <api-key>`	Iniciar sesión directamente con una clave de API (omite el navegador)
`--env <environment>`	Entorno de API: `local`, `staging` o `production`

`dm logout`

Elimina las credenciales almacenadas.

dm logout

`dm whoami`

Muestra el estado actual de autenticación.

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

Opción	Descripción
`--verify`	Verificar credenciales con la API

Comandos de Config

`dm config get [key]`

Obtiene un valor de configuración, o muestra todos los valores cuando no se proporciona una clave.

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

Claves disponibles: organizationName, organizationSlug, organizationId, apiEnvironment, keyId, apiKey.

`dm config set <key> <value>`

Establece un valor de configuración. Solo apiEnvironment es editable.

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

`dm config path`

Imprime la ruta absoluta al archivo de configuración.

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

Comandos de Account

`dm account`

Muestra información de la cuenta, incluidos el nombre de la organización, ID, fecha de creación y tipo de autenticación.

dm account

Salida:

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

Comandos de Usage

`dm usage`

Muestra el uso de créditos para el ciclo de facturación actual.

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

Salida:

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

Comandos de Properties

`dm properties search`

Busca propiedades con filtros y ubicaciones.

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

Opción	Descripción
`--body <json>`	Cuerpo de la solicitud como cadena JSON
`-f, --file <path>`	Leer el cuerpo de la solicitud desde un archivo JSON
`--include-lists <ids>`	Lista de IDs separados por comas para incluir
`--exclude-lists <ids>`	Lista de IDs separados por comas para excluir
`--exclude-previously-exported`	Excluir registros ya exportados por tu organización
`--bigquery-data-environment <n>`	Entorno de datos de Query Builder (`1` producción, `2` staging, `3` desarrollo)
`--estimate-cost`	Vista previa de conteos y costo de créditos sin consumir créditos
`--yes`	Confirmar gasto de créditos aprobado para ejecución no interactiva
`--json`	Salida como JSON

`dm properties count`

Contar propiedades que coinciden con los filtros sin consumir créditos.

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

`dm properties get <id>`

Obtener una sola propiedad por su ID de DealMachine.

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

Opción	Descripción
`--contact-audience <audience>`	`owners`, `owners_and_family`, `renters`, `residents`, `all`, `none`
`--fields <csv>`	IDs de campos de propiedad separados por comas de `dm fields`
`--json`	Salida como JSON

La búsqueda de propiedades usa owners por defecto. Si solo necesitas datos de la propiedad, usa --contact-audience none. Esto omite contactos y evita créditos de personas.

`dm properties ids [ids...]`

Obtener múltiples propiedades por sus IDs en una sola solicitud por lotes.

# 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

Opción	Descripción
`--body <json>`	Cuerpo de la solicitud como cadena JSON
`-f, --file <path>`	Leer el cuerpo de la solicitud desde un archivo JSON
`--contact-audience <audience>`	Incluir contactos: `owners`, `owners_and_family`, `renters`, `residents`, `all`, `none`
`--json`	Salida como JSON

`dm properties export`

Exportar propiedades como CSV (hasta 1,000,000 de registros). Devuelve URLs de descarga firmadas.

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

Opción	Descripción
`--body <json>`	Cuerpo de la solicitud como cadena JSON
`-f, --file <path>`	Leer el cuerpo de la solicitud desde un archivo JSON
`--require-phone`	Incluir solo registros donde el contacto tiene un número de teléfono
`--require-email`	Incluir solo registros donde el contacto tiene una dirección de correo electrónico
`--mobile-only`	Incluir solo números de teléfono inalámbricos
`--landline-only`	Incluir solo números de teléfono fijos
`--scrub-dnc`	Excluir contactos en el registro de No Llamar
`--json`	Salida como JSON

Comandos de Personas

`dm people search`

Buscar personas con filtros y ubicaciones.

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

La Búsqueda de Personas no interactiva devuelve una estimación gratuita a menos que se proporcione --yes. Una persona específica por nombre usa dm enrich name, no la Búsqueda de Personas.

`dm people count`

Contar personas que coinciden con los filtros sin consumir créditos.

dm people count -f filters.json

`dm people get <id>`

Obtener una sola persona por su ID de DealMachine.

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

Opción	Descripción
`--include-properties`	Incluir propiedades asociadas
`--property-limit <n>`	Máximo de propiedades asociadas a devolver, de 1 a 100
`--fields <csv>`	IDs de campos separados por comas de `dm fields`
`--json`	Salida como JSON

`dm people ids [ids...]`

Obtener múltiples personas por sus IDs en una sola solicitud por lotes.

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

Opción	Descripción
`--include-properties`	Incluir propiedades asociadas
`--property-limit <n>`	Máximo de propiedades asociadas a devolver por persona, hasta 100
`--fields <csv>`	IDs de campos separados por comas de `dm fields`

`dm people export`

Exportar personas como CSV (hasta 1,000,000 de registros). Devuelve URLs de descarga firmadas.

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

Las opciones de filtro de contacto son las mismas que dm properties export.

Comandos de Enriquecimiento

Todos los comandos de enriquecimiento admiten tres modos de entrada: un argumento posicional para búsqueda de un solo elemento, --body/-f para cargas útiles JSON, y -f con un archivo .csv para enriquecimiento por lotes desde CSV. Los lotes de más de 250 elementos se dividen automáticamente en fragmentos. Cada comando de enriquecimiento acepta --fields <csv> y envía los IDs de campos seleccionados a la API. Las coincidencias de correo electrónico, teléfono y nombre también incluyen un property_count gratuito; usa --include-properties cuando necesites los registros de propiedad en sí.

`dm enrich address [address]`

Buscar una propiedad por dirección de calle.

# 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)

Opción	Descripción
`--body <json>`	Cuerpo de la solicitud como cadena JSON
`-f, --file <path>`	Leer desde archivo JSON o CSV
`--contact-audience <audience>`	`owners`, `owners_and_family`, `renters`, `residents`, `none`
`--fields <csv>`	IDs de campos separados por comas de `dm fields`
`--json`	Salida como JSON

Usa --contact-audience none siempre que solo necesites la propiedad. La respuesta omite contactos y consume cero créditos de personas.

`dm enrich latlng [coords]`

Buscar una propiedad por coordenadas de latitud/longitud.

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]`

Buscar una propiedad por Número de Parcela del Tasador. Reduce los resultados con --state o --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)

Opción	Descripción
`--state <code>`	Reducir por estado (p. ej., TX)
`--zip <code>`	Reducir por código postal
`--contact-audience <audience>`	`owners`, `owners_and_family`, `renters`, `residents`, `none`
`--fields <csv>`	IDs de campos separados por comas de `dm fields`

`dm enrich email [email]`

Buscar una persona por dirección de correo electrónico.

dm enrich email jane@example.com
dm enrich email jane@example.com --include-properties
dm enrich email -f emails.csv --fields estimated_household_income,estimated_value --json
# CSV columns: email (or email_address)

Opción	Descripción
`--include-properties`	Incluir propiedades asociadas
`--fields <csv>`	IDs de campos separados por comas de `dm fields`

`dm enrich phone [phone]`

Buscar una persona por número de teléfono.

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

Opción	Descripción
`--include-properties`	Incluir propiedades asociadas
`--fields <csv>`	IDs de campos separados por comas de `dm fields`

`dm enrich name [name]`

Buscar personas por nombre. Admite formato "Nombre Apellido" o solo "Apellido".

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

Opción	Descripción
`--state <code>`	Reducir por estado
`--zip <code>`	Reducir por código postal
`--include-properties`	Incluir propiedades asociadas
`--fields <csv>`	IDs de campos de `dm fields`
`--estimate-cost`	Vista previa de conteo y créditos
`--yes`	Confirmar gasto de créditos aprobado
`--page <n>`	Número de página
`--per-page <n>`	Resultados por página

Comandos de Comparables

`dm comps [property_ids...]`

Encontrar propiedades comparables (comparables de ventas) para una o más propiedades.

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

Opción	Descripción
`--body <json>`	Cuerpo de la solicitud como cadena JSON
`-f, --file <path>`	Leer el cuerpo de la solicitud desde un archivo JSON
`--radius <miles>`	Radio de búsqueda en millas (predeterminado: 1)
`--timeframe <period>`	`3months`, `6months`, `12months`, `all` (predeterminado: 6meses)
`--limit <n>`	Máximo de comparables por propiedad (predeterminado: 25, máximo: 100)
`--sort-by <field>`	`distance`, `price`, `date`, `match` (predeterminado: coincidencia)
`--sort-direction <dir>`	`asc`, `desc` (predeterminado: desc)
`--include-foreclosures`	Incluir ventas por ejecución hipotecaria
`--json`	Salida como JSON

La salida incluye detalles de la propiedad sujeto, estimación de valor con intervalo de confianza, estadísticas resumidas (precio promedio/mediano, precio por pie cuadrado) y una tabla de propiedades comparables.

Comandos de Listas

`dm lists search`

Buscar y listar todas las listas guardadas.

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

Opción	Descripción
`--search <term>`	Buscar listas por nombre
`--source-type <type>`	`properties` o `people`
`--sort <order>`	`newest`, `oldest`, `name`, `count`
`-p, --page <n>`	Número de página
`--per-page <n>`	Resultados por página

`dm lists create`

Crear una nueva lista.

# 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

Opción	Descripción
`--name <name>`	Nombre de la lista (obligatorio)
`--source-type <type>`	`properties` o `people`
`--ids <csv>`	IDs de registros separados por comas para precargar (máx. 250)
`--body <json>`	Cuerpo de la solicitud como JSON (filtros/ubicaciones)
`-f, --file <path>`	Leer el cuerpo de la solicitud desde un archivo JSON

`dm lists get <id>`

Obtén detalles de una lista específica, incluidos estado, progreso y estado de error.

dm lists get list_abc123

`dm lists update <id>`

Renombra una lista.

dm lists update list_abc123 --name "New Name"

`dm lists delete <id>`

Elimina una lista y todos sus elementos.

dm lists delete list_abc123

`dm lists build <id>`

Construye una lista a partir de filtros de búsqueda. Esta es una operación asíncrona: consulta con dm lists get para conocer el estado.

dm lists build list_abc123 -f search-filters.json

`dm lists import <id>`

Importa IDs de registros en una lista existente.

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>`

Lista los elementos de una lista con paginación.

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

`dm lists add <id>`

Agrega elementos a una lista por ID.

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

Opción	Descripción
`--ids <csv>`	Lista de IDs separados por comas para agregar (obligatorio)
`--id-type <type>`	`internal_property_id` o `internal_person_id`

`dm lists remove <id>`

Elimina elementos de una lista por ID.

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

`dm lists export <id>`

Exporta elementos de la lista. Se cobran créditos por registro.

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

Opción	Descripción
`--fields <csv>`	Lista de campos separados por comas para exportar
`--anchor <type>`	`property` o `person`

Comandos de Filtros

`dm filters`

Lista los filtros de búsqueda disponibles con sus tipos, operadores y agrupaciones.

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

Opción	Descripción
`--source-type <type>`	`properties` o `people`
`--group-id <id>`	Filtrar por ID de grupo
`--search <term>`	Buscar filtros por nombre
`--page <n>`	Número de página
`--per-page <n>`	Resultados por página

Comandos de Campos

`dm fields`

Lista los campos de datos disponibles con indicadores de filtrable/ordenable.

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

Opción	Descripción
`--source-type <type>`	`properties` o `people`
`--group-id <id>`	Filtrar por ID de grupo
`--search <term>`	Buscar campos por nombre
`--page <n>`	Número de página
`--per-page <n>`	Resultados por página

Comandos de Ubicaciones

Busca y recupera ubicaciones de DealMachine.

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

dm locations autocomplete sigue disponible como alias obsoleto para dm addresses autocomplete.

Comandos de Actividad

`dm activity search`

Busca actividad pasada de la API con filtros de tipo y búsqueda de texto libre.

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

Opción	Descripción
`--body <json>`	Cuerpo de la solicitud como cadena JSON
`-f, --file <path>`	Leer el cuerpo de la solicitud desde un archivo JSON
`-t, --types <types...>`	Filtrar por tipos de actividad (separados por espacios)
`-q, --query <text>`	Búsqueda de texto libre en la actividad
`--page <n>`	Número de página
`--per-page <n>`	Resultados por página

`dm activity get <id>`

Obtén detalles completos de un registro de actividad específico, incluida la solicitud original, el resumen de resultados y los IDs de entidades (personas y propiedades).

dm activity get act_abc123
dm activity get act_abc123 --json

Comandos de Direcciones

`dm addresses autocomplete <query>`

Devuelve sugerencias gratuitas y acotadas de direcciones y ubicaciones normalizadas.

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

Opción	Descripción
`--scope <scope>`	`all`, `address` o `location`, predeterminado `all`
`--state <code>`	Preferir una abreviatura de estado de dos letras
`--limit <n>`	Máximo de sugerencias, predeterminado 5 y máximo 10
`--latitude <number>`	Latitud para clasificación cercana, requiere longitud
`--longitude <number>`	Longitud para clasificación cercana, requiere latitud
`--json`	Salida de respuesta JSON sin procesar

El autocompletado no solicita campos, no realiza enriquecimiento ni consume créditos de datos.

`dm addresses validate [address]`

Valida y estandariza direcciones mediante 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

La salida muestra cada dirección como válida, corregida (con correcciones enumeradas) o inválida (con motivo).

Comandos de Desarrollo

Utilidades de desarrollo local que operan directamente contra el contenedor Docker MySQL (dealmachine-next-mysql). Requieren que la base de datos local esté en ejecución (npm run db:start desde la raíz del repositorio).

`dm dev license add <key_id>`

Agrega una licencia a una clave de API en la base de datos local.

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

Opción	Descripción
`--type <type>`	`state`, `county`, `zip_code` o `unlimited` (obligatorio)
`--code <code>`	Código de ubicación: abreviatura de estado, código FIPS o código postal
`--expires <date>`	Fecha de vencimiento en formato ISO

`dm dev license list [key_id]`

Lista todas las licencias, opcionalmente filtradas por ID de clave.

dm dev license list
dm dev license list key_abc123

`dm dev license remove <license_id>`

Elimina una licencia por su ID numérico.

dm dev license remove 42

Opciones Globales

Cada comando admite estas banderas:

Banderas	Descripción
`--json`	Salida como JSON legible por máquina (para scripts y tuberías)
`--quiet`	Suprimir indicadores y salida decorativa para agentes/scripts
`--help`	Mostrar información de uso para cualquier comando
`--version`	Mostrar la versión de la CLI

Métodos de Entrada

Los comandos que aceptan un cuerpo de solicitud admiten tres métodos de entrada, verificados en este orden:

--body <json> -- Cadena JSON en línea.
-f, --file <path> -- Leer desde un archivo JSON. Los comandos de enriquecimiento también aceptan archivos .csv para procesamiento por lotes.
Tubería de stdin -- Leer JSON desde entrada canalizada (detectada cuando stdin no es una 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

Enriquecimiento por Lotes CSV

Los comandos enrich detectan archivos .csv por extensión y los analizan automáticamente. Nombres de columnas esperados por comando:

Comando	Columnas Obligatorias	Nombres de Columnas Alternativos
`enrich address`	`full_address`	o `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`

Los lotes de más de 250 elementos se dividen automáticamente en fragmentos con indicadores de progreso. Si se alcanza un límite de exportación a mitad del lote, la CLI se detiene y devuelve los resultados recopilados hasta el momento.

Estructura del Proyecto

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

Módulos Clave

Módulo	Responsabilidad
`lib/config.ts`	Gestiona `~/.dealmachine/config.json`. Aplica permisos de archivo `0600` y permisos de directorio `0700`. Proporciona asistentes tipados de lectura/escritura/eliminación.
`lib/client.ts`	Cliente HTTP central. Resuelve la URL base de la API desde variables de entorno, configuración o valores predeterminados. Adjunta el encabezado `Authorization: Bearer` y `User-Agent` con versión. Sale con un código distinto de cero en errores HTTP.
`lib/api.ts`	Implementación del flujo de autorización de dispositivo. Maneja `POST /v1/auth/device/code` y `POST /v1/auth/device/token` con sondeo compatible con RFC 8628 y mapeo de errores. También proporciona `verifyCredentials` para validación de claves.
`lib/output.ts`	Todo el formato de salida: `printTable` (columnas de ancho automático), `printJson`, `printKeyValue`, `printPagination`, `printCredits`, `printTotals`, `printWarning`, `printHeader`. También exporta `parseRequestBody` que maneja `--body`, `-f` y entrada de stdin.

Compilación

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

Las verificaciones publicadas e implementadas son puertas de lanzamiento. Se espera que fallen antes de que se publique un lanzamiento o de que la implementación de documentación llegue a producción. El catálogo de escenarios se almacena en evals/claude-code-name-lookup.json para que las mismas variantes de indicaciones permanezcan visibles y revisables.

Binario Independiente

El dist/index.js compilado incluye un shebang #!/usr/bin/env node y se declara en package.json bajo bin.dm. Cuando se instala globalmente mediante npm, queda disponible como dm en el PATH.

Para distribución como binario independiente sin 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)

La matriz files en package.json garantiza que solo dist/ se incluya en el paquete publicado.

Configuración de TypeScript

Objetivo: ES2022
Módulo: NodeNext (ESM)
Modo estricto habilitado
Genera declaraciones, mapas de declaraciones y mapas de origen
Sin referencias de proyecto (compilación independiente)

Agregar Nuevos Comandos

Paso 1: Crear el archivo de comando

Crea 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();
}

Paso 2: Registrar en index.ts

Importa y conecta el comando en 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);
  });

Paso 3: Compilar y probar

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

Convenciones

Un archivo por grupo de comandos en src/commands/.
Siempre admite --json para salida legible por máquina.
Usa ora para indicadores durante llamadas a la API.
Usa chalk para salida de terminal en color.
Usa apiRequest<T> de lib/client.ts para todas las llamadas a la API: maneja autenticación, errores y salidas.
Usa parseRequestBody de lib/output.ts cuando el comando acepte entrada --body, -f o stdin.
Usa printHeader, printTable, printKeyValue, printCredits, printPagination para formato de salida consistente.
Todas las importaciones deben usar la extensión .js (requisito de ESM con resolución NodeNext).

Dependencias

Tiempo de Ejecución

Paquete	Versión	Propósito
`commander`	^12.1.0	Marco de CLI -- registro de comandos, análisis de opciones, generación de ayuda
`chalk`	^5.3.0	Estilizado de cadenas de terminal (colores, negrita, atenuado)
`ora`	^8.1.0	Animaciones de spinner para operaciones asíncronas
`open`	^10.1.0	Abre el navegador para el flujo de autenticación del dispositivo

Dev

Paquete	Versión	Propósito
`typescript`	^5.6.3	Compilador de TypeScript
`@types/node`	^22.0.0	Definiciones de tipos de Node.js

Dependencias Internas de Paquetes

Ninguna. Este paquete es un binario completamente independiente con cero dependencias de @dealmachine/*. Se comunica exclusivamente a través de la API REST pública.

Usado Por

El Playbook en packages/playbooks/playbook/ usa comandos de dm para ejecutar flujos de trabajo de inteligencia de propiedades. La CLI es la interfaz principal a través de la cual el Playbook interactúa con los datos de DealMachine. Los agentes pueden cargar el Playbook incluido directamente con dm agents playbook.

Seguimiento de trabajo de staging de Factory

El flujo de trabajo de factory-release-intake.yml se mantiene en master y lee los PR fusionados desde staging. Reporta la fuente y, donde esté registrado, el despliegue exacto de staging a Factory Releases, reutilizando enlaces de Linear o creando un issue de seguimiento piloto configurable. La reconciliación programada reintenta eventos omitidos sin issues duplicados. No despliega este repositorio, ejecuta QA ni aprueba producción.

El recolector se genera desde Factory. Consulta ingesta automática de staging para configuración, propiedad de la fuente, regeneración y recuperación. Staging sigue siendo la rama que se verifica aunque el flujo de trabajo de reporte viva en master.