Initial commit

skills/document-sync/references/COMMANDS.md

@@ -0,0 +1,223 @@
+# Command Reference
+
+## doc-push
+
+```bash
+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**:
+```bash
+uv run commands/doc-push specs.md --tags "api,v2"
+uv run commands/doc-push arch.md --tags "design,mvp" --description "MVP architecture"
+```
+
+**Output**:
+```json
+{
+  "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
+
+```bash
+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**:
+```bash
+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**:
+```json
+[
+  {
+    "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
+
+```bash
+uv run commands/doc-info <document-id>
+```
+
+**Arguments**: `<document-id>` - Document ID to retrieve metadata for
+
+**Examples**:
+```bash
+uv run commands/doc-info doc_abc123...
+```
+
+**Output**:
+```json
+{
+  "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):
+```json
+{"error": "Document not found: doc_abc123..."}
+```
+
+---
+
+## doc-read
+
+```bash
+uv run commands/doc-read <document-id>
+```
+
+**Arguments**: `<document-id>` - Document ID to read content from
+
+**Examples**:
+```bash
+# 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):
+```json
+{"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
+
+```bash
+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**:
+```bash
+uv run commands/doc-pull doc_abc123...
+uv run commands/doc-pull doc_abc123... -o custom-name.md
+```
+
+**Output**:
+```json
+{
+  "success": true,
+  "document_id": "doc_abc123...",
+  "filename": "/absolute/path/to/output.md",
+  "size_bytes": 2048
+}
+```
+
+---
+
+## doc-delete
+
+```bash
+uv run commands/doc-delete <document-id>
+```
+
+**Arguments**: `<document-id>` - Document ID from query results
+
+**Example**:
+```bash
+uv run commands/doc-delete doc_abc123...
+```
+
+**Output**:
+```json
+{
+  "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)