dealmachine-cli

# DealMachine CLI

DealMachine CLI (`dm`) -- property intelligence from the command line.

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

This package has **zero** `@dealmachine/*` dependencies -- it is a self-contained binary that communicates exclusively through the public API.

---

## AI agent integrations

This repository is also the public distribution package for the DealMachine MCP server and DealMachine skill.

- Hosted MCP server: `https://mcp.dealmachine.com`
- API documentation: `https://api.docs.dealmachine.com`
- Account and API keys: `https://dealmachine.com/settings/developer`
- Privacy policy: `https://dealmachine.com/privacy-policy`
- Terms of service: `https://dealmachine.com/terms-of-service`
- Support: `support@dealmachine.com`

The MCP server supports OAuth 2.1 for ChatGPT, Claude, Cursor, Codex, and other compatible clients. It can also use a DealMachine API key in developer clients that support bearer-token configuration.

The plugin package includes:

- A hosted MCP connection for property, people, company, enrichment, comparable-sales, and account tools
- A credit-aware skill that discovers filters and fields, counts first, and confirms large paid operations
- Manifests for OpenAI, Claude, Cursor, GitHub Copilot, and Gemini
- Official MCP Registry metadata in `server.json`

Example requests:

- "Find high-equity absentee-owned properties in Austin and estimate the credit cost first."
- "Look up the owner of this property and find available contact data."
- "Find comparable sales for this property."
- "Research companies that match these criteria for a targeted prospecting list."

Direct skill installation:

```bash
npx skills add DealMachine/dealmachine-cli
```

---

## Table of Contents

- [AI agent integrations](#ai-agent-integrations)
- [Installation](#installation)
- [Authentication](#authentication)
- [Configuration](#configuration)
- [Commands](#commands)
  - [Agents](#agents-commands) -- `agents`, `agents guide`, `agents playbook`
  - [Auth](#auth-commands) -- `login`, `logout`, `whoami`
  - [Config](#config-commands) -- `config get`, `config set`, `config path`
  - [Account](#account-commands) -- `account`
  - [Usage](#usage-commands) -- `usage`
  - [Properties](#properties-commands) -- `search`, `count`, `get`, `ids`, `export`
  - [People](#people-commands) -- `search`, `count`, `get`, `ids`, `export`
  - [Enrich](#enrich-commands) -- `address`, `latlng`, `apn`, `email`, `phone`, `name`
  - [Comps](#comps-commands) -- comparable property analysis
  - [Lists](#lists-commands) -- `search`, `create`, `get`, `update`, `delete`, `build`, `import`, `items`, `add`, `remove`, `export`
  - [Filters](#filters-commands) -- list available search filters
  - [Fields](#fields-commands) -- list available data fields
  - [Activity](#activity-commands) -- `search`, `get`
  - [Addresses](#addresses-commands) -- `autocomplete`, `validate`
  - [Dev](#dev-commands) -- `license add`, `license list`, `license remove`
- [Global Options](#global-options)
- [Input Methods](#input-methods)
- [Project Structure](#project-structure)
- [Building](#building)
- [Adding New Commands](#adding-new-commands)
- [Dependencies](#dependencies)

---

## Installation

### From npm (global)

```bash
npm install -g dealmachine
dm login
```

The canonical implementation package is `@dealmachine/cli`. The `dealmachine` package is the short install alias and provides the same `dm` command.

### From source

```bash
cd packages/cli
npm run build
node dist/index.js whoami
```

### Link for local development

```bash
cd packages/cli
npm link
dm --version
```

The binary entry is `dist/index.js`, declared in `package.json` under `bin.dm`. Requires Node.js >= 18.

---

## Authentication

The CLI supports two authentication methods.

### Device Auth Flow (RFC 8628)

The default `dm login` command uses the OAuth 2.0 Device Authorization Grant (RFC 8628). This is the recommended flow for interactive use:

```bash
dm login
```

1. The CLI requests a device code from `POST /v1/auth/device/code` with client ID `dealmachine-next-cli` and your machine's hostname.
2. A verification URL and user code are displayed. The browser opens automatically (unless `--no-browser`).
3. You authorize the device in the browser by entering the user code.
4. The CLI polls `POST /v1/auth/device/token` at the server-specified interval.
5. On success, the API key, key ID, and organization details are stored to `~/.dealmachine/config.json`.

The polling handles all RFC 8628 responses: `authorization_pending`, `slow_down` (backs off by 5s), `access_denied`, and `expired_token`.

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

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

### Direct API Key Login

For CI pipelines, scripts, or local development, pass an API key directly:

```bash
dm login --key dm_sk_live_abc123...
```

The key is verified against `GET /v1/account` before being stored. If verification fails, the CLI exits with a non-zero code.

If you do not have an API key yet, use `dm signup`, `dm plans`, and `dm checkout` first. Public plan checkout only accepts self-serve Basic and Pro prices from the shared plan catalog and is capped at 60,000 monthly data credits.

### Switching Environments

If you are already logged in, you can switch the target API environment without logging out:

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

```bash
dm logout
```

Removes the config file at `~/.dealmachine/config.json`.

---

## Configuration

Credentials are stored at `~/.dealmachine/config.json` with file permissions `0600` (owner read/write only). The config directory `~/.dealmachine/` is created with mode `0700`.

### Config File Schema

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

### Environment Variables

The CLI checks these environment variables for API URL resolution (in priority order):

| Variable                             | Purpose             | Example                             |
| ------------------------------------ | ------------------- | ----------------------------------- |
| `DM_API_URL` / `DEALMACHINE_API_URL` | Direct URL override | `http://localhost:3001/v1`          |
| `DM_ENV` / `DEALMACHINE_ENVIRONMENT` | Environment name    | `local`, `staging`, or `production` |

If none are set, the CLI falls back to the `apiEnvironment` field in the config file, then defaults to `production`.

### API Environments

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

---

## Commands

### Agents Commands

#### `dm agents`

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.

```bash
dm agents
dm agents --json
```

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.

#### `dm agents guide`

Print the same concise agent guidance explicitly.

```bash
dm agents guide
dm agents guide --json
```

#### `dm agents playbook`

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.

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

The public CLI source keeps its bundled Playbook at `playbook/PLAYBOOK.md`. Monorepo builds can also copy `packages/playbooks/playbook/SKILL.md`. The build writes the selected source to `dist/agents/dealmachine-playbook.md`, so the command works from a published CLI package as well as a local source checkout.

---

### Auth Commands

#### `dm signup`

Create a public API account and receive an API key:

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

#### `dm plans`

List public self-serve Basic and Pro plans:

```bash
dm plans
dm plans --json
```

#### `dm checkout`

Create a Stripe checkout session using a price ID from `dm plans`:

```bash
dm checkout --price-id price_xxx_monthly
```

#### `dm login`

Authenticate with your DealMachine account.

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

| Option                | Description                                          |
| --------------------- | ---------------------------------------------------- |
| `--no-browser`        | Do not automatically open the browser                |
| `--key <api-key>`     | Login directly with an API key (skips browser)       |
| `--env <environment>` | API environment: `local`, `staging`, or `production` |

#### `dm logout`

Remove stored credentials.

```bash
dm logout
```

#### `dm whoami`

Show current authentication status.

```bash
dm whoami               # Show stored crede