DealMachine

Inteligência de propriedades, proprietários, pessoas e empresas para vendas imobiliárias, marketing, prospecção, enriquecimento e geração de leads.

GitHubExperimente este MCPPatrocinado

Documentação

CLI do DealMachine

Mantenedores: instruções para agentes, desenvolvimento, referência atual de comandos e versões npm.

CLI do DealMachine (dm) — inteligência imobiliária a partir da linha de comando.

Uma CLI independente baseada em Commander.js que se comunica com a API REST do DealMachine. Fornece comandos para autenticação, pesquisa de propriedades e pessoas, enriquecimento, listas, prospects, tags, webhooks, e-mail e utilitários de desenvolvimento. Compila para JavaScript ESM via tsc.

Este pacote tem zero dependências de @dealmachine/* — é um binário autocontido que se comunica exclusivamente por meio da API pública.

Integrações com agentes de IA

Este repositório também é o pacote de distribuição pública para o servidor MCP do DealMachine e a skill do DealMachine.

Servidor MCP hospedado: https://mcp.dealmachine.com
Documentação da API: https://api.docs.dealmachine.com
Conta e chaves de API: https://dealmachine.com/settings/developer
Política de privacidade: https://dealmachine.com/privacy-policy
Termos de serviço: https://dealmachine.com/terms-of-service
Suporte: support@dealmachine.com

O servidor MCP suporta OAuth 2.1 para ChatGPT, Claude, Cursor, Codex e outros clientes compatíveis. Ele também pode usar uma chave de API do DealMachine em clientes de desenvolvimento que suportam configuração de bearer-token.

O pacote do plugin inclui:

Uma conexão MCP hospedada para ferramentas de propriedades, pessoas, enriquecimento, vendas comparáveis e conta
Uma skill com ciência de créditos que descobre filtros e campos, conta primeiro e confirma operações pagas de grande volume
Um pacote portátil de Agent Plugins para clientes compatíveis
Manifestos para OpenAI, Claude, Cursor, GitHub Copilot e Gemini
Metadados oficiais do Registro MCP em server.json

O pacote portátil segue o Agent Plugins 1.0.0:

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

Clientes compatíveis descobrem a skill do DealMachine a partir de skills/dealmachine/ e se conectam ao servidor MCP HTTP Streamable hospedado declarado em mcp.json. Manifestos específicos de clientes permanecem no repositório para compatibilidade, metadados de marketplace e apresentação mais rica.

Exemplos de solicitações:

"Encontre propriedades de proprietários ausentes com alto patrimônio em Austin e estime o custo de créditos primeiro."
"Consulte o proprietário desta propriedade e encontre dados de contato disponíveis."
"Encontre vendas comparáveis para esta propriedade."
"Pesquise pessoas que correspondam a esses critérios para uma lista de prospecção direcionada."

Instalação direta da skill:

npx skills add DealMachine/dealmachine-cli

Índice

Integrações com agentes de IA
Instalação
Autenticação
Configuração
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álise de propriedades comparáveis
- Lists -- search, create, get, update, delete, build, import, items, add, remove, export
- Filters -- lista os filtros de pesquisa disponíveis
- Fields -- lista os campos de dados disponíveis
- Activity -- search, get
- Addresses -- autocomplete, validate
- Dev -- license add, license list, license remove
Opções Globais
Métodos de Entrada
Estrutura do Projeto
Compilação
Adicionando Novos Comandos
Dependências

Instalação

Via npm (global)

npm install -g dealmachine
dm login

O pacote de implementação canônico é @dealmachine/cli. O pacote dealmachine é o alias curto de instalação e fornece o mesmo comando dm.

A partir do código-fonte

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

Link para desenvolvimento local

cd dealmachine-cli
npm link
dm --version

A entrada binária é dist/index.js, declarada em package.json sob bin.dm. Requer Node.js >= 18.

Autenticação

A CLI suporta dois métodos de autenticação.

Fluxo de Autenticação de Dispositivo (RFC 8628)

O comando padrão dm login usa a Concessão de Autorização de Dispositivo OAuth 2.0 (RFC 8628). Este é o fluxo recomendado para uso interativo:

dm login

A CLI solicita um código de dispositivo de POST /v1/auth/device/code com o ID do cliente dealmachine-next-cli e o nome do host da sua máquina.
Uma URL de verificação e um código de usuário são exibidos. O navegador abre automaticamente (a menos que --no-browser).
Você autoriza o dispositivo no navegador inserindo o código de usuário.
A CLI consulta POST /v1/auth/device/token no intervalo especificado pelo servidor.
Em caso de sucesso, a chave de API, o ID da chave e os detalhes da organização são armazenados em ~/.dealmachine/config.json.

A consulta trata todas as respostas RFC 8628: authorization_pending, slow_down (recua por 5s), access_denied e expired_token.

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

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

Login Direto com Chave de API

Para pipelines de CI, scripts ou desenvolvimento local, passe uma chave de API diretamente:

dm login --key dm_sk_live_abc123...

A chave é verificada em relação a GET /v1/account antes de ser armazenada. Se a verificação falhar, a CLI sai com um código não zero.

Se você ainda não tem uma chave de API, use dm signup, dm plans e dm checkout primeiro. O checkout do plano público aceita apenas preços Basic e Pro de autoatendimento do catálogo de planos compartilhado e está limitado a 60.000 créditos de dados mensais.

Alternando Ambientes

Se você já está conectado, pode alternar o ambiente de API de destino sem sair:

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

Logout

dm logout

Remove o arquivo de configuração em ~/.dealmachine/config.json.

Configuração

As credenciais são armazenadas em ~/.dealmachine/config.json com permissões de arquivo 0600 (somente leitura/gravação do proprietário). O diretório de configuração ~/.dealmachine/ é criado com modo 0700.

Esquema do Arquivo de Configuração

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

Variáveis de Ambiente

A CLI verifica estas variáveis de ambiente para resolução da URL da API (em ordem de prioridade):

Variável	Finalidade	Exemplo
`DM_API_URL` / `DEALMACHINE_API_URL`	Substituição direta de URL	`http://localhost:3001/v1`
`DM_ENV` / `DEALMACHINE_ENVIRONMENT`	Nome do ambiente	`local`, `staging` ou `production`

Se nenhuma estiver definida, a CLI usa o campo apiEnvironment no arquivo de configuração e, em seguida, o padrão production.

Ambientes de API

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

Exibe orientações concisas para agentes que usam a CLI. Este é o primeiro comando recomendado quando um agente tem acesso a dm, mas ainda não carregou o Playbook do DealMachine.

dm agents
dm agents --json

O guia instrui os agentes a usar --json e --quiet, verificar a autenticação, buscar filtros e campos atualizados antes das pesquisas, contar antes de trabalhos que consomem créditos e confirmar o uso esperado de créditos antes de buscar registros ou exportar.

`dm agents guide`

Exibe explicitamente a mesma orientação concisa para agentes.

dm agents guide
dm agents guide --json

`dm agents playbook`

Exibe o Markdown do Playbook do DealMachine incluído no pacote. Os agentes devem carregar isso antes de traduzir solicitações em linguagem natural sobre propriedades, pessoas, contatos, enriquecimento, listas, exportação, comparáveis ou uso de créditos em comandos da CLI.

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

O código-fonte público da CLI mantém seu Playbook incluído em playbook/PLAYBOOK.md. A compilação grava o código-fonte selecionado em dist/agents/dealmachine-playbook.md, para que o comando funcione tanto a partir de um pacote CLI publicado quanto de uma cópia local do código-fonte.

`dm agents install claude-code`

Instala o Playbook como uma skill nativa do Claude Code. O escopo pessoal é o padrão. O escopo de projeto instala no repositório atual.

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

`dm agents permissions`

Exibe a lista de permissões restrita do Claude Code para comandos gratuitos de descoberta e contagem. Comandos pagos e de mutação não são pré-aprovados.

dm agents permissions
dm agents permissions --json

Comandos de Auth

`dm signup`

Cria uma conta pública de API e recebe uma chave 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 os planos públicos Basic e Pro de autoatendimento:

dm plans
dm plans --json

`dm checkout`

Cria uma sessão de checkout no Stripe usando um ID de preço de dm plans:

dm checkout --price-id price_xxx_monthly

`dm login`

Autentica com sua conta do 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

Opção	Descrição
`--no-browser`	Não abrir o navegador automaticamente
`--key <api-key>`	Login direto com uma chave de API (ignora o navegador)
`--env <environment>`	Ambiente de API: `local`, `staging` ou `production`

`dm logout`

Remove as credenciais armazenadas.

dm logout

`dm whoami`

Exibe o status atual de autenticação.

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

Opção	Descrição
`--verify`	Verifica as credenciais com a API

Comandos de Config

`dm config get [key]`

Obtém um valor de configuração ou exibe todos os valores quando nenhuma chave é fornecida.

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

Chaves disponíveis: organizationName, organizationSlug, organizationId, apiEnvironment, keyId, apiKey.

`dm config set <key> <value>`

Define um valor de configuração. Apenas apiEnvironment é editável.

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

`dm config path`

Exibe o caminho absoluto para o arquivo de configuração.

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

Comandos de Account

`dm account`

Exibe informações da conta, incluindo nome da organização, ID, data de criação e tipo de autenticação.

dm account

Saída:

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

Comandos de Usage

`dm usage`

Exibe o uso de créditos para o ciclo de cobrança atual.

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

Saída:

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`

Pesquisa propriedades com filtros e localizações.

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

Opção	Descrição
`--body <json>`	Corpo da solicitação como string JSON
`-f, --file <path>`	Ler corpo da solicitação de um arquivo JSON
`--include-lists <ids>`	Lista de IDs separados por vírgula para incluir
`--exclude-lists <ids>`	Lista de IDs separados por vírgula para excluir
`--exclude-previously-exported`	Excluir registros já exportados pela sua organização
`--bigquery-data-environment <n>`	Ambiente de dados do Query Builder (`1` produção, `2` staging, `3` desenvolvimento)
`--estimate-cost`	Visualizar contagens e custo de créditos sem consumir créditos
`--yes`	Confirmar gasto de créditos aprovado para execução não interativa
`--json`	Saída como JSON

`dm properties count`

Contar propriedades que correspondem aos filtros sem consumir créditos.

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

`dm properties get <id>`

Obter uma única propriedade pelo seu ID 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

Opção	Descrição
`--contact-audience <audience>`	`owners`, `owners_and_family`, `renters`, `residents`, `all`, `none`
`--fields <csv>`	IDs de campos de propriedade separados por vírgula de `dm fields`
`--json`	Saída como JSON

A consulta de propriedade usa como padrão owners. Se você precisar apenas dos dados da propriedade, use --contact-audience none. Isso omite contatos e evita créditos de pessoas.

`dm properties ids [ids...]`

Obter várias propriedades pelos seus IDs em uma única solicitação em lote.

# 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

Opção	Descrição
`--body <json>`	Corpo da solicitação como string JSON
`-f, --file <path>`	Ler corpo da solicitação de um arquivo JSON
`--contact-audience <audience>`	Incluir contatos: `owners`, `owners_and_family`, `renters`, `residents`, `all`, `none`
`--json`	Saída como JSON

`dm properties export`

Exportar propriedades como CSV (até 1.000.000 de registros). Retorna URLs de download assinadas.

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

Opção	Descrição
`--body <json>`	Corpo da solicitação como string JSON
`-f, --file <path>`	Ler corpo da solicitação de um arquivo JSON
`--require-phone`	Incluir apenas registros onde o contato tem um número de telefone
`--require-email`	Incluir apenas registros onde o contato tem um endereço de e-mail
`--mobile-only`	Incluir apenas números de telefone celular
`--landline-only`	Incluir apenas números de telefone fixo
`--scrub-dnc`	Excluir contatos no registro Do Not Call
`--json`	Saída como JSON

Comandos de Pessoas

`dm people search`

Buscar pessoas com filtros e localizações.

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

A Busca de Pessoas não interativa retorna uma estimativa gratuita, a menos que --yes seja fornecida. Uma pessoa específica pelo nome usa dm enrich name, não a Busca de Pessoas.

`dm people count`

Contar pessoas que correspondem aos filtros sem consumir créditos.

dm people count -f filters.json

`dm people get <id>`

Obter uma única pessoa pelo seu ID 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

Opção	Descrição
`--include-properties`	Incluir propriedades associadas
`--property-limit <n>`	Máximo de propriedades associadas a retornar, de 1 a 100
`--fields <csv>`	IDs de campos separados por vírgula de `dm fields`
`--json`	Saída como JSON

`dm people ids [ids...]`

Obter várias pessoas pelos seus IDs em uma única solicitação em lote.

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

Opção	Descrição
`--include-properties`	Incluir propriedades associadas
`--property-limit <n>`	Máximo de propriedades associadas a retornar por pessoa, até 100
`--fields <csv>`	IDs de campos separados por vírgula de `dm fields`

`dm people export`

Exportar pessoas como CSV (até 1.000.000 de registros). Retorna URLs de download assinadas.

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

As opções de filtro de contato são as mesmas de dm properties export.

Comandos de Enriquecimento

Todos os comandos de enriquecimento suportam três modos de entrada: um argumento posicional para consulta de item único, --body/-f para cargas JSON, e -f com um arquivo .csv para enriquecimento em lote a partir de CSV. Lotes maiores que 250 itens são automaticamente divididos em partes. Cada comando de enriquecimento aceita --fields <csv> e envia os IDs de campos selecionados para a API. Correspondências de e-mail, telefone e nome também incluem um property_count gratuito; use --include-properties quando precisar dos próprios registros de propriedade.

`dm enrich address [address]`

Consultar uma propriedade pelo endereço da rua.

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

Opção	Descrição
`--body <json>`	Corpo da solicitação como string JSON
`-f, --file <path>`	Ler de arquivo JSON ou CSV
`--contact-audience <audience>`	`owners`, `owners_and_family`, `renters`, `residents`, `none`
`--fields <csv>`	IDs de campos separados por vírgula de `dm fields`
`--json`	Saída como JSON

Use --contact-audience none sempre que precisar apenas da propriedade. A resposta omite contatos e consome zero créditos de pessoas.

`dm enrich latlng [coords]`

Consultar uma propriedade por coordenadas de latitude/longitude.

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

Consultar uma propriedade pelo Número de Parcela do Avaliador. Refine os resultados com --state ou --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)

Opção	Descrição
`--state <code>`	Refinar por estado (ex.: TX)
`--zip <code>`	Refinar por código postal
`--contact-audience <audience>`	`owners`, `owners_and_family`, `renters`, `residents`, `none`
`--fields <csv>`	IDs de campos separados por vírgula de `dm fields`

`dm enrich email [email]`

Consultar uma pessoa pelo endereço de e-mail.

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)

Opção	Descrição
`--include-properties`	Incluir propriedades associadas
`--fields <csv>`	IDs de campos separados por vírgula de `dm fields`

`dm enrich phone [phone]`

Consultar uma pessoa pelo número de telefone.

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

Opção	Descrição
`--include-properties`	Incluir propriedades associadas
`--fields <csv>`	IDs de campos separados por vírgula de `dm fields`

`dm enrich name [name]`

Consultar pessoas pelo nome. Suporta o formato "Primeiro Sobrenome" ou apenas "Sobrenome".

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

Opção	Descrição
`--state <code>`	Refinar por estado
`--zip <code>`	Refinar por código postal
`--include-properties`	Incluir propriedades associadas
`--fields <csv>`	IDs de campos de `dm fields`
`--estimate-cost`	Visualizar contagem e créditos
`--yes`	Confirmar gasto de créditos aprovado
`--page <n>`	Número da página
`--per-page <n>`	Resultados por página

Comandos de Comparáveis

`dm comps [property_ids...]`

Encontrar propriedades comparáveis (comparáveis de vendas) para uma ou mais propriedades.

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

Opção	Descrição
`--body <json>`	Corpo da solicitação como string JSON
`-f, --file <path>`	Ler corpo da solicitação de um arquivo JSON
`--radius <miles>`	Raio de busca em milhas (padrão: 1)
`--timeframe <period>`	`3months`, `6months`, `12months`, `all` (padrão: 6meses)
`--limit <n>`	Máx. de comparáveis por propriedade (padrão: 25, máx: 100)
`--sort-by <field>`	`distance`, `price`, `date`, `match` (padrão: correspondência)
`--sort-direction <dir>`	`asc`, `desc` (padrão: desc)
`--include-foreclosures`	Incluir vendas de execução hipotecária
`--json`	Saída como JSON

A saída inclui detalhes da propriedade em questão, estimativa de valor com intervalo de confiança, estatísticas resumidas (preço médio/mediano, preço por m²) e uma tabela de propriedades comparáveis.

Comandos de Listas

`dm lists search`

Buscar e listar todas as listas salvas.

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

Opção	Descrição
`--search <term>`	Buscar listas pelo nome
`--source-type <type>`	`properties` ou `people`
`--sort <order>`	`newest`, `oldest`, `name`, `count`
`-p, --page <n>`	Número da página
`--per-page <n>`	Resultados por página

`dm lists create`

Criar uma nova 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

Opção	Descrição
`--name <name>`	Nome da lista (obrigatório)
`--source-type <type>`	`properties` ou `people`
`--ids <csv>`	IDs de registros separados por vírgula para pré-popular (máx. 250)
`--body <json>`	Corpo da solicitação como JSON (filtros/localizações)
`-f, --file <path>`	Ler corpo da solicitação de um arquivo JSON

`dm lists get <id>`

Obtenha detalhes de uma lista específica, incluindo status, progresso e estado de erro.

dm lists get list_abc123

`dm lists update <id>`

Renomeie uma lista.

dm lists update list_abc123 --name "New Name"

`dm lists delete <id>`

Exclua uma lista e todos os seus itens.

dm lists delete list_abc123

`dm lists build <id>`

Construa uma lista a partir de filtros de pesquisa. Esta é uma operação assíncrona — consulte dm lists get para verificar o status.

dm lists build list_abc123 -f search-filters.json

`dm lists import <id>`

Importe IDs de registros para uma 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>`

Liste itens em uma lista com paginação.

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

`dm lists add <id>`

Adicione itens a uma 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

Opção	Descrição
`--ids <csv>`	Lista de IDs separados por vírgula para adicionar (obrigatório)
`--id-type <type>`	`internal_property_id` ou `internal_person_id`

`dm lists remove <id>`

Remova itens de uma lista por ID.

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

`dm lists export <id>`

Exporte itens da lista. Créditos são cobrados por registro.

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

Opção	Descrição
`--fields <csv>`	Lista de campos separados por vírgula para exportar
`--anchor <type>`	`property` ou `person`

Comandos de Filtros

`dm filters`

Liste os filtros de pesquisa disponíveis com seus tipos, operadores e agrupamentos.

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

Opção	Descrição
`--source-type <type>`	`properties` ou `people`
`--group-id <id>`	Filtrar por ID do grupo
`--search <term>`	Pesquisar filtros por nome
`--page <n>`	Número da página
`--per-page <n>`	Resultados por página

Comandos de Campos

`dm fields`

Liste os campos de dados disponíveis com sinalizadores de filtrável/ordenável.

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

Opção	Descrição
`--source-type <type>`	`properties` ou `people`
`--group-id <id>`	Filtrar por ID do grupo
`--search <term>`	Pesquisar campos por nome
`--page <n>`	Número da página
`--per-page <n>`	Resultados por página

Comandos de Localizações

Pesquise e recupere localizações do DealMachine.

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

dm locations autocomplete permanece disponível como um alias obsoleto para dm addresses autocomplete.

Comandos de Atividade

`dm activity search`

Pesquise atividades passadas da API com filtros de tipo e pesquisa de texto livre.

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

Opção	Descrição
`--body <json>`	Corpo da solicitação como string JSON
`-f, --file <path>`	Ler corpo da solicitação de um arquivo JSON
`-t, --types <types...>`	Filtrar por tipos de atividade (separados por espaço)
`-q, --query <text>`	Pesquisa de texto livre em toda a atividade
`--page <n>`	Número da página
`--per-page <n>`	Resultados por página

`dm activity get <id>`

Obtenha detalhes completos de um registro de atividade específico, incluindo a solicitação original, resumo do resultado e IDs de entidades (pessoas e propriedades).

dm activity get act_abc123
dm activity get act_abc123 --json

Comandos de Endereços

`dm addresses autocomplete <query>`

Retorne sugestões gratuitas e limitadas de endereço e localização normalizada.

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

Opção	Descrição
`--scope <scope>`	`all`, `address`, ou `location`, padrão `all`
`--state <code>`	Prefira uma abreviação de estado de duas letras
`--limit <n>`	Máximo de sugestões, padrão 5 e máximo 10
`--latitude <number>`	Latitude para classificação por proximidade, requer longitude
`--longitude <number>`	Longitude para classificação por proximidade, requer latitude
`--json`	Saída da resposta JSON bruta

O preenchimento automático não solicita campos, não realiza enriquecimento nem consome créditos de dados.

`dm addresses validate [address]`

Valide e padronize endereços via 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

A saída mostra cada endereço como válido, corrigido (com correções listadas) ou inválido (com motivo).

Comandos de Desenvolvimento

Utilitários de desenvolvimento local que operam diretamente contra o contêiner MySQL do Docker (dealmachine-next-mysql). Eles exigem que o banco de dados local esteja em execução (npm run db:start a partir da raiz do repositório).

`dm dev license add <key_id>`

Adicione uma licença a uma chave de API no banco de dados 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

Opção	Descrição
`--type <type>`	`state`, `county`, `zip_code`, ou `unlimited` (obrigatório)
`--code <code>`	Código de localização: abreviação de estado, código FIPS ou CEP
`--expires <date>`	Data de expiração no formato ISO

`dm dev license list [key_id]`

Liste todas as licenças, opcionalmente filtradas por ID da chave.

dm dev license list
dm dev license list key_abc123

`dm dev license remove <license_id>`

Remova uma licença pelo seu ID numérico.

dm dev license remove 42

Opções Globais

Todo comando suporta estes sinalizadores:

Sinalizador	Descrição
`--json`	Saída como JSON legível por máquina (para scripts e pipes)
`--quiet`	Suprimir spinners e saída decorativa para agentes/scripts
`--help`	Mostrar informações de uso para qualquer comando
`--version`	Mostrar a versão da CLI

Métodos de Entrada

Comandos que aceitam um corpo de solicitação suportam três métodos de entrada, verificados nesta ordem:

--body <json> -- String JSON inline.
-f, --file <path> -- Ler de um arquivo JSON. Comandos de enriquecimento também aceitam arquivos .csv para processamento em lote.
Pipe de stdin -- Ler JSON de entrada via pipe (detectado quando stdin não é um 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

Enriquecimento em Lote CSV

Os comandos enrich detectam arquivos .csv pela extensão e os analisam automaticamente. Nomes de colunas esperados por comando:

Comando	Colunas Obrigatórias	Nomes Alternativos de Colunas
`enrich address`	`full_address`	ou `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`

Lotes maiores que 250 itens são automaticamente divididos em blocos com spinners de progresso. Se um limite de exportação for atingido no meio do lote, a CLI para e retorna os resultados coletados até o momento.

Estrutura do Projeto

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 Principais

Módulo	Responsabilidade
`lib/config.ts`	Gerencia `~/.dealmachine/config.json`. Impõe permissões de arquivo `0600` e permissões de diretório `0700`. Fornece auxiliares tipados de leitura/escrita/exclusão.
`lib/client.ts`	Cliente HTTP central. Resolve a URL base da API a partir de variáveis de ambiente, configuração ou padrões. Anexa o cabeçalho `Authorization: Bearer` e `User-Agent` versionado. Sai com código não zero em erros HTTP.
`lib/api.ts`	Implementação do fluxo de autorização de dispositivo. Lida com `POST /v1/auth/device/code` e `POST /v1/auth/device/token` com polling compatível com RFC 8628 e mapeamento de erros. Também fornece `verifyCredentials` para validação de chave.
`lib/output.ts`	Toda a formatação de saída: `printTable` (colunas de largura automática), `printJson`, `printKeyValue`, `printPagination`, `printCredits`, `printTotals`, `printWarning`, `printHeader`. Também exporta `parseRequestBody` que lida com `--body`, `-f` e entrada stdin.

Compilação

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

As verificações publicadas e implantadas são portões de lançamento. Espera-se que falhem antes de um lançamento ser publicado ou a implantação da documentação atingir produção. O catálogo de cenários é armazenado em evals/claude-code-name-lookup.json para que as mesmas variantes de prompt permaneçam visíveis e revisáveis.

Binário Independente

O dist/index.js compilado inclui um shebang #!/usr/bin/env node e é declarado em package.json sob bin.dm. Quando instalado globalmente via npm, torna-se disponível como dm no PATH.

Para distribuição como binário independente sem 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)

O array files em package.json garante que apenas dist/ seja incluído no pacote publicado.

Configuração TypeScript

Alvo: ES2022
Módulo: NodeNext (ESM)
Modo estrito habilitado
Gera declarações, mapas de declaração e mapas de origem
Sem referências de projeto (compilação independente)

Adicionando Novos Comandos

Etapa 1: Criar o arquivo do comando

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

Etapa 2: Registrar em index.ts

Importe e conecte o comando em 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);
  });

Etapa 3: Compilar e testar

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

Convenções

Um arquivo por grupo de comandos em src/commands/.
Sempre suporte --json para saída legível por máquina.
Use ora para spinners durante chamadas de API.
Use chalk para saída de terminal colorida.
Use apiRequest<T> de lib/client.ts para todas as chamadas de API — ele lida com autenticação, erros e saídas.
Use parseRequestBody de lib/output.ts quando o comando aceitar entrada --body, -f ou stdin.
Use printHeader, printTable, printKeyValue, printCredits, printPagination para formatação de saída consistente.
Todos os imports devem usar a extensão .js (requisito ESM com resolução NodeNext).

Dependências

Tempo de Execução

Pacote	Versão	Finalidade
`commander`	^12.1.0	Framework de CLI — registro de comandos, análise de opções, geração de ajuda
`chalk`	^5.3.0	Estilização de strings no terminal (cores, negrito, esmaecido)
`ora`	^8.1.0	Animações de spinner para operações assíncronas
`open`	^10.1.0	Abre o navegador para o fluxo de autenticação do dispositivo

Dev

Pacote	Versão	Finalidade
`typescript`	^5.6.3	Compilador TypeScript
`@types/node`	^22.0.0	Definições de tipos do Node.js

Dependências Internas de Pacotes

Nenhuma. Este pacote é um binário totalmente autônomo com zero dependências de @dealmachine/*. Ele se comunica exclusivamente por meio da API REST pública.

Usado Por

O Playbook em packages/playbooks/playbook/ usa comandos dm para executar fluxos de trabalho de inteligência de propriedades. A CLI é a interface principal pela qual o Playbook interage com os dados do DealMachine. Os agentes podem carregar o Playbook incluído diretamente com dm agents playbook.

Rastreamento de trabalho de staging da fábrica

O fluxo de trabalho factory-release-intake.yml é mantido no master e lê PRs mesclados do staging. Ele relata a origem e, quando registrado, a implantação exata de staging para Factory Releases, reutilizando links do Linear ou criando um problema de rastreamento piloto configurável. A reconciliação agendada tenta novamente eventos perdidos sem problemas duplicados. Ele não implanta este repositório, executa QA ou aprova produção.

O coletor é gerado a partir da Factory. Consulte ingestão automática de staging para configuração, propriedade da origem, regeneração e recuperação. O staging permanece como o branch sendo verificado, mesmo que o fluxo de trabalho de relatório viva no master.