Reference

CLI reference

Every personkit subcommand shipped today, grouped by what you do with it.

This page mirrors what personkit --help prints. Every command listed here is in the binary now.

Get started

personkit setup

Orchestrates the full first-run flow: sign in → [1/4] connect → [2/4] corpus init → [3/4] seed → [4/4] verify surfaces. The seed step auto-discovers your git repos and ingests the last 30 days.

• --relay <url> — point at a non-default relay (persisted into credentials.json).
• --no-auto-connect — stop after sign-in and print the manual connect / doctor recipe instead of running the four steps.

personkit doctor

Surface-by-surface health check. Reports signed-in state, wired tools, observer / harvester last-run times, breaker state, corpus + daemon health.

• --errors [--since <d>] — pull recent observer_errors from the relay.

personkit status

Shows your AI’s identity and where it’s connected. Cheaper than doctor — just lists wired surfaces.

Day-to-day

personkit connect

Wires the persona projection into every detected AI surface. Idempotent.

• --tool <id> — wire a single surface (e.g. cursor, claude-code).
• --all — wire everything detected.
• --uninstall — remove the projection.
• --dry-run — show what would change without writing.

Editor and agent targets (--tool ids): claude-code, vscode, copilot, cursor, windsurf, zed, jetbrains, antigravity, augment, continue, cline, aider, codex, factory-droid, opencode, gemini. Every MCP entry they write pins @aiperson/mcp-server@0.8.1, never @latest (whose dist-tag can lag the repo), so re-running connect is what upgrades the server. Each entry also names its tool in PERSONKIT_SOURCE_SURFACE, so your AI’s history records which tool a change came from. Before writing anything, connect checks that npm can resolve the pinned server, and stops if it can’t.

Local-model runtimes get a projection, not a proxy: connect writes the persona as a system prompt in the runtime’s own format and, where the runtime has a CLI or API, registers it. Inference still runs entirely on your machine; personkit never sits in the request path.

Every rules-file and system-prompt projection is bounded to 20,000 characters. Identity, voice, signatures, every refusal, every value and every global convention always fit (their prose is shortened rather than dropped); scoped conventions fill the rest newest-first; and a trailing <!-- projected N of M conventions; budget B chars --> says what was left out. Override with PERSONKIT_PROJECTION_BUDGET=<chars> (2,000–60,000).

personkit login

Opens a browser tab on aiperson.one, signs you in via GitHub, persists credentials at ~/.dotperson/credentials.json.

personkit sync

Alias for personkit observe — one sweep of every observer (Continue, Cursor, Copilot Chat, Windsurf, Gemini-CLI, Claude Desktop presence-check), then POST to the relay’s /v1/observations and mirror each observation into the local messages table.

personkit import [--name <slug>]

Pick up settings or transcripts you already have in other AI tools. Supports --name chatgpt for ChatGPT export zips, --name <other> for other surfaces.

personkit uninstall [--yes]

Disconnect everything and wipe local config. Tears down the daemon’s job — the legacy observer plist and the unified daemon plist on macOS, the systemd units on Linux.

The corpus

personkit corpus init

Create ~/.dotperson/corpus.db and run all migrations (currently up to schema v2 — threads + messages).

personkit corpus seed [--repo P]... [--since 30d]

Seed git history into the corpus. Reads commits from each --repo and emits git_event rows.

personkit corpus query <text>

Hybrid retrieval (FTS5 + sqlite-vec + entity + temporal, fused with reciprocal rank fusion, k=60).

• --kind <k> (repeatable) — restrict to event kinds.
• --surface <s> (repeatable) — restrict to surfaces.
• --entity <id> (repeatable) — restrict to events referencing the entity.
• --since <d|h|m> — temporal lower bound (default unbounded).
• --until <d|h|m> — temporal upper bound.
• --limit N — default 10.
• --json — machine-readable output.

personkit corpus recent

Most-recent events, no text search.

• --surface <s> — restrict to one source.
• --limit N — default 20.
• --json.

personkit corpus entity <id>

Read one entity by id (git:<sha>, repo:<path>, person:<name>, …).

personkit corpus health

Counts per table (events, threads, messages, entities, relations, embeddings), pending-embedding counts, schema version, vec availability, embedder selection. The first thing to check when retrieval is acting strange.

personkit corpus surfaces [--since 7d] [--json]

Per-surface roll-up of recent threads — source_surface, thread count, last-message timestamp. Useful for confirming “is dotperson seeing what I expect across the chat surfaces I use.” Pairs with corpus messages for drill-in.

personkit corpus messages [--surface <id>] [--since 7d] [--limit 20] [--json]

Flatten recent threads to a per-message feed. Filter to one surface (browser-ext:chatgpt, browser-ext:kimi, claude_code, etc.) or scan all. Each row is role + content preview + timestamp. The MCP corpus_messages tool shells out to this; the assistant can answer “show me what I said to Kimi today” without leaving the chat.

personkit corpus embed [--batch 16] [--max 2000]

Backfill embeddings for events lacking them. Uses the configured embedder (Vertex when GCP_PROJECT_ID is set; fastembed when built with that feature). The daemon calls the same helper on every cycle.

personkit corpus record-turn

Universal capture entry point. Reads JSON from stdin (or --input <file>), upserts the thread, inserts the message, prints {thread_id, message_id} on stdout. The MCP record_turn tool shells out to this; the browser extension can fall back to it; any agent on any surface can call it.

personkit corpus snapshot

Signed JSONL export of every corpus table — sister to the markdown export, aimed at machines + crypto rather than humans. Each table becomes a JSONL file under <dir>/, plus a manifest.json carrying per-file SHA-256 hashes + (when --key is supplied) an Ed25519 signature.

• --out <dir> — destination (default ~/.dotperson/snapshots/<UTC-timestamp>/).
• --key <secret-b64-or-path> — sign the manifest with this Ed25519 key. Accepts the raw base64 secret or a path containing one. Use personkit keygen --out <path> to mint one.
• --json — machine-readable summary on stdout.

Includes V2 tables (threads, messages) automatically.

personkit corpus restore

Round-trip a snapshot back into a corpus. Inverse of snapshot.

• --from <dir> — snapshot directory.
• --into <path> — write into a different DB instead of ~/.dotperson/corpus.db (useful for archive verification).
• --verify-only — verify the manifest signature and report row counts without writing.

Existing rows in the target corpus are preserved (entities + threads are INSERT OR REPLACE; events + messages are INSERT OR IGNORE so content-hash dedupe wins).

personkit corpus wipe

Wipe the local corpus DB. Interactive by default — asks for confirmation and reports counts of what will be removed.

• --yes / -y — skip the prompt.
• --keep-persona — preserve credentials.json, persona.cache.json, harvester/observer state. Without this flag everything under ~/.dotperson/ except the daemon plist is cleared.
• --dry-run — show what would be removed without doing anything.
• --json — machine-readable.

personkit corpus sync push|pull|serve

Cross-device sync against the relay.

• push [--limit N] — push new events (those with allow_relay_mirror=true).
• pull — pull events newer than the local watermark.
• serve [--once] — loop both forever (the daemon does this for you).

Daily memory

personkit today / personkit brief

The daily brief — recent threads + git activity in the last N hours.

• --hours N — default 24.
• --limit N — default 15.
• --json — machine-readable output.

personkit export --format=markdown

Export the corpus as portable .md files (Obsidian-friendly). Each thread becomes one file with YAML front-matter and turns as block-quotes.

• --out <dir> — default ~/.dotperson/export/.
• --since-hours N — optional time-bound.
• --max N — cap thread count (default 10k).

Background

personkit daemon

The unified background loop, run every five minutes by your system’s scheduler: one launchd job (one.aiperson.personkit-daemon) on macOS, which replaces the legacy observer-only plist, or a systemd user service and timer (~/.config/systemd/user/personkit-daemon.{service,timer}) on Linux.

• --install (a.k.a. --install-background) — install the job and start it. On macOS it migrates off the legacy observer plist automatically; on Linux it runs systemctl --user enable --now personkit-daemon.timer.
• --once — run one cycle in the foreground.
• --serve — foreground loop (for debugging, or a machine with no launchd or systemd user session).
• --uninstall — stop and remove the job.

Each cycle runs: harvest → embed → observe → sync → connector-drain → synthesise (deterministic synthesis only; LLM hook stays gated behind PERSONKIT_SYNTHESIS_LLM_OK=1).

personkit synthesise [--hours 24] [--with-llm]

Nightly housekeeping: embedder backfill (events + messages), entity-alias resolution, templated thread summaries. Wired into the daemon by default; runnable on demand for debugging.

personkit harvest run-once|serve|enable|disable

• run-once [--id <id>] — single pass of every (or one) harvester.
• serve — long-running loop (used by daemon --serve).
• enable <id> / disable <id> — toggle in ~/.dotperson/harvesters/enabled.json.

Discovery

personkit connectors [--json]

List every thread connector and whether its source is available on this host: browser_extension, openai_export, anthropic_api, openai_api.

personkit plugin list|install|remove|info

Community plugin manager. Plugins live in ~/.dotperson/plugins/<id>/plugin.json.

• personkit plugin list [--json]
• personkit plugin install <local-directory>
• personkit plugin remove <id>
• personkit plugin info <id>

personkit voice capture <audio-file> [--model <name>]

Whisper bridge: invokes a local whisper (or whisper-cpp) binary, takes the transcript, upserts a voice thread, inserts the transcript as a user-role message. Default model is base.en.

personkit prefs list|get|set|unset|path

Local preference manager — mirrors the dashboard’s /dashboard/advanced page in the terminal. Preferences live in ~/.dotperson/preferences.json as a flat JSON object with dotted keys.

• personkit prefs list [--json] — show every set preference.
• personkit prefs get <key> — read one (returns (unset) when absent).
• personkit prefs set <key>=<value> — write one. Booleans (true/false), integers, floats, and inline JSON ({...}, [...]) are coerced; everything else is a string. Use --sync to also PUT /v1/me/preferences so the dashboard sees the change.
• personkit prefs unset <key> — remove.
• personkit prefs path — print the file path (useful for editor integration).

Examples:

personkit prefs set theme=dark
personkit prefs set corpus.sync_interval_secs=300
personkit prefs set daemon.synthesise.with_llm=true --sync

personkit verify surfaces

Per-surface presence + content check. Also runs a stdio MCP smoke handshake against dotperson-mcp (initialize → list tools → corpus_health).

Advanced (the original git-substrate surface)

These predate the memory layer and remain for working directly with .person files:

• personkit parse <file> — validate a .person JSON.
• personkit keygen [--out <path>] — Ed25519 keypair.
• personkit sign <file> --key <secret> — sign a .person.
• personkit verify <file> — verify the signature.
• personkit init <dir> — empty profile repo.
• personkit clone <url> <dir> [--token <pat>] — clone a profile repo.
• personkit commit <repo-dir> <file> "<msg>" — commit a .person.
• personkit push <repo-dir> / pull <repo-dir> — sync the profile repo.