The notes_client.py script provides command-line access to the notes system. It communicates with a running gdata server via HTTP.
The CLI is symlinked as notes on the PATH (/home/john/bin/notes). Always invoke it as simply notes — do NOT cd to the gdata-server directory or run python3 notes_client.py directly.
Read a document by key. Empty key reads the root page.
Write content to a key. Content is passed as command-line arguments.
Load a JSON file into a document key. This is the preferred way to create notes from tools and scripts.
The -d flag deletes the file after successful load.
List all document keys currently stored in the notes system. This is essential for discovering what notes exist and identifying any orphaned documents (notes with no links from other pages).
Use this command to:
- Check what notes exist before reading or linking- Audit the system for orphaned documents- Verify parent-child relationships are properly linked
Delete a document by key.
WARNING: See Avoiding Orphaned Notes and Information Loss before deleting or removing links.
The notes command is on the PATH. Run it from any directory — there is no need to change directory or reference the gdata-server source. Examples:
When programmatically creating notes:1. Use your create_file/Write tool to generate a JSON file (no shell redirects like cat >)2. Validate JSON if needed3. Load with: notes load -d <key> <file>The -d flag cleans up the file after successful load. This avoids terminal prompts, uses native tools, and ensures proper validation.
Do not use cat > file.json << 'EOF' patterns. They trigger user prompts and are less reliable.
When creating a new child note, always add a link from the parent page. See Avoiding Orphaned Notes for details and examples of why this matters.