CLI reference

CLI or GUI: both included

Geneziz is one product with two faces. The desktop app gives you the GUI; the CLI gives you the same engine in your terminal - and both ship in the $99 one-time license. There is no CLI-only tier and nothing extra to buy.

The command line is not a second-class surface: the desktop app itself runs these exact commands under the hood (as its bundled geneziz-cli sidecar), so what works in the app works in your terminal, and what you script in the terminal is what the app would have done.

The surface: 45 commands and command groups in geneziz --help, plus 17 subcommands under the 9 groups - 62 command paths in all. This page walks through all of them, grouped by pipeline stage.

Install and setup

You already have the CLI if you have the app - the desktop app bundles it as its engine. For standalone use (cron jobs, scripts, servers):

# pip installable; installs the `geneziz` entry point
pip install geneziz

# or run without installing
python -m geneziz

The desktop app auto-detects its bundled CLI, so app-side features (the extension bridge, MCP registration, the search daemon) need no PATH setup. For your own shells, the geneziz executable on PATH is all you need.

Every command takes --config (or -c) to point at a config file; without it, Geneziz uses geneziz.config.json in the working directory. geneziz --version prints the version. geneziz <command> --help prints the full flag list - the same source this page was written from.

New machine? Start with geneziz setup (interactive wizard) or geneziz init (write a default config). The knowledge base itself is plain Markdown + YAML - see the vault.

Fetch: get things in

geneziz fetch

Fetch a unified source - github, bluesky, youtube, instagram, hackernews, reddit - via its official API, or resolve a single item by URL:

geneziz fetch --source github          # your GitHub stars
geneziz fetch --source reddit --all    # everything Reddit saved
geneziz fetch --url "https://youtu.be/…"   # one video, no login needed

Fetched items land in a crash-safe queue (.state/) for geneziz process. X.com bookmarks flow in through the browser extension into the same queue - the CLI never scrapes X.

geneziz run

The whole pipeline in one command: fetch → process → index.

geneziz run                            # default source, AI on
geneziz run --source github --no-ai    # deterministic filing only

Accepts the fetch flags (--source, --url, --count, --all, --max-pages, --account) plus --no-ai and --track-tokens (-t).

geneziz sync

Sync loop over your configured sources - the app's Sync button runs the same engine.

geneziz sync                # everything configured
geneziz sync --bookmarks    # bookmarks only
geneziz sync --stars        # GitHub stars only

geneziz hydrate

Download the substance behind your entries: article content and images, tweet media, YouTube transcripts.

geneziz hydrate                          # articles (default)
geneziz hydrate --kind media             # images and videos from tweets
geneziz hydrate --kind all
geneziz hydrate --gaps                   # backfill only what is missing
geneziz hydrate --gaps --dry-run         # report without writing

--kind takes articles, media, transcripts, or all; --limit caps the run.

Process: make it knowledge

geneziz process

Process the pending queue into the knowledge base: dedupe against what you already have, fetch README content for GitHub links, search for the original post text behind article links, and file each item with AI category, tags, and description (or deterministically with --no-ai).

geneziz process                    # drain the queue
geneziz process --limit 10         # small batches
geneziz process --top 50           # keep only the top 50 by engagement (saves AI cost)
geneziz process -t                 # show the token/cost table

geneziz index

Regenerate the viewer index and the FTS5 search database. Runs automatically after geneziz process and geneziz web - run it by hand after editing files.

geneziz index

geneziz vectors

Build the ChromaDB vector index that powers semantic search (license tier; the bare build is a clean no-op on lower tiers):

geneziz vectors             # incremental build
geneziz vectors rebuild     # drop and fully re-embed (after an embedder model swap)

geneziz organize

Re-file and tidy existing knowledge items - descriptions, categories, tags. --all re-organizes even items that were already organized. With AI (credits) or deterministic.

geneziz gaps

Quality scan over the library: missing descriptions, categories, domains, empty bodies, missing media.

geneziz gaps --dry-run      # report only
geneziz gaps                # fill what it can
geneziz gaps --json         # machine-readable report

geneziz ocr

Extract text from an image with a local vision model and write it into a knowledge file:

geneziz ocr screenshot.png --md knowledge/articles/my-article.md

--md writes the OCR section into the file (omit it to print to stdout); --force re-OCRs; --json emits a single JSON line.

geneziz wiki

Build the navigable wiki: ## Related (auto) cross-link sections computed from local embeddings (free, offline) plus a regenerated INDEX.md. Never touches hand-written Related sections.

geneziz enrich-link

Capture the OpenGraph preview (title, description, image, favicon) for a saved-link article - the CLI twin of the MCP enrich_link tool.

Search and ask

geneziz search

Keyword search over the FTS5 index - titles, descriptions, tags, content:

geneziz search "rust async"
geneziz search "database" --category tool
geneziz search "agent frameworks" --semantic     # vector similarity (license tier)
geneziz search "sunset" --media-visual           # find images by what they look like
geneziz search --json

geneziz ask

RAG question over your whole knowledge base: retrieval (FTS5 + vectors) plus an AI answer with cited sources. Multi-turn via --context-file, or continue saved conversations with geneziz conversations.

geneziz ask "what did I save about compilers?"
geneziz ask "summarize my ML reading list" --save      # also saves the answer
geneziz ask --json --stream                            # streaming JSON lines
geneziz ask --provider-override local                  # force a provider: cloud | byok | local | brain
geneziz ask --access-mode plan                         # read | plan | full

Asking through the Geneziz AI proxy costs 1 credit per question; free with your own key or a local model - see AI modes.

geneziz conversations

Ask-chat history: list conversations (--limit, default 50), read one (--id), or append a turn (--append --question "…" --answer "…"). Files live in .state/conversations/ - plain markdown, no database.

geneziz summarize

Generate a 2-3 sentence TL;DR for one knowledge file and persist it into the file's tldr: frontmatter - the viewer then shows it for free, forever:

geneziz summarize knowledge/tools/ripgrep.md
geneziz summarize knowledge/tools/ripgrep.md --json

geneziz insights

AI analysis of the library: what it is about, what it is missing, what to read next. --json for machines, --save <file> to keep it.

geneziz possible

AI-powered 2x2 roadmap generator: clusters bookmark themes into impact/effort quadrants. Actions: run, frames, grid; --query seeds the theme search.

geneziz self search / geneziz self ask

Ask about Geneziz itself. self search retrieves the top sections of the shipped docs pack (free, offline); self ask answers with the AI citing them:

geneziz self ask "how does the license work?" --json

Local AI: free on-device intelligence

All of these run models on your machine - no credits, no network (see AI modes).

geneziz local-brain qualify / geneziz local-brain nightly

Qualify the local brain on your real library (--sample caps the test set; the accuracy gate is 85%) and refresh the qualification in the night batch. The brain is the free fallback rung of the organize ladder.

geneziz personal train / geneziz personal status

Your on-device folder classifier (XGBoost): day-1 bootstrap from the current library, then retrain as it grows. status shows compound metrics - auto-filed percentage, model age.

geneziz media status / geneziz media analyze

Consented local media analysis: status shows counts and progress; analyze backfills dominant-color palettes and image embeddings that power search --media-visual.

geneziz polish pending / geneziz polish run / geneziz polish local

The AI Polish flow: pending derives the review card (counts, previews, price - free), run executes the one approved paid batch (credits; free with BYOK), and local runs the free local ladder (personal model → brain, 0 credits).

Serve: surfaces and servers

geneziz web / geneziz build / geneziz serve

The local web viewer:

geneziz web --port 9876     # Vite dev server (auto-installs deps, auto-indexes)
geneziz build               # static production build to web/dist/
geneziz serve --port 8000   # plain Python HTTP server - no Node needed to serve

serve routes /.state/, /knowledge/, and /bookmarks.md from your data directory and serves everything else from web/dist/ with SPA fallback. --no-window opens a browser tab instead of the native window.

geneziz mcp / geneziz mcp register

Expose the knowledge base to AI clients. Bare geneziz mcp starts the local stdio MCP server (33 tools + 4 resources - full tour in MCP server); mcp register writes the server entry into every detected AI client config (Claude Desktop, Claude Code, Cursor, Windsurf, Codex, VS Code, ZCode, OpenCode):

geneziz mcp register                    # all detected clients
geneziz mcp register --client cursor    # just one (repeatable)
geneziz mcp register --status           # current state as JSON
geneziz mcp register --remove --all     # remove only the Geneziz entries
geneziz mcp register --dry-run          # preview, touch nothing

Registration is config writing only (merged, backed up, atomic) and needs no license; starting the server does.

geneziz extension-serve

The browser-save gateway: the local-only, token-authed HTTP server the browser extension talks to (default port 43117, loopback only). The desktop app starts it for you - run it by hand only for headless setups.

geneziz search-daemon

The long-lived search/ask HTTP sidecar (loopback only, --port 0 = OS-assigned, --host must be loopback). Same payloads as the CLI's --json output, over HTTP.

geneziz dashboard / geneziz dashboard-stats

Launch the Streamlit ops dashboard (--port, default 8501; needs pip install "geneziz[dashboard]"). dashboard-stats pushes knowledge-base stats to the ops dashboard (--json, --dry-run).

geneziz tui / geneziz viz

Two terminal surfaces: tui is the interactive browser/search/Ask UI in your terminal; viz renders knowledge-base charts and analytics.

Setup, health, and your data

geneziz setup

Interactive wizard that validates credentials live as you enter them: X auth cookies (with a test fetch), Anthropic or OpenAI-compatible keys (optional), GitHub token (optional), default source.

geneziz init

Write a default geneziz.config.json (--config to choose the path).

geneziz status

Current configuration and knowledge-base stats - bookmark, tool, article, and media counts. --json for scripts.

geneziz doctor

Whole-install health check: config, knowledge base, search index, MCP client registrations, license. Fixes what it can:

geneziz doctor               # the full report
geneziz doctor --json        # one JSON object
geneziz doctor --fix-mcp     # re-run MCP registration before reporting
geneziz doctor --dupes       # near-duplicate scan over the library

geneziz import-pocket / geneziz import-bookmarks

Refuge-friendly importers: import-pocket reads a Pocket export (JSON array, shutdown CSV, or ril_export.html - auto-detected); import-bookmarks reads a browser bookmarks.html export (Chrome/Firefox/Edge/Safari). Both file into the knowledge base with dedupe.

geneziz export

Zip backup of the whole base - bookmarks.md, knowledge/, .state/:

geneziz export --output ~/backups/knowledge.zip
geneziz export --html              # standalone HTML dashboard instead

geneziz migrate

Migrate from a Smaug project directory (--from /path/to/smaug): copies bookmarks.md and knowledge/ into Geneziz. Follow with geneziz index.

geneziz reset

Delete config and state (--force skips the confirmation). Your bookmarks.md and knowledge/ are preserved - reset the machinery, never the library.

geneziz skill

Install, show, or uninstall the Geneziz agent skill for Claude Code and Codex, so coding agents in that directory can drive the CLI idiomatically:

geneziz skill install
geneziz skill show
geneziz skill uninstall

The fine print

• Same license, both faces. The CLI is part of the product you bought; there is no separate CLI license and no subscription.
• Honest tiers. Keyword search, processing, and the FTS index work on every tier. Semantic search, vector indexes, and the MCP server are license-tier capabilities; AI calls cost credits through the Geneziz proxy or are free with your own key / local models.
• Local-first. Commands read and write your data directory. The only network calls are the sources you fetch from and the AI provider you configure.
• One legacy command, geneziz enrich, still ships but is hidden from --help - organize and summarize supersede it.

Questions this page did not answer? geneziz <command> --help is generated from the same code this page documents - or ask your own knowledge base: geneziz self ask "how do I …".