gh-rawe-claude-agent-orchestrator-plugins-document-sync/skills/document-sync

Document Sync CLI Commands

Command-line tools for interacting with the Document Sync Server. These UV-based scripts enable Claude Code sessions to store, retrieve, query, inspect, read, and delete documents with metadata and tags.

Prerequisites

• Python 3.11+ - Required for script dependencies
• UV package manager - For running scripts with automatic dependency management
• Document Server - Must be running (see ../../document-server/README.md)

Available Commands

All commands output JSON for easy parsing and integration with Claude Code (except doc-read, which outputs raw text).

doc-push - Upload Documents

Upload a document to the server with optional tags and description.

uv run /path/to/doc-push <file> [OPTIONS]

Arguments:

• file - Path to the file to upload (required)

Options:

• --name TEXT - Custom name for the document (defaults to filename)
• --tags TEXT - Comma-separated tags (e.g., "python,api,docs")
• --description TEXT - Document description

Example:

uv run doc-push architecture.md --tags "design,architecture" --description "System architecture document"

Output:

{
  "id": "doc_abc123...",
  "filename": "architecture.md",
  "content_type": "text/markdown",
  "size_bytes": 2048,
  "created_at": "2025-11-23T00:00:00",
  "updated_at": "2025-11-23T00:00:00",
  "tags": ["design", "architecture"],
  "metadata": {"description": "System architecture document"},
  "url": "http://localhost:8766/documents/doc_abc123..."
}

doc-query - Search Documents

Query documents by name pattern and/or tags.

uv run /path/to/doc-query [OPTIONS]

Options:

• --name TEXT - Filter by filename pattern (partial match)
• --tags TEXT - Comma-separated tags with AND logic (document must have ALL tags)
• --limit INTEGER - Maximum number of results

Examples:

# List all documents
uv run doc-query

# Find documents with specific tags (AND logic)
uv run doc-query --tags "python,tutorial"

# Filter by name pattern
uv run doc-query --name "architecture"

# Combine filters
uv run doc-query --name "guide" --tags "python" --limit 5

Tag AND Logic: When querying with multiple tags (e.g., --tags "python,api"), only documents that have both tags will be returned.

Output:

[
  {
    "id": "doc_abc123...",
    "filename": "python-guide.md",
    "content_type": "text/markdown",
    "size_bytes": 1024,
    "created_at": "2025-11-23T00:00:00",
    "updated_at": "2025-11-23T00:00:00",
    "tags": ["python", "tutorial"],
    "metadata": {},
    "url": "http://localhost:8766/documents/doc_abc123..."
  }
]

doc-info - Get Document Metadata

Retrieve metadata for a specific document without downloading the file.

uv run /path/to/doc-info <document_id>

Arguments:

• document_id - The document's unique identifier (required)

Example:

uv run doc-info doc_abc123...

Output:

{
  "id": "doc_abc123...",
  "filename": "architecture.md",
  "content_type": "text/markdown",
  "size_bytes": 2048,
  "created_at": "2025-11-23T00:00:00",
  "updated_at": "2025-11-23T00:00:00",
  "tags": ["design", "architecture"],
  "metadata": {"description": "System architecture document"},
  "url": "http://localhost:8766/documents/doc_abc123..."
}

Use Case: Check document metadata (file size, MIME type, tags) before downloading. The url field provides a direct link to retrieve the document, mostly interesting for the user or system having no access to the skill itself.

doc-read - Read Text Documents

Read text document content directly to stdout without downloading to file.

uv run /path/to/doc-read <document_id>

Arguments:

• document_id - The document's unique identifier (required)

Supported File Types:

• Text files (text/*)
• JSON files (application/json)
• XML files (application/xml)

Examples:

# Output content to terminal
uv run doc-read doc_abc123...

# Pipe to grep
uv run doc-read doc_abc123... | grep "search term"

# Pipe to jq (for JSON documents)
uv run doc-read doc_abc123... | jq '.field'

# Save to file
uv run doc-read doc_abc123... > output.txt

Output: Raw text content (no JSON wrapper)

Error (for non-text files):

{"error": "Cannot read non-text file (MIME type: image/png). Use doc-pull to download binary files."}

Use Case: Quick inspection of text files, piping content to other tools, processing documents in scripts without creating temporary files.

doc-pull - Download Documents

Download a document by its ID.

uv run /path/to/doc-pull <document_id> [OPTIONS]

Arguments:

• document_id - The document's unique identifier (required)

Options:

• --output PATH or -o PATH - Output file path (defaults to original filename)

Examples:

# Download with original filename
uv run doc-pull doc_abc123...

# Download to specific path
uv run doc-pull doc_abc123... --output ~/downloads/my-document.md

Output:

{
  "success": true,
  "document_id": "doc_abc123...",
  "filename": "/path/to/output.md",
  "size_bytes": 2048
}

doc-delete - Remove Documents

Delete a document from the server.

uv run /path/to/doc-delete <document_id>

Arguments:

• document_id - The document's unique identifier (required)

Example:

uv run doc-delete doc_abc123...

Output:

{
  "success": true,
  "message": "Document doc_abc123... deleted successfully",
  "document_id": "doc_abc123..."
}

Configuration

Commands connect to the document server using environment variables:

DOC_SYNC_HOST

• Description: Server hostname or IP address
• Default: localhost
• Example:

  DOC_SYNC_HOST=192.168.1.100 uv run doc-push file.txt
  

DOC_SYNC_PORT

• Description: Server port number
• Default: 8766
• Example:

  DOC_SYNC_PORT=9000 uv run doc-query
  

DOC_SYNC_SCHEME

• Description: HTTP scheme (http or https)
• Default: http
• Example:

  DOC_SYNC_SCHEME=https uv run doc-pull doc_abc123...
  

Combined Example:

DOC_SYNC_HOST=example.com DOC_SYNC_PORT=443 DOC_SYNC_SCHEME=https \
  uv run doc-push document.pdf --tags "report"

Common Workflows

Store and Retrieve a Document

# 1. Upload a document
uv run doc-push specs.md --tags "api,specification"

# Output includes the document ID: "doc_abc123..."

# 2. Later, query for it
uv run doc-query --tags "api,specification"

# 3. Check metadata before downloading
uv run doc-info doc_abc123...

# 4. Read content (for text files)
uv run doc-read doc_abc123... | less

# 5. Download it
uv run doc-pull doc_abc123... --output specs-copy.md

Share Documents Across Sessions

# Session 1: Store architecture document
uv run doc-push architecture.md --tags "design,mvp" \
  --description "MVP architecture decisions"

# Session 2: Query and retrieve
uv run doc-query --tags "design,mvp"
uv run doc-info doc_abc123...  # Check metadata
uv run doc-read doc_abc123... | head -20  # Preview first 20 lines
uv run doc-pull doc_abc123... --output architecture.md

Manage Document Repository

# List all documents
uv run doc-query

# Find specific category
uv run doc-query --tags "deprecated"

# Remove old documents
uv run doc-delete doc_old123...

Error Handling

All commands output errors to stderr in JSON format and exit with code 1 on failure.

Common Errors:

File not found:

{"error": "File not found: /path/to/file.txt"}

Document not found:

{"error": "Document not found: doc_invalid123"}

Non-text file (doc-read only):

{"error": "Cannot read non-text file (MIME type: image/png). Use doc-pull to download binary files."}

Network error:

{"error": "Network error: Connection refused"}

Server not running:

{"error": "Network error: [Errno 61] Connection refused"}

Technical Details

Script Architecture

• UV Scripts: Use PEP 723 inline dependency metadata
• Shebang: #!/usr/bin/env -S uv run --script
• Dependencies: Automatically installed by UV (httpx, typer)
• Shared Library: lib/config.py and lib/client.py provide reusable components

Why UV?

• Zero installation: Scripts run with dependencies automatically installed
• Reproducible: PEP 723 metadata ensures consistent dependency versions
• Fast: UV's Rust-based resolver is extremely fast
• Portable: Scripts work across different environments

Troubleshooting

"Connection refused" error

The document server isn't running. Start it first:

cd ../../document-server
uv run python -m src.main

"No such file or directory" when running commands

Use full paths or navigate to the commands directory:

# Use full path
uv run /full/path/to/doc-push file.txt

# Or navigate to commands directory
cd /path/to/commands
uv run doc-push file.txt

Commands run slowly the first time

UV is installing dependencies. Subsequent runs will be fast as dependencies are cached.

Development

See ../../docs/implementation/03-IMPLEMENTATION-CHECKLIST.md for implementation details and design decisions.