CLI Commands

Quick reference for all zk commands.

Note Creation

Create an untethered note (no project required)

zk create "Quick idea about X" --category untethered
zk create "My note title"  # Default is untethered

Create an untethered note with project

zk create "Project idea" --category untethered --project my-project
zk create "Project idea" --category untethered -p my-project

Create a tethered note (project required)

zk create "Refined concept" --category tethered --project my-project

Note Management

Set project on a note

zk set-project path/to/note.md my-project

Tether an untethered note (promote to tethered)

# With explicit project
zk tether path/to/note.md --project my-project
zk tether path/to/note.md -p my-project

# Auto-detect from git (if in a repo)
zk tether path/to/note.md

Untether a tethered note (demote to untethered)

# Reverts a tethered note back to untethered
zk untether path/to/note.md

Validation

Validate a zettel’s frontmatter

zk validate path/to/note.md

Validates the zettel’s YAML frontmatter against the CUE schema. Reports any missing or invalid fields.

Indexing

Index a single file

zk index path/to/note.md

Index all notes in a directory

zk index ~/zk_vault/
zk index .

Searching

Full-text search

zk search "authentication patterns"
zk search "golang error handling"

Filter by project

zk search --project my-project
zk search -p my-project
zk search "query" --project my-project  # Combined

Filter by category

zk search --category untethered
zk search --category tethered
zk search -c tethered

Filter by tags

zk search --tag golang
zk search --tag golang --tag api  # AND (must have both)
zk search -T golang -T testing

Filter by type

zk search --type todo
zk search --type daily-note
zk search -t issue

Filter by status and priority

zk search --status open
zk search --priority high
zk search --type todo --status open --priority high

Filter by due date

zk search --due-before 2026-03-01
zk search --due-after 2026-02-01
zk search --due-after 2026-02-01 --due-before 2026-02-28  # Date range

Limit results

zk search --limit 10
zk search -l 50

JSON output (for scripting/tooling)

zk search --json
zk search "query" --json | jq '.[] | .title'

Combined filters

zk search "authentication" --project my-project --category tethered --tag security
zk search --type todo --status open --project my-project --priority high

Graph Visualization

Generate a graph from a directory

zk graph ~/zk_vault/
zk graph .

Limit the number of nodes

zk graph . --limit 20
zk graph . -l 5

Start from a specific note

zk graph . --start 20260219143000-a1b2c3d4

Control tree depth

zk graph . --depth 3

Sync graph database before querying

zk graph --sync

The graph command outputs Mermaid flowchart syntax to stdout. When a graph database (.zk_graph.db) exists, it uses indexed data for faster queries. Use --sync to force a fresh sync before querying.

Graph Database

The graph database (.zk_graph.db) enables O(1) indexed backlink lookups and fast traversals. It is optional — all commands fall back to filesystem scanning when the database doesn’t exist.

Sync the graph database

zk graph-sync                    # Sync from configured root
zk graph-sync ~/zk_vault/        # Sync from explicit path
zk graph-sync --validate         # Sync + validate edge integrity

Output shows added, updated, deleted counts. With --validate, reports dangling edges (links to non-existent notes) and structurally invalid edges.

Query backlinks (indexed)

zk graph-query backlinks <id>
zk graph-query backlinks <id> --json

Query connected cluster (N-depth BFS)

zk graph-query cluster <id>
zk graph-query cluster <id> --depth 2 --limit 20
zk graph-query cluster <id> --json

Query by tag

zk graph-query tag golang
zk graph-query tag golang --json

Find dangling edges

zk graph-query dangling
zk graph-query dangling --json

Note Templates

List and use note templates for structured content.

List available templates

zk templates

Create a note from a template

zk create "Sprint Planning Q1" --template meeting
zk create "Clean Code Review" --template book-review
zk create "OAuth Implementation" --template feature
zk create "Add Login Flow" --template user-story
zk create "CLI Tool Idea" --template project-idea
zk create "Go Error Handling" --template snippet

Available templates:

meeting - Meeting notes with attendees and action items
book-review - Book review with rating and key takeaways
snippet - Code snippet with context and explanation
project-idea - Project idea with goals and next steps
user-story - User story in standard format with acceptance criteria
feature - Feature specification with requirements and design notes
daily - Daily note for thoughts, tasks, and reflections
todo - Actionable task with status tracking
issue - Issue tracking like GitHub (bug, enhancement, question)

Backlinks

Find all notes that link to a specific zettel.

Find backlinks by ID

zk backlinks 202602131045

Find backlinks by file path

zk backlinks ./notes/202602131045.md

JSON output

zk backlinks 202602131045 --json
zk backlinks 202602131045 --json | jq '.[].title'

Daily Notes

Create and manage daily notes for capturing thoughts, tasks, and reflections.

Create or open today’s daily note

zk daily

Open yesterday’s daily note

zk daily --yesterday

Open a specific date’s daily note

zk daily --date 2026-02-10

List recent daily notes

zk daily --list              # Last 14 days
zk daily --list --week       # This week
zk daily --list --month      # This month
zk daily --list --json       # JSON output

Daily notes are stored in untethered/daily/YYYY/MM/YYYY-MM-DD.md.

See Daily Notes Workflow for a comprehensive guide to daily note workflows.

Todo Management

Create a todo

zk todo "Fix login bug"
zk todo "Update docs" --project my-project

Create with due date and priority

zk todo "Critical fix" --due 2026-02-20 --priority high
zk todo "Nice to have" --priority low

List todos

zk todos                        # List open todos
zk todos --project my-project   # Filter by project
zk todos --overdue              # Overdue todos
zk todos --today                # Due today
zk todos --this-week            # Due this week
zk todos --closed               # Show closed todos
zk todos --json                 # JSON output

Manage todo status

zk set-status 202602131045 closed       # Mark as closed
zk set-status 202602131045 in_progress  # Set to in progress
zk set-status 202602131045 open         # Reopen a closed todo

Generate todo list markdown

zk todo-list                    # Generate todo list
zk todo-list --project my-project
zk todo-list --output my-todos.md

See Todo Workflow for a comprehensive guide to todo workflows.

Git Workflow

Manage your zettelkasten git repository with dated branches.

Start your day (hello)

zk hello

This command:

Checks out the main branch
Pulls latest changes
Creates a new branch named with today’s date (YYYYMMDD format, e.g., 20260213)
Warns if the branch already exists (does nothing)
Warns if there are uncommitted changes (does nothing)

End your day (goodbye)

zk goodbye

This command:

Commits all changes with a timestamped message
Checks out main
Merges the dated branch into main
Deletes the dated branch after merge
Warns if not on a date branch (does nothing)
Warns if there are no changes to commit (still merges)

Typical daily workflow

# Morning
zk hello                    # Create today's branch

# Throughout the day
zk create "Meeting notes" --template meeting
zk todo "Follow up on action item"
zk daily                    # Add to daily note

# End of day
zk goodbye                  # Commit and merge to main

Help

General help

zk --help
zk -h

Command-specific help

zk create --help
zk index --help

Flags Reference

`zk create`

Flag	Short	Default	Description
`--category`	`-c`	`untethered`	Note category (`untethered` or `tethered`)
`--project`	`-p`	(auto-detect)	Project context
`--template`	-	-	Use a note template (e.g., `meeting`, `user-story`)
`--help`	`-h`	-	Show help

`zk templates`

Flag	Short	Default	Description
`--help`	`-h`	-	Show help

`zk tether`

Flag	Short	Default	Description
`--project`	`-p`	(auto-detect)	Project context for tethered note
`--help`	`-h`	-	Show help

`zk untether`

Flag	Short	Default	Description
`--help`	`-h`	-	Show help

`zk set-project`

Flag	Short	Default	Description
`--help`	`-h`	-	Show help

`zk add-tags`

Usage: zk add-tags <file> <tag1> [tag2...]

Flag	Short	Default	Description
`--help`	`-h`	-	Show help

`zk validate`

Usage: zk validate <file>

Flag	Short	Default	Description
`--help`	`-h`	-	Show help

`zk index`

Flag	Short	Default	Description
`--help`	`-h`	-	Show help

`zk search`

Flag	Short	Default	Description
`--project`	`-p`	-	Filter by project
`--category`	`-c`	-	Filter by category (`untethered`/`tethered`)
`--tag`	`-T`	-	Filter by tag (repeatable, AND logic)
`--type`	`-t`	-	Filter by type (`note`/`todo`/`daily-note`/`issue`)
`--status`	-	-	Filter by status (`open`/`in_progress`/`closed`)
`--priority`	-	-	Filter by priority (`high`/`medium`/`low`)
`--due-before`	-	-	Filter todos due before date (YYYY-MM-DD)
`--due-after`	-	-	Filter todos due after date (YYYY-MM-DD)
`--limit`	`-l`	`20`	Maximum number of results
`--json`	-	`false`	Output as JSON
`--help`	`-h`	-	Show help

`zk graph`

Flag	Short	Default	Description
`--limit`	`-l`	`10`	Maximum number of nodes to display
`--start`		-	Start tree from a specific note ID
`--depth`		`0` (unlimited)	Maximum tree depth
`--sync`		`false`	Sync graph database before querying
`--help`	`-h`	-	Show help

`zk graph-sync`

Flag	Short	Default	Description
`--validate`		`false`	Run CUE edge validation and report integrity issues
`--help`	`-h`	-	Show help

`zk graph-query`

Subcommands: backlinks <id>, cluster <id>, tag <tag>, dangling

Flag	Short	Default	Description
`--json`		`false`	Output as JSON
`--depth`		`0` (unlimited)	Maximum BFS depth (cluster only)
`--limit`	`-l`	`10`	Maximum number of nodes (cluster only)
`--help`	`-h`	-	Show help

`zk backlinks`

Flag	Short	Default	Description
`--json`	-	`false`	Output as JSON
`--help`	`-h`	-	Show help

`zk daily`

Flag	Short	Default	Description
`--date`	-	-	Target date (YYYY-MM-DD format)
`--yesterday`	-	`false`	Use yesterday’s date
`--list`	-	`false`	List recent daily notes
`--week`	-	`false`	Show this week’s notes (with —list)
`--month`	-	`false`	Show this month’s notes (with —list)
`--json`	-	`false`	Output as JSON (with —list)
`--help`	`-h`	-	Show help

`zk todo`

Flag	Short	Default	Description
`--project`	`-p`	(auto-detect)	Project context
`--due`	-	-	Due date (YYYY-MM-DD format)
`--priority`	-	-	Priority (`high`, `medium`, `low`)
`--help`	`-h`	-	Show help

`zk todos`

Flag	Short	Default	Description
`--project`	`-p`	-	Filter by project
`--overdue`	-	`false`	Show overdue todos
`--today`	-	`false`	Show todos due today
`--this-week`	-	`false`	Show todos due this week
`--closed`	-	`false`	Show closed todos
`--json`	-	`false`	Output as JSON
`--help`	`-h`	-	Show help

`zk set-status`

Usage: zk set-status [id_or_file] [status]

Status must be one of: open, in_progress, closed.

Flag	Short	Default	Description
`--help`	`-h`	-	Show help

`zk todo-list`

Flag	Short	Default	Description
`--project`	`-p`	-	Filter by project
`--output`	`-o`	`todos-TIMESTAMP.md`	Output filename
`--help`	`-h`	-	Show help

`zk hello`

Flag	Short	Default	Description
`--help`	`-h`	-	Show help

`zk goodbye`

Flag	Short	Default	Description
`--help`	`-h`	-	Show help

Note ID Format

Notes use a 12-digit timestamp ID: YYYYMMDDHHMM

Examples:

202602131045 = February 13, 2026 at 10:45
202601010900 = January 1, 2026 at 09:00

Frontmatter Template

---
id: "YYYYMMDDHHMM"
title: "Note Title"
project: "project-name"
category: "untethered"  # or "tethered"
tags:
  - "tag1"
  - "tag2"
created: "YYYY-MM-DDTHH:MM:SSZ"
parent: "YYYYMMDDHHMM"  # optional
---

Directory Structure

Default layout (configurable):

~/zk_vault/
├── untethered/         # Quick captures, ideas
│   └── 202602131045.md
├── tethered/           # Refined, linked notes
│   └── 202602131100.md
└── tmp/                # Scratch space

Environment

zk automatically detects:

Git project: Uses repo name as project field
Working directory: For relative paths

Common Workflows

Capture an idea quickly (no project context)

zk create "Random thought while commuting"

Capture while working on a project

cd ~/projects/my-project
zk create "Interesting pattern in auth flow"
# Project auto-detected from git

Add project context later

zk set-project ~/zk_vault/untethered/202602131045.md my-project

Tether an untethered note

# Review and refine the untethered note, then tether
zk tether ~/zk_vault/untethered/202602131045.md --project my-project

# Or if in a git repo, project is auto-detected
cd ~/projects/my-project
zk tether ~/zk_vault/untethered/202602131045.md

Untether a tethered note

# Revert a tethered note back to untethered
zk untether ~/zk_vault/tethered/202602131100.md

Build a note chain

# Create parent
zk create "Main concept" --category tethered -p my-project
# Note the ID (e.g., 202602131045)

# Create child (manually add parent field to frontmatter)
zk create "Sub-concept" --category tethered -p my-project
# Edit to add: parent: "202602131045"

Makefile Targets

make build            # Build binary
make test             # Run Go tests + CUE validation
make lint             # Run go vet + staticcheck
make fmt              # Format Go + CUE files
make install          # Install to $GOPATH/bin
make clean            # Remove binary and index
make tidy             # Run go mod tidy
make ui-check         # Lint Lua plugin
make integration-test # Test NeoVim integration