CLI Reference

CLI Reference

Grounded reference for the threadnote CLI. Every command is defined in src/threadnote.ts; entries below list each command's purpose and the flags confirmed there. Global options apply to every command.

Global Options

These are accepted on the root threadnote command and inherited by subcommands.

Option	Purpose
--home <path>	Override THREADNOTE_HOME for this invocation.
--manifest <path>	Override THREADNOTE_MANIFEST for this invocation.
--host <host>	OpenViking host (default 127.0.0.1).
--port <port>	OpenViking port (default 1933).

Dry-Run Conventions

Behavior is not uniform, so check per command:

• mcp-install and install-hooks print the planned change by default and only modify agent config with --apply.
• migrate-lifecycle and compact dry-run by default and require --apply to act.
• Most other commands take an explicit --dry-run to preview without changing anything, including doctor, install, uninstall, repair, start, stop, update, seed, seed-skills, init-manifest, migrate-memories, the memory commands (remember, handoff, recall, read, list, archive, forget), export-pack, import-pack, and every share subcommand.

From a source checkout, prefix any command with the npm script: npm run threadnote -- <command>.

Setup and Lifecycle

doctor

Check local prerequisites, config files, manifest shape, and server health.

• --dry-run — show checks without writing anything.
• --strict — exit non-zero if any check fails.

install

Install OpenViking, local config files, the command shim, and user-level agent instructions.

• --dry-run — print actions without making changes.
• --force — reinstall OpenViking at the pinned version even if a working install is present.
• --no-start — do not start OpenViking or check health after installing.
• --package-manager <manager> — uv, pipx, or pip.
• --with-hooks — also install agent-side hooks (Claude PreCompact + SessionStart) across supported agents.

repair

Repair the local OpenViking install, config files, server health, shim, manifest, and MCP config.

• --dry-run — print repair actions without making changes.
• --mcp <clients> — clients to repair: available (default), all, none, codex, claude, cursor, copilot, or a comma-separated list.
• --no-start — do not start OpenViking if health is failing.
• --no-post-update — skip post-update migration prompts after repair.
• --package-manager <manager> — uv, pipx, or pip.

start

Start the local OpenViking server.

• --dry-run — print the start command without running it.
• --foreground — run in the foreground instead of detaching.
• --launchd — install and start a macOS LaunchAgent.

stop

Stop the local OpenViking server or LaunchAgent.

• --dry-run — print the stop actions without running them.

uninstall

Remove Threadnote setup and optionally erase local memories.

• --dry-run — print uninstall actions without making changes.
• --mcp <clients> — clients to remove: available (default), all, none, codex, claude, cursor, copilot, or a comma-separated list.
• --preserve-memories — preserve THREADNOTE_HOME and OpenViking memories (default).
• --erase-memories — delete THREADNOTE_HOME, including all OpenViking memories.

version

Print the installed Threadnote version, latest npm version, and release notes.

• --registry <url> — npm registry URL.

update

Update the published Threadnote package, then repair local shims and MCP config.

• --check — only check whether a newer version is available.
• --dry-run — print update and repair commands without running them.
• --force — run the package-manager update even if already current.
• --registry <url> — npm registry URL.
• --runtime <runtime> — auto (default), npm, bun, or deno.
• --no-repair — skip repair after updating the package.
• --no-post-update — skip post-update migration prompts.
• --yes — accept applicable post-update migrations without prompting.

Manifest and Seeding

init-manifest

Create or update a per-developer seed manifest from one or more repo roots.

• --dry-run — print the manifest without writing it.
• --path <path> — manifest path; defaults to THREADNOTE_MANIFEST or ~/.openviking/seed-manifest.yaml.
• --replace — replace the manifest instead of merging with existing projects.
• --repo <path> — repo root to include; repeat for multiple repos.

seed

Seed curated context from the manifest; never indexes whole repos by default.

• --dry-run — print files and ov commands without importing.
• --force — re-upload every candidate even if mtime and size match the recorded state.
• --manifest <path> — manifest path for this seed run.
• --only <project> — restrict seeding to one or more manifest projects by name; repeat for multiple.

seed-skills

Seed Codex, Claude, and repo-local SKILL.md files as a searchable catalog.

• --dry-run — print skill files and ov commands without importing.
• --manifest <path> — manifest path for repo-local skill discovery.
• --native — use native OpenViking skill ingestion; requires a working VLM config.

Agent Integration

mcp-install <agent>

Install OpenViking MCP config for a supported agent (codex, claude, cursor, or copilot). Prints by default.

• --apply — actually modify the selected agent config.
• --name <name> — MCP server name.
• --native-http — install the OpenViking native HTTP MCP endpoint instead of the local stdio adapter.
• --scope <scope> — Claude MCP config scope: user (default), local, or project.
• --url <url> — OpenViking native HTTP MCP URL.
• --bearer-token-env-var <name> — environment variable containing the local API key.

install-hooks <agent>

Install deterministic agent hooks (Claude PreCompact + SessionStart). Prints by default; Codex/Cursor/Copilot are no-ops that print an explanation.

• --apply — actually modify the selected agent config.
• --dry-run — print the planned change without applying it.
• --remove — remove threadnote-managed hook entries instead of adding them.

Memory

remember

Store a durable engineering memory in OpenViking.

• --dry-run — print memory and ov command without storing.
• --kind <kind> — durable (default), handoff, incident, preference, or smoke.
• --project <name> — project/repo/topic namespace for lifecycle-aware storage.
• --replace <uri> — supersede an existing viking:// memory after the new memory is stored.
• --source-agent-client <name> — codex (default), claude, cursor, copilot, or another client name.
• --status <status> — active (default), archived, or superseded.
• --stdin — read memory text from stdin.
• --text <text> — memory text to store.
• --topic <name> — stable topic name; active memories with the same project/topic update one file.

handoff

Capture current repo state as a durable cross-agent handoff memory. Bare invocation uses the current repo and git branch as project/topic.

• --blockers <text> — known blockers.
• --dry-run — print handoff without storing.
• --next-step <text> — suggested next step.
• --project <name> — project/repo namespace; defaults to the current repo basename.
• --replace <uri> — supersede an existing viking:// memory after the new handoff is stored.
• --source-agent-client <name> — codex (default), claude, cursor, copilot, or another client name.
• --task <text> — current task summary.
• --tests <text> — tests or checks run.
• --timestamped — store a historical timestamped handoff instead of updating the current branch handoff.
• --topic <name> — stable topic name; active handoffs with the same project/topic update one file.

recall

Search shared OpenViking context. --query is required.

• --query <query> — search query (required).
• --dry-run — print ov command without searching.
• --include-archived — include archived memories in exact memory/resource matches.
• -n, --node-limit <count> — maximum number of search results.
• --no-infer-scope — disable query-based scope inference.
• --uri <uri> — restrict search to a viking:// URI.

read <uri>

Read a viking:// URI returned by recall or list.

• --dry-run — print ov command without reading.

list / ls [uri]

List a viking:// directory (defaults to viking://).

• -a, --all — show hidden files such as .abstract.md and .overview.md.
• --dry-run — print ov command without listing.
• -n, --node-limit <count> — maximum number of nodes to list.
• -r, --recursive — list subdirectories recursively.
• -s, --simple — print only paths.

archive <uri>

Move a memory into the archived lifecycle tree, then remove the original after the archive is stored.

• --dry-run — print archive content and ov commands without changing anything.
• --kind <kind> — durable, handoff, incident, preference, or smoke.
• --project <name> — override the inferred project/repo namespace.
• --topic <name> — override the inferred topic.

forget <uri>

Remove a viking:// URI from local OpenViking context.

• --dry-run — print ov command without deleting.

compact

Plan or apply scoped memory hygiene for active personal memories. --project is required; dry-run by default.

• --project <name> — project/repo namespace to inspect (required).
• --apply — apply the compact plan; without this, prints a dry run.
• --dry-run — print the compact plan without changing anything.
• --kind <kind> — durable, handoff, or incident.
• --topic <name> — stable topic name to inspect.

Migrations

migrate-memories

Migrate legacy session-only Threadnote memories into durable memory files.

• --all-accounts — scan all local OpenViking accounts under THREADNOTE_HOME.
• --dry-run — print migration actions without writing memories.
• --limit <count> — maximum number of memories to migrate.
• --source-account <account> — source OpenViking account to scan; repeat for multiple accounts.

migrate-lifecycle

Move clear legacy handoff memories into lifecycle-aware archive paths. Dry-runs by default.

• --apply — perform the migration; without this, prints a dry run.
• --dry-run — print migration actions without writing or removing memories.
• --limit <count> — maximum number of legacy handoffs to migrate.

Packs

export-pack

Export local OpenViking context to an .ovpack.

• --dry-run — print ov command without exporting.
• --path <path> — output .ovpack path.
• --uri <uri> — source viking:// URI to export (default viking://).

import-pack

Import an .ovpack into local OpenViking context. --path is required.

• --path <path> — input .ovpack path (required).
• --dry-run — print ov command without importing.
• --target-uri <uri> — target parent viking:// URI (default viking://).

Sharing

All share subcommands accept --dry-run. See Sharing Memories for the full workflow and the publish-time scrubber rules.

share init <remote-url>

Configure a shared memories repo for a team (clones the remote into the local memory tree).

• --team <name> — team name; defaults to default.
• --set-default — mark this team as the default for future share commands.
• --no-push — do not push the auto-generated .gitignore housekeeping commit.
• --dry-run — print actions without running them.

share status

Show git status and ahead/behind counts for a shared team.

• --team <name> — team name; defaults to the configured default team.
• --dry-run — print git commands without running them.

share sync

Pull, reindex, and push the shared memories repo for a team.

• --team <name> — team name; defaults to the configured default team.
• --message <text> — commit message when auto-committing local edits.
• --no-auto-commit — refuse to sync if there are uncommitted local changes.
• --no-push — skip the push step after pulling and reindexing.
• --dry-run — print actions without running them.

share publish <viking-uri>

Move a personal memory into the shared team namespace, commit, and push.

• --team <name> — team name; defaults to the configured default team.
• --message <text> — commit message override.
• --no-push — skip the push step.
• --dry-run — print actions without running them.
• --preview — print the exact bytes that would land in the shared repo (after frontmatter strip and scrubber redaction) without writing, committing, or pushing.
• --redact — replace soft-leak matches (local paths) with placeholders and continue; credentials still block.

share unpublish <viking-uri>

Pull a shared memory back into the personal namespace, commit the removal, and push.

• --team <name> — team name; defaults to the configured default team.
• --message <text> — commit message override.
• --no-push — skip the push step.
• --dry-run — print actions without running them.

share list

List configured shared teams.

• --dry-run — print without side effects (no-op for list).

share rename

Rename a configured shared team. Both options are required.

• --team <name> — existing team name (required).
• --to <name> — new team name (required).
• --dry-run — print actions without running them.

share set-url <remote-url>

Change the git remote URL for a configured shared team.

• --team <name> — team name; defaults to the configured default team.
• --dry-run — print actions without running them.

share remove

Forget a configured team and optionally delete its worktree/gitdir.

• --team <name> — team name; defaults to the configured default team.
• --keep-files — keep the worktree and gitdir on disk; only forget the team entry.
• --preserve-local — copy shared durable memories into the personal tree before removing the team.
• --dry-run — print actions without running them.

Manager UI

manage

Open the local React web manager for browsing, recalling, reading, editing, archiving, forgetting, publishing, consolidating, and diagnosing memories. It binds to 127.0.0.1 with a per-session token. See Web Manager for a full tour.

• --ui-port <port> — port for the local manager UI; defaults to a random free port.
• --no-open — start the manager without opening a browser.

See also

Memory Lifecycle, Recall and Read, Sharing Memories, Installation