peterhajas/dotfiles/tw

TiddlyWiki CLI (tw)

Quick Reference

tw is a Python-based CLI for managing single-file TiddlyWiki wikis.

Location: ~/dotfiles/tiddlywiki/bin/tw

Basic syntax:

tw [<wiki_path>] <command> [args]

Common Commands

Reading/Listing

• ls - List all tiddlers
• cat <tiddler> - Display tiddler contents (cat format: title, tags, other fields, blank line, text)
• json <tiddler> [...] - Output tiddler(s) as JSON (use --all for all tiddlers)
• get <tiddler> <field> - Get a specific field value
• filter <expression> - Evaluate TiddlyWiki filter expression

Writing/Editing

• init <dest_path> - Create a new empty wiki
• touch <tiddler> [text] - Create or update a tiddler
• set <tiddler> <field> <val> - Set a field value
• edit <tiddler> - Edit tiddler in $EDITOR (opens interactive editor)
• append <tiddler> [text] - Append text to tiddler
• insert <json> - Insert/replace tiddler(s) from JSON
• replace <content> - Insert/replace from cat format (reads from stdin)
• rm <tiddler> - Remove a tiddler

Serving

• serve [--host HOST] [--port PORT] [--readonly] - Serve wiki with live reload
• webdav [--host HOST] [--port PORT] [--readonly] - Serve tiddlers via WebDAV

Utilities

• detect - Detect wiki format (modern or legacy)
• filetype-map - Output MIME type to filetype mapping as JSON
• mimetype <filename> - Get MIME type for a file extension
• install_plugin - Install live reload plugin

Important Notes

1. Wiki path: Always specify the wiki path as the first argument
2. Cat format: Output format is title: X\ntags: Y\nfield: Z\n\ntext content
3. Interactive commands: edit opens $EDITOR - don't use in automated scripts, use replace instead
4. Filter expressions: Supports TiddlyWiki filter syntax (see tw_filter_progress.md for coverage)
5. Live reload: Use install_plugin once, then serve to get auto-refresh in browser

Examples

# List all tiddlers in a wiki
tw ~/wiki.html ls
 
# Create a new tiddler
tw ~/wiki.html touch "MyTiddler" "This is the content"
 
# Get a field value
tw ~/wiki.html get "MyTiddler" tags
 
# Set a field
tw ~/wiki.html set "MyTiddler" tags "foo bar"
 
# Pipe content to replace (non-interactive)
echo -e "title: Test\ntags: demo\n\nContent here" | tw ~/wiki.html replace
 
# Export all tiddlers as JSON
tw ~/wiki.html json --all > backup.json
 
# Filter tiddlers (find all tagged "journal")
tw ~/wiki.html filter "[tag[journal]]"
 
# Serve wiki with live reload on port 8080
tw ~/wiki.html serve --port 8080

Integration with Other Tools

• Pipe JSON to/from jq for processing
• Use with nvim via $EDITOR for editing
• Combine with shell scripts for batch operations
• WebDAV server allows mounting as filesystem