ztlctl 1.15.0

ZettelControl — CLI utility for managing a Zettelkasten note-taking system

ZettelControl (ztlctl)

ZettelControl (ztlctl) is a local knowledge operating system for human users and AI agents. It separates agent-assisted capture and synthesis from human-led enrichment, so research capture, durable notes, and garden work can coexist without sharing the same workflow.

ztlctl manages durable knowledge artifacts as structured markdown files backed by a SQLite index and a weighted knowledge graph. Operational state such as sessions, logs, generated self/ documents, and event dispatch is internal and rebuildable rather than part of the file-first durability contract.

Installation

pip install ztlctl

Or with uv:

uv tool install ztlctl

Or with Homebrew:

brew tap ThatDev/ztlctl
brew install ThatDev/ztlctl/ztlctl

Optional extras: pip install ztlctl[mcp] (MCP server), pip install ztlctl[semantic] (vector search), pip install ztlctl[community] (advanced graph algorithms).

Homebrew installs the base CLI. For optional extras such as MCP or semantic search, use pip or uv.

See the Installation Guide for details.

Quick Start

# 1. Initialize a new vault
ztlctl init my-vault --topics "python,architecture,devops"

# 2. Enter the vault directory
cd my-vault

# 3. Start a research session
ztlctl agent session start "Learning Python async patterns"

# 4. Create notes as you learn
ztlctl create note "Asyncio Event Loop" --tags "lang/python,concept/concurrency"
ztlctl create note "Async vs Threading" --tags "lang/python,concept/concurrency"

# 5. Create references to external sources
ztlctl create reference "Python asyncio docs" --url "https://docs.python.org/3/library/asyncio.html"

# 6. Track tasks that emerge
ztlctl create task "Refactor API to use async" --priority high --impact high

# 7. Let the graph grow — reweave discovers connections
ztlctl reweave --auto-link-related

# 8. Search your knowledge
ztlctl query search "async patterns" --rank-by relevance

# 9. Build a topic packet and draft from it
ztlctl query packet --topic architecture --mode review
ztlctl query draft --topic architecture --target note

# 10. Close the session when done
ztlctl agent session close --summary "Mapped async patterns, identified refactoring task"

Features

• Two explicit working layers: capture/synthesis for agent-assisted research and enrichment for garden work (Knowledge Paradigms)
• File-first durable artifacts for notes, references, and tasks, with rebuildable indexes and operational state (Core Concepts)
• Knowledge graph with 4-signal reweave scoring (BM25, tag overlap, graph proximity, topic match) for automated link discovery (Tutorial)
• Session-based agentic workflows with token-budgeted 5-layer context assembly (Agentic Workflows)
• Digital garden maturity tracking — seed, budding, and evergreen stages (Knowledge Paradigms)
• Text-first ingestion for raw text, markdown files, and provider-backed URL capture (Command Reference)
• Durable source bundles for agent-fetched web and multimodal captures, persisted beside ingested references for later packet/export reuse (Agentic Workflows)
• Full-text + semantic search with BM25/vector hybrid ranking, explainable review/garden modes, and topic packets (Command Reference)
• Conversational enrichment workflows with packet-to-draft note/task/decision generation (Agentic Workflows)
• Dashboard and dossier export for review queues, garden backlog, and topic workbenches (Tutorial)
• MCP server with discovery-first tooling, portable prompts, capture-spec resources, and exported client assets for AI integration (MCP Server)
• Generated Claude and Codex workflow assets via ztlctl workflow export for portable agent setup
• Export to markdown, indexes, graph formats, and dashboard artifacts (Tutorial)
• Plugin system via pluggy event bus with built-in git integration (Development)
• Structured JSON output on every command for scripting and agent consumption (--json flag)
• Vault integrity checking, auto-fix, full rebuild, and rollback (Troubleshooting)

CLI Command Reference

All commands support --json for structured output and --help for full option details. Use --log-json on the root command to emit structured JSON logs to stderr (e.g. for agent pipelines).

Command	Description
ztlctl init	Initialize a new vault
ztlctl create	Create notes, references, and tasks
ztlctl update	Update content metadata or body
ztlctl query	Search, list, and query vault content
ztlctl graph	Traverse and analyze the knowledge graph
ztlctl reweave	Reweave links to densify the knowledge graph
ztlctl agent	Manage sessions, context, and agent workflows
ztlctl garden	Cultivate knowledge with the garden persona
ztlctl ingest	Ingest text and source material into the vault
ztlctl check	Check vault integrity; optionally fix, rebuild, or rollback
ztlctl upgrade	Run pending database schema migrations
ztlctl export	Export vault content (markdown, indexes, graph formats)
ztlctl vector	Manage the semantic search vector index
ztlctl workflow	Manage workflow templates and configuration
ztlctl serve	Start the MCP server (ztlctl[mcp] extra required)
ztlctl archive	Archive a content item (sets archived flag)
ztlctl extract	Extract a decision note from a session log
ztlctl supersede	Mark a decision as superseded by a newer decision

Documentation

Guide	Description
Installation	Install via pip, uv, or Homebrew
Quick Start	Your first vault in 9 commands
Tutorial	Step-by-step vault building guide
Core Concepts	Content types, lifecycle, vault structure, graph
Command Reference	All CLI commands, options, and filters
Configuration	ztlctl.toml settings and environment variables
Agentic Workflows	Sessions, context assembly, batch, scripting
Knowledge Paradigms	Capture/synthesis and enrichment, mapped to note-taking paradigms
MCP Server	Model Context Protocol integration
Development	Contributing, architecture, local setup
Troubleshooting	Common issues and solutions

Full documentation is also available at thatdevstudio.github.io/ztlctl.

Architecture

ztlctl follows a strict 6-layer package structure where dependencies flow downward:

src/ztlctl/
├── domain/          # Types, enums, lifecycle rules, ID patterns
├── infrastructure/  # SQLite/SQLAlchemy, NetworkX graph, filesystem
├── config/          # Pydantic config models, TOML discovery
├── services/        # Business logic (create, query, graph, reweave, ...)
├── output/          # Rich/JSON formatters
├── commands/        # Click CLI commands
├── plugins/         # Pluggy hook specs and built-in plugins
├── mcp/             # MCP server adapter
└── templates/       # Jinja2 templates for content creation

See Development for details and DESIGN.md for the complete internal design specification.

Contributing

This project uses conventional commits. See CONTRIBUTING.md for the full guide.

1. Branch from develop: git checkout -b feature/<name> develop
2. Make changes and commit with conventional messages
3. Open a PR targeting develop
4. Releases are automated when version-bumping commits (feat:, fix:) merge to develop

Community

• Code of Conduct
• Security Policy
• Support

License

MIT