path: root/README.md

# dborg - DB.org.ai CLI

CLI tool for querying the DB.org.ai API services.

## Project Structure

```
dborg/
├── cmd/                    # CLI commands
│   ├── admin.go           # Admin commands (build tag: admin)
│   ├── npd.go             # NPD breach data search
│   ├── osint.go           # OSINT tools (username, BSSID, BreachForum)
│   ├── reddit.go          # Reddit data retrieval
│   ├── root.go            # Root command configuration
│   ├── skiptrace.go       # Premium skiptrace operations
│   ├── sl.go              # Stealer logs search
│   ├── update.go          # Auto-update functionality
│   ├── version.go         # Version command
│   └── x.go               # Twitter/X username history
├── internal/              # Private application code
│   ├── client/            # API client implementation
│   │   ├── admin.go       # Admin API methods
│   │   ├── client.go      # Base HTTP client
│   │   ├── client_test.go # Client tests
│   │   ├── npd.go         # NPD API methods
│   │   ├── osint.go       # OSINT API methods
│   │   ├── reddit.go      # Reddit API methods
│   │   ├── skiptrace.go   # Skiptrace API methods
│   │   ├── sl.go          # Stealer logs API methods
│   │   ├── usrsx.go       # Username check API methods
│   │   └── x.go           # Twitter/X API methods
│   ├── config/            # Configuration management
│   │   ├── config.go      # Config structure
│   │   └── errors.go      # Custom errors
│   ├── models/            # Data models
│   │   ├── admin.go       # Admin response types
│   │   ├── npd.go         # NPD response types
│   │   ├── osint.go       # OSINT response types
│   │   ├── reddit.go      # Reddit response types
│   │   ├── skiptrace.go   # Skiptrace response types
│   │   ├── sl.go          # Stealer logs types
│   │   ├── usrsx.go       # Username check types
│   │   └── x.go           # Twitter/X types
│   └── utils/             # Utility functions
│       ├── output.go      # Output formatting helpers
│       ├── version.go     # Version checking and auto-update
│       └── version_test.go # Version utility tests
├── go.mod
├── go.sum
├── main.go
├── Makefile
└── README.md
```

## Installation

```bash
go install git.db.org.ai/dborg@latest
```

To build with admin commands:

```bash
make build-admin
```

Or:

```bash
go build -tags admin -o dborg .
```

### Auto-Update

The CLI automatically checks for updates on startup. When a newer version is available:
- You'll be prompted to update
- Accepts with `Y` or `Enter` to install the latest version via `go install git.db.org.ai/dborg@latest`
- The binary automatically restarts with the new version
- Skip with `n` to continue with your current version

Check your current version:
```bash
dborg version
```

## Configuration

### Initial Setup

Run the initialization command to set up your API key:

```bash
dborg init
```

This will prompt you to enter your API key and save it to `~/.config/dborg/config.json`.

### Alternative Configuration Methods

You can also set your API key via environment variable:

```bash
export DBORG_API_KEY=your_api_key_here
```

**Note:** Environment variables take precedence over the config file.

## Commands

### NPD - Search NPD breach data

```bash
dborg npd --firstname John --lastname Doe --max_hits 20
```

Available flags:
- `--id`, `--firstname`, `--lastname`, `--middlename`
- `--dob`, `--ssn`, `--phone1`
- `--address`, `--city`, `--st`, `--zip`, `--county_name`
- `--name_suff`, `--aka1fullname`, `--aka2fullname`, `--aka3fullname`
- `--alt1dob`, `--alt2dob`, `--alt3dob`, `--startdat`
- `--max_hits` (default: 10)
- `--sort_by`

### SL - Search stealer logs

```bash
dborg sl "domain.com" --max_hits 20 --format json
```

Available flags:
- `--max_hits` (default: 10)
- `--sort_by` (ingest_timestamp or date_posted)
- `--ingest_start_date`, `--ingest_end_date`
- `--posted_start_date`, `--posted_end_date`
- `--format` (json, ulp, up, pul, etc.)

### OSINT - Open Source Intelligence tools

#### Username Check
Check username availability across hundreds of websites using WhatsMyName dataset:

```bash
dborg osint username john_doe --sites GitHub,Twitter --max_tasks 100
```

Available flags:
- `--sites`, `-s` (comma-separated list of specific sites to check)
- `--fuzzy`, `-f` (enable fuzzy validation mode)
- `--max_tasks`, `-m` (maximum concurrent tasks, default: 50)

#### BSSID Lookup
Lookup WiFi access point location by BSSID (MAC address):

```bash
dborg osint bssid 00:11:22:33:44:55 --google --osm
```

Available flags:
- `--all`, `-a` (show all related results instead of exact match only)
- `--google`, `-g` (include Google Maps URL for the location)
- `--osm`, `-o` (include OpenStreetMap URL for the location)

#### BreachForum Search
Search BreachForum data from breachdetect index:

```bash
dborg osint breachforum "search term" --max_hits 20
```

Available flags:
- `--max_hits`, `-m` (maximum number of results, default: 10)

### Reddit - Reddit data retrieval

#### Subreddit Posts
```bash
dborg reddit subreddit posts programming
```

#### Subreddit Comments
```bash
dborg reddit subreddit comments programming
```

#### User Posts
```bash
dborg reddit user posts spez
```

#### User Comments
```bash
dborg reddit user comments spez
```

#### User Profile
```bash
dborg reddit user about spez
```

### Skiptrace - Premium people search (requires premium access)

**Note:** All skiptrace commands require a premium API key. Contact support to upgrade for premium access.

#### Search People
```bash
dborg skiptrace people --first-name John --last-name Doe --city Austin --state TX
```

Required flags:
- `--first-name`, `-f` (first name)
- `--last-name`, `-l` (last name)

Optional flags:
- `--city`, `-c` (city)
- `--state`, `-s` (state, 2-letter code)
- `--age`, `-a` (age)

#### Get Person Report
```bash
dborg skiptrace report SX_KEY 1
```

Args: `[sx_key]` `[selection]` from previous search results

#### Phone Lookup
```bash
dborg skiptrace phone 5551234567
```

Args: 10-digit phone number (no +1 prefix)

#### Email Lookup
```bash
dborg skiptrace email [email protected]
```

### X - Twitter/X username history

```bash
dborg x elonmusk
```

### Admin Commands (requires build tag)

Only available when built with `-tags admin`:

```bash
dborg admin list
dborg admin create john_doe --credits 1000 --unlimited
dborg admin delete API_KEY
dborg admin credits API_KEY 500
dborg admin disable API_KEY
dborg admin disable API_KEY --enable
```

## Architecture Benefits

The refactored structure provides:

1. **Separation of Concerns**: API logic is separated from CLI commands
2. **Testability**: Components can be easily unit tested
3. **Maintainability**: Clear organization makes code easier to maintain
4. **Reusability**: Client can be reused in other Go applications
5. **Error Handling**: Centralized error handling with custom error types
6. **Configuration Management**: Single source of truth for configuration
7. **Type Safety**: Strongly typed models for API requests/responses

## Building

Standard build (no admin commands):
```bash
make build
```

Build with admin commands:
```bash
make build-admin
```

Run tests:
```bash
go test ./...
```

Clean:
```bash
make clean
```

## Development

The codebase follows Go best practices:

- Internal packages for private implementation
- Interface-based design for testability
- Structured error handling
- Clear separation between CLI and business logic
- Comprehensive type definitions for API interactions