gh-rawe-claude-agent-orchestrator-plugins-document-sync/skills/document-sync/references/COMMANDS.md

Command Reference

doc-push

uv run commands/doc-push <file> [--name TEXT] [--tags TEXT] [--description TEXT]

Arguments: <file> - File path to upload

Options:

• --name TEXT - Custom name (default: filename)
• --tags TEXT - Comma-separated tags
• --description TEXT - Description

Examples:

uv run commands/doc-push specs.md --tags "api,v2"
uv run commands/doc-push arch.md --tags "design,mvp" --description "MVP architecture"

Output:

{
  "id": "doc_abc123def456...",
  "filename": "specs.md",
  "content_type": "text/markdown",
  "size_bytes": 2048,
  "created_at": "2025-11-23T00:00:00",
  "updated_at": "2025-11-23T00:00:00",
  "tags": ["api", "v2"],
  "metadata": {"description": "Specification document for API v2"},
  "url": "http://localhost:8766/documents/doc_abc123def456..."
}

Note: Save the id field for pull/delete operations.

---

doc-query

uv run commands/doc-query [--name TEXT] [--tags TEXT] [--limit INTEGER]

Options:

• --name TEXT - Filter by filename pattern
• --tags TEXT - Filter by tags (AND logic - ALL tags must match)
• --limit INTEGER - Max results

Examples:

uv run commands/doc-query                    # List all
uv run commands/doc-query --tags "api,v2"    # Both tags required (AND)
uv run commands/doc-query --name "spec"      # Name contains "spec"

Output:

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

Important: Multiple tags = ALL must match (AND logic, not OR)

---

doc-info

uv run commands/doc-info <document-id>

Arguments: <document-id> - Document ID to retrieve metadata for

Examples:

uv run commands/doc-info doc_abc123...

Output:

{
  "id": "doc_abc123...",
  "filename": "api-spec.md",
  "content_type": "text/markdown",
  "size_bytes": 1024,
  "created_at": "2025-11-23T00:00:00",
  "updated_at": "2025-11-23T00:00:00",
  "tags": ["api", "v2"],
  "metadata": {"description": "API specification"},
  "url": "http://localhost:8766/documents/doc_abc123..."
}

Use Case: View document metadata without downloading the file. The url field provides a direct link to retrieve the document. Useful to provide this url to a user if you don't want to download the file yourself.

Error Output (stderr):

{"error": "Document not found: doc_abc123..."}

---

doc-read

uv run commands/doc-read <document-id>

Arguments: <document-id> - Document ID to read content from

Examples:

# Direct output
uv run commands/doc-read doc_abc123...

# Pipe to grep
uv run commands/doc-read doc_abc123... | grep "pattern"

# Pipe to wc
uv run commands/doc-read doc_abc123... | wc -l

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

Output: Raw text content to stdout (no JSON wrapper)

Supported MIME Types:

• text/* (text/plain, text/markdown, text/html, etc.)
• application/json
• application/xml

Error Output (stderr):

{"error": "Cannot read non-text file (MIME type: image/png). Use doc-pull to download binary files."}
{"error": "File is not valid UTF-8 text. Use doc-pull to download."}
{"error": "Document not found: doc_abc123..."}

Use Case: Read text document content directly without downloading to file system. Ideal for:

• Piping content to other tools (grep, awk, jq, etc.)
• Quick inspection of text files
• Processing document content in scripts

Limitations:

• Text files only (binary files will error)
• UTF-8 encoding only
• For binary files or non-UTF-8 content, use doc-pull instead

---

doc-pull

uv run commands/doc-pull <document-id> [--output PATH | -o PATH]

Arguments: <document-id> - Document ID from query results

Options: --output PATH or -o PATH - Output path (default: original filename)

Examples:

uv run commands/doc-pull doc_abc123...
uv run commands/doc-pull doc_abc123... -o custom-name.md

Output:

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

---

doc-delete

uv run commands/doc-delete <document-id>

Arguments: <document-id> - Document ID from query results

Example:

uv run commands/doc-delete doc_abc123...

Output:

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

Warning: Permanent deletion - cannot be undone.

---

Exit Codes

• 0 - Success
• 1 - Error (JSON error in stderr)