Work with your contact book

Start without an account

Install the verified public CLI on macOS or Linux with Bun 1.3.14 or newer. Initialize an empty database before granting source access. These commands need no cloud account, provider credential, or contact import.

bun add --global @hraness/peopleblade@0.4.1
peopleblade --version
peopleblade init --json
peopleblade stats --json

Use --help to inspect a command before running it. Apple Contacts and iMessage imports require macOS; other sources have their own platform and permission requirements in the source directory.

Import sources before buying enrichment

Approved local contacts, official owner archives, and existing relationship metadata can supply useful context before any paid research. Choose each source explicitly. PeopleBlade keeps source records and their completeness limits instead of flattening observations into an unexplained contact.

# macOS: read Apple Contacts without writing back
peopleblade contacts sync --json
peopleblade stats --json

Ghostget owns authentication and transport for supported live Google, Beeper, and WhatsApp operations and for the LinkedIn Contact-info read. LinkedIn connections come only from your official export. After that import, one command reads the Contact info panel (email, phone numbers, websites, birthday) of a single first-degree connection through Ghostget from your signed-in browser profile; it never lists connections, reads messages or feeds, or guesses a hidden field. A logged-in LinkedIn browser session is not a connector for listing connections or permission to scrape. Blocked and planned adapters remain unavailable even when an agent can operate a browser.

peopleblade linkedin import /path/to/Complete_LinkedInDataExport.zip --account linkedin-main
peopleblade linkedin contact-info --person-id ID --json

Message text is not retained, searched, used for enrichment, or uploaded by provider imports. Only approved participant, timing, and body-free relationship metadata can enter the graph.

Review duplicates without losing their sources

peopleblade identity suggest --limit 25 --json
peopleblade identity decide TOKEN accept --note "reviewed exact evidence" --json
# Only to reverse that accepted decision:
peopleblade identity separate DECISION_ID --json

Keep the decisionId from the identity decide receipt. Use that ID if you later choose to separate the accepted component; do not rely on a filtered listing to recover it.

Read the evidence before accepting a fresh decision token. Similar names, employers, or shared household phone numbers do not authorize a silent merge. A reviewed decision joins a derived contact component while original source records retain their owners. Separation reverses the decision without deleting those records.

# Observed-overlap inspection, not the complete decision history
peopleblade identity audit --json
peopleblade identity decisions --json

The audit reports observed-overlap risk counts. The decisions command lists currently accepted observed-email and observed-phone decisions only; exact-email and exact-phone decisions are not included.

Interaction totals account for overlapping sources. Treat them as bounded relationship evidence, not a complete message history or an exact measure of relationship strength.

Find and inspect a person

peopleblade capabilities --json
peopleblade query --search "Ada" --sort name --direction asc --limit 50 --json
peopleblade people show 12 --json

Query searches names, companies, titles, active contact methods, and provider handles. Filter by source, email or phone presence, and do-not-contact status. Search punctuation is literal, not SQL wildcard syntax. Use source facet keys from the result, not capability identifiers.

Each bounded page returns total, offset, limit, and nextOffset. Pass nextOffset as --offset to continue. Pages are a live view: imports and identity decisions can move rows between requests, so restart at offset zero after changes. Existing list commands retain their original output shape.

Capability discovery is a no-database, no-network declaration of supported interfaces. It does not prove that a tool, credential, permission, or provider is configured. Person details expose totals and truncation markers; displayed contact values are not automatically trusted identity-join evidence.

Open a private contact workspace

peopleblade ui

Open the printed loopback URL and select the printed access.json file. It lives in a new owner-only directory; the capability stays in the tab's memory, not browser storage, cookies, page source, or the URL. Stop the CLI with Ctrl+C to invalidate access. This does not protect against another process already running as your operating-system user.

The workspace provides searchable, filtered pages of 50 contacts, sortable columns, person details, private note search, and Markdown editing. It performs no cloud sync, provider collection, enrichment, or outreach. --port N chooses a loopback port; the server cannot be exposed to the network through a CLI option.

Markdown source remains authoritative. Preview supports headings, lists, checklists, tables, emphasis, code, and safe HTTP(S) links. Raw HTML is text, images are omitted, and previews load no remote assets.

Edit notes with a recoverable history

peopleblade notes list --person-id 12 --json
peopleblade notes show 42 --json
peopleblade notes update 42 --expected-revision 0 \
  --expected-context CONTEXT_SHA256 --request-id REQUEST_UUID \
  --body-file /private/path/note.md --title "Follow-up" --json
peopleblade notes history 42 --json

Use the current revision and context digest from notes show and a fresh UUID for a new save. --body-file - reads bounded UTF-8 from stdin so private note text need not appear in shell arguments. Use command help for the explicit title-clearing option.

Edits append user revisions without replacing imported content, occurrence dates, source provenance, or the attribution ledger. Search uses current content; history retains earlier versions. Restoring old text creates another revision.

If content, attribution, or identity changes during an edit, preserve the draft and reload before saving. After an uncertain transport outcome, retry the same request UUID with the exact same payload; do not invent a second save. The workspace retains that retry and can download a draft before you close the tab.

Notes and revisions are excluded from cloud sync, public research, and agent source packets. Keep exported drafts private too.

Choose enrichment by evidence and cost

1. Begin with approved local sources and official archives; review exact identity overlaps before adding claims.
2. Prepare public research for one selected person. A human or authorized agent supplies reviewed citations, or abstains. PeopleBlade does not call a provider in this local workflow; the agent's search and model tools may charge separately.
3. Preview optional cloud research only when useful. Configured execution uses Exa exact-profile retrieval or bounded search, followed by cited model extraction.
4. Treat Hunter as an optional, narrowly gated email fallback. It does not replace identity evidence or the local graph and never authorizes guessed addresses.

peopleblade research prepare PERSON_ID > /private/path/research.json
# Fill only result with reviewed public citations, or abstain
peopleblade research apply /private/path/research.json --json

Keep the template's subject and instructions intact. Public claims need evidence for each retained field. Research does not authorize contacting anyone, collecting authenticated social graphs, or expanding a provider's permissions.

Cloud enrichment requires sign-in, synced contacts, and preview confirmation before dispatch. Preserve the accepted job ID: if a status read fails, check that job instead of submitting another paid request. The dashboard shows the maximum product-credit charge before confirmation; a product credit is charged only for a completed contact with at least one supported field.

Prepare context for an agent

Choose one person, review their background and cited public research, and decide which agent environment may receive the result. Creating a packet does not send it to an agent or give an agent access to your contact book.

peopleblade soulscrape prepare PERSON_ID --output /private/path/peopleblade-soulscrape-source.json --json

The explicit Soulscrape source packet is a new owner-selected mode-0600 file. It contains canonical subject background and current cited public-enrichment evidence, and excludes CRM notes, messages, raw source or provider payloads, unrelated contacts, public-email claims, and exact stored email, phone, or provider-handle coordinates.

CLI use and packet creation do not require the separate source-checkout validator, which is not included in the npm package. Before opening or interpreting packet records, an authorized receiver must validate the packet successfully: zero exit status and a receipt with valid: true. A failed check is a hard stop; do not inspect or partially use the packet.

# Receiver: from an authorized source checkout, before opening records
bun skills/soulscrape/scripts/validate-source-packet.ts /private/path/peopleblade-soulscrape-source.json

Require both a zero exit status and valid: true in the receipt. A validated file is still source material, not consent, identity authority, a voice profile, or permission to contact or act for anyone. Share it only with the person or agent environment you authorized.

Use the hosted projection deliberately

peopleblade cloud signin
peopleblade cloud sync

Sync only when you want the private hosted view. It receives normalized contacts, active contact methods, approved aggregate interaction facts, identity anchors, and enrichment evidence. It receives no notes, note revisions, raw source records, message text, archives, local paths, or provider credentials.

The updated dashboard offers account-scoped search, URL filters, sorting, source facets, and contact details. Selection applies to the displayed page only. Export all contacts exports the account's complete projection, not just filtered rows. CSV protects spreadsheet formula-like string cells with an apostrophe prefix; use JSON when exact string bytes matter.

The hosted CLI routes are authenticated device-protocol endpoints, not a public general contact API. Prefer the documented CLI over ad hoc SQL or undocumented HTTP calls. No public MCP server, GraphQL endpoint, or OAuth application is implied.

Back up before larger changes

peopleblade backup

Schema upgrades create a private backup before applying migrations. Make another before a large import or identity-review session. Keep the original database and backup until any restored copy passes integrity and data checks, and never replace a database while the CLI or workspace has it open.

Contact and note editing do not change account ownership or the passwordless migration process. Treat contact JSON, notes, backups, and agent packets as private data, even when they contain no credentials.