hinge-kit

Unofficial TypeScript CLI and SDK for interacting with Hinge (and Sendbird chat) from Node.js. Includes dry-run defaults, local profile filters, safety budgets, message templates, multi-profile sessions, scheduling, and local stats.

Not affiliated with Hinge, Match Group, or Sendbird. Automating a dating account may violate Hinge’s Terms of Service and can get your account restricted or banned. Prefer dry-run mode. Use at your own risk.

Install

Requires Node.js 20+. Package on npm: hinge-kit.

npm install -g hinge-kit
# or, without global install:
npx hinge-kit --help

From source (GitHub):

git clone https://github.com/akj1608/hinge-kit.git
cd hinge-kit
npm install
npm run build
npm test

Quick start

# write conservative config (~/.hinge-kit/config.json)
hinge-kit init

# login
hinge-kit auth login --phone +15555550123
hinge-kit auth verify-otp --otp 123456

# preview recommendations + filters (no likes)
hinge-kit recs

# discover with dry-run likes preview
hinge-kit discover --like

# only after accepting account risk:
hinge-kit discover --like --live

Configuration

Default path: ~/.hinge-kit/config.json (mode 600). Override with -c/--config or HINGE_KIT_CONFIG.

| Field | Meaning | | --- | --- | | activeProfile | Which named profile’s session to use | | profiles[] | Per-profile name, optional phoneNumber, sessionFile, cacheDir | | dataDir | Root for sessions, cache, stats (default ~/.hinge-kit) | | filters | Local accept/reject rules applied after fetch | | safety.dryRunDefault | true (default): writes preview unless --live | | safety.maxLikesPerRun / maxLikesPerDay | Hard caps | | safety.minActionDelayMs / maxActionDelayMs | Random delay between live actions | | recs.* | Discover fetch knobs | | schedule.* | Interval cycles for schedule | | templates[] | Named message bodies with {{var}} placeholders |

Environment overrides:

| Variable | Role | | --- | --- | | HINGE_KIT_CONFIG | Config path | | HINGE_KIT_PROFILE | Profile name | | HINGE_KIT_PHONE | Phone for login / client builder |

See config.example.json in this repo.

Multi-profile

hinge-kit profiles list
hinge-kit profiles add --name alt --phone +15555550199
hinge-kit -p alt auth status

Each profile stores session, cache, daily counters, and stats under ~/.hinge-kit/profiles/<name>/ unless overridden.

CLI reference

Global options: -c/--config, -p/--profile, --phone, --debug.

Auth

hinge-kit auth status
hinge-kit auth login --phone +15555550123
hinge-kit auth verify-otp --otp 123456
hinge-kit auth verify-email --case-id <caseId> --code 654321
hinge-kit auth logout

Read

| Command | Purpose | | --- | --- | | me | Own profile, content, like limit | | recs | Discover feed + filter preview | | likes | Likes received + remaining likes/roses | | standouts | Standouts feed | | matches | Connections list | | match --subject-id <id> | Match detail + note | | chats | Chat channels | | messages --channel-url … or --partner … | Message history | | preferences | Dating preferences | | prompts [--query] [--category] | Prompt catalog | | templates | Message templates | | stats | Local analytics | | config / config --validate | Show or validate config |

Write / automation (dry-run by default)

When safety.dryRunDefault is true, these preview unless you pass --live. --dry-run forces preview.

hinge-kit like --subject-id ID --rating-token TOKEN
hinge-kit skip --subject-id ID --rating-token TOKEN
hinge-kit message --subject-id ID --text "hey"
hinge-kit message --subject-id ID --template hello --var firstName=Ada

hinge-kit discover --like
hinge-kit discover --like --skip-rejected
hinge-kit discover --like --live

hinge-kit schedule --cycles 1
hinge-kit schedule --cycles 3 --interval-minutes 90 --live

hinge-kit preferences-update --json '{"maxDistance":50}'
hinge-kit export --stats
hinge-kit export --chat <channelUrl> --out ./chat.txt

like also supports --comment, --content-id, --question, --answer, --photo-url, --rose, --origin.

Escape hatch (still requires --live to execute):

hinge-kit raw --service hinge --method GET --path /likelimit --live

Filters

Applied locally after fetching profiles/content:

• minAge / maxAge
• minHeightCm / maxHeightCm
• locationIncludes[]
• requireKeywords[] / excludeKeywords[]
• requirePromptAnswer

Verify with recs or discover before --live.

Safety

• Dry-run default for batch and write actions
• Per-run and per-day like caps; per-run skip/message caps
• Jittered delay between live actions
• Retries with backoff on network errors and HTTP 429/502/503
• Redacted logging for auth headers when logging.redact is true

Programmatic SDK

import {
  HingeClient,
  BrowserFetchTransport,
  NodeFileStorage,
  runDiscover,
  loadConfig
} from "hinge-kit";

Also available: import { HingeClient } from "hinge-kit/sdk".

Scripts (from source)

| Script | Purpose | | --- | --- | | npm run build | Compile TypeScript to dist/ | | npm run typecheck | Typecheck without emit | | npm test | Build + node test suite | | npm start / npm run hinge-kit | Run the CLI |

Layout

• src/sdk/ — Hinge + Sendbird client, transport, storage
• src/cli/ — hinge-kit command surface
• src/automation/ — filters, safety, discover, schedule, stats, templates, retry
• src/config/ — Zod-validated config

Limitations

• Unofficial private API behavior can break when Hinge changes servers.
• Node direct transport may be blocked or fingerprint differently than the mobile app.
• Most CLI flows use REST; realtime features need the Node WebSocket transport and a live session.

License

MIT. See LICENSE.