# hoody-files Subskill ## Overview ### Service Description hoody-files is Hoody's universal file access service providing a unified interface to local storage and 60+ cloud storage providers. Every file path is treated as a URL, enabling seamless file operations regardless of underlying storage. The service runs inside a Hoody container and is accessed exclusively through the `hoody files` CLI command group. ### Key Capabilities - Universal file CRUD across local and cloud storage - 60+ cloud provider backends (S3, Google Drive, Dropbox, OneDrive, and many more) - Archive operations (ZIP, TAR, compressed TAR extraction and creation) - On-the-fly image processing and format conversion - File search by name pattern (glob) and content (grep/ripgrep) - Persistent FUSE mounts for remote storage backends - File mutation journal for auditing and change tracking - Remote ad-hoc access via FTP, SSH, Git, WebDAV, and S3 protocols - Resumable uploads, append operations, and permission management ### When to Use Use hoody-files when you need to: - Upload, download, list, or delete files in a container - Connect to cloud storage providers (S3, Google Drive, Dropbox, etc.) - Extract or preview ZIP/TAR archives - Search for files by glob pattern or content regex - Mount remote storage as a persistent local filesystem - Process images (resize, convert format, generate thumbnails) - Track file mutations via the journal system - Access files on remote FTP, SSH, Git, or WebDAV servers ### Authentication All commands require authentication and container targeting: ``` # Authenticate interactively hoody auth login # Or set token via environment variable export HOODY_TOKEN="your-api-token" # Or pass token per-command hoody files get / -c --token # Use a named profile hoody files get / -c --profile production ``` ### Key Concepts | Concept | Description | |---------|-------------| | **Container** | The hoody-files service runs inside a Hoody container. All file operations target a specific container via `-c `. | | **Backend** | A connected storage provider (S3, Google Drive, local, etc.). Each backend has a unique ID and type. | | **Mount** | A persistent FUSE filesystem mount that exposes remote storage as a local directory. Mounts survive restarts. | | **Path** | Every file path is a URL. Paths are relative to the container root or a mounted backend. | | **Journal** | A mutation log tracking all file changes for auditing, debugging, and recovery. | ### How It Fits the Hoody Philosophy hoody-files embodies universal access by treating every file path as a URL. Whether files reside on local disk, S3, Google Drive, or a Git repository, the same CLI commands work uniformly. This eliminates provider-specific tooling and enables portable, reproducible workflows across all 60+ storage backends. ### CLI Aliases The `hoody files` command group supports these aliases: ``` hoody files # Primary hoody file # Alias hoody f # Short alias hoody fs # Short alias ``` --- ## Core Resource Workflows ### 1. File Operations File operations are the foundation of hoody-files. These map to the legacy endpoint layer (`/{path}`) and provide direct file access. #### List Directory Contents ``` # List directory contents (table output) hoody files get /documents -c # List directory contents (JSON output) hoody files get /documents -c -o json # Alternative command hoody files dir /documents -c ``` Example JSON response: ``` { "path": "/documents", "items": [ { "name": "report.pdf", "type": "file", "size": 1048576, "modified": "2025-01-15T10:30:00Z" }, { "name": "images", "type": "directory", "size": 0, "modified": "2025-01-14T08:00:00Z" } ] } ``` #### Download a File ``` # Download a file (returns content directly) hoody files get /documents/report.pdf -c # Force download with Content-Disposition: attachment hoody files get /documents/report.pdf?download -c ``` #### Upload a File ``` # Upload a file (creates new or overwrites existing) hoody files put /documents/new-report.pdf -c # Upload using alternative command name hoody files upload /documents/new-report.pdf -c ``` #### Modify File Properties ``` # Rename a file hoody files patch /documents/old-name.pdf -c # Move or rename via modify-properties hoody files modify-properties /documents/report.pdf -c ``` #### Delete Files and Directories ``` # Delete a file (requires --yes confirmation) hoody files delete /documents/old-report.pdf -c --yes # Delete using aliases hoody files rm /documents/temp-file.txt -c --yes hoody files remove /documents/temp-file.txt -c --yes # Recursive delete for directories hoody files delete-recursive /documents/archive/ -c --yes ``` #### Touch a File ``` # Create empty file if not exists, or update modification time hoody files touch /documents/new-file.txt -c ``` Maps to `PUT /{path}?touch`. Cannot be used on directories. #### Get File Metadata (HEAD) ``` # Get metadata without downloading content hoody files metadata /documents/report.pdf -c ``` Maps to `HEAD /{path}`. Returns headers with size, type, and modification time. #### Get Allowed Methods (OPTIONS) ``` # Get supported HTTP methods for a path hoody files options /documents/report.pdf -c -o json ``` Maps to `OPTIONS /{path}`. Used by WebDAV clients for capability discovery. Example JSON response: ``` { "allow": "GET, HEAD, OPTIONS, PUT, PATCH, DELETE" } ``` --- ### 2. Advanced File Operations (API v1) These operations use the structured `/api/v1/files/` endpoints for advanced file manipulation. #### Append Data to File ``` # Append binary data to end of existing file hoody files append /documents/log.txt -c ``` Maps to `PUT /api/v1/files/append/{path}`. Creates the file if it does not exist. Auto-creates parent directories. #### Change File Permissions (Unix) ``` # Change permissions using octal mode hoody files chmod /documents/script.sh -c ``` Maps to `PATCH /api/v1/files/chmod/{path}`. Pass the mode value (e.g., 755) when prompted or via flags. #### Change File Ownership (Unix) ``` # Change owner and group hoody files chown /documents/data/ -c ``` Maps to `PATCH /api/v1/files/chown/{path}`. Pass owner:group (e.g., user:staff). Group is optional. #### Copy Files and Directories ``` # Copy a file to a new location hoody files copy /documents/report.pdf -c # Copy a directory recursively hoody files copy /documents/project/ -c ``` Maps to `POST /api/v1/files/copy/{path}`. Auto-creates parent directories at destination. Use overwrite flag to replace existing destination. #### Move Files and Directories ``` # Move or rename a file hoody files move /documents/old-name.pdf -c # Move across directories hoody files move /documents/report.pdf -c ``` Maps to `POST /api/v1/files/move/{path}`. Works across directories. Auto-creates parent directories at destination. Requires both upload and delete permissions. #### Resolve Canonical Path ``` # Resolve symbolic links and relative paths to canonical form hoody files realpath /documents/link-to-file -c -o json ``` Maps to `GET /api/v1/files/realpath/{path}`. Equivalent to POSIX `realpath(3)`. Example JSON response: ``` { "path": "/documents/link-to-file", "realpath": "/storage/actual-file.txt" } ``` #### Get Detailed File Stats ``` # Get detailed metadata without downloading content hoody files stat /documents/report.pdf -c -o json ``` Maps to `GET /api/v1/files/stat/{path}`. Returns name, type, size, modification time, permissions, ownership, and symlink information. Example JSON response: ``` { "name": "report.pdf", "type": "file", "size": 1048576, "modified": "2025-01-15T10:30:00Z", "permissions": "0644", "owner": "user", "group": "staff", "symlink": false } ``` #### Multi-Purpose File Operations ``` # Create directory hoody files operation /documents/new-folder -c # Extract archive to destination hoody files operation /documents/archive.zip -c # Download from URL to destination hoody files operation /documents/ -c # Move file hoody files operation /documents/source.txt -c # Copy file hoody files operation /documents/source.txt -c ``` Maps to `POST /api/v1/files/{path}`. Supports: create directory, extract archive, download from URL, move, or copy. #### Modify Properties via API v1 ``` # Change permissions via API v1 hoody files modify-properties /documents/file.txt -c # Rename via API v1 (JSON body with name) hoody files modify-properties /documents/old.txt -c # Move across directories via API v1 (JSON body with move_to) hoody files modify-properties /documents/file.txt -c ``` Maps to `PATCH /api/v1/files/{path}`. Supports chmod, chown, rename, and cross-directory move. #### Upload via API v1 ``` # Upload file via API v1 hoody files put /documents/upload.txt -c # Append to existing file instead of overwriting hoody files put /documents/log.txt -c ``` Maps to `PUT /api/v1/files/{path}`. Use append flag to append instead of overwriting. #### Delete via API v1 ``` # Delete file or directory via API v1 hoody files delete /documents/temp-file.txt -c --yes ``` Maps to `DELETE /api/v1/files/{path}`. #### List/Download via API v1 ``` # Get directory listing in JSON format hoody files get /documents -c -o json # Download a file hoody files get /documents/report.pdf -c ``` Maps to `GET /api/v1/files/{path}`. Supports optional backend parameter for remote files. --- ### 3. File Search and Discovery #### Search Directory ``` # Search for files matching a query hoody files search /documents -c # Search with JSON output hoody files search /documents -c -o json ``` Maps to `GET /{directory}?q`. Returns HTML by default, or JSON with `-o json`. #### Glob Pattern Search ``` # Find files matching glob pattern hoody files glob /documents -c -o json ``` Maps to `GET /api/v1/files/glob/{path}`. Returns file metadata sorted by name. Supported patterns: - `*.rs` — standard wildcards - `**/*.rs` — recursive patterns - `{ts,tsx}` — brace expansion - `[a-z]` — character classes Example JSON response: ``` { "path": "/documents", "pattern": "**/*.pdf", "matches": [ { "name": "report.pdf", "path": "/documents/report.pdf", "type": "file", "size": 1048576, "modified": "2025-01-15T10:30:00Z" }, { "name": "summary.pdf", "path": "/documents/reports/summary.pdf", "type": "file", "size": 524288, "modified": "2025-01-14T16:00:00Z" } ] } ``` #### Content Search (Grep) ``` # Search file contents using regex patterns hoody files grep /documents -c -o json ``` Maps to `GET /api/v1/files/grep/{path}`. Powered by ripgrep engine with .gitignore support, binary file detection, and configurable limits. Returns matching lines with optional context. Example JSON response: ``` { "path": "/documents", "pattern": "TODO", "matches": [ { "file": "/documents/code.py", "line_number": 42, "line": " # TODO: implement this function" }, { "file": "/documents/app.js", "line_number": 108, "line": " // TODO: add error handling" } ] } ``` --- ### 4. Archive Operations hoody-files supports ZIP, TAR, and compressed TAR archives (gzip, bzip2, xz, zstd). #### Extract Archive ``` # Extract entire archive to destination hoody files create /documents/archive.zip -c # Selectively extract matching entries hoody files create /documents/archive.zip -c ``` Maps to `GET /{archive}?extract`. Empty extract extracts all; with a path parameter, selectively extracts matching entries. #### Extract Single File from Archive ``` # Extract a single file or directory from archive hoody files extract-file /documents/archive.zip -c ``` Maps to `GET /{archive}?extract_file`. Only the specified entry (and its children if a directory) is extracted, leaving other archive contents untouched. #### Preview Archive Contents ``` # List all entries in archive (JSON) hoody files preview /documents/archive.zip -c -o json # Read a specific file from archive without extracting hoody files preview /documents/archive.zip -c ``` Maps to `GET /{archive}?preview`. With empty preview: returns JSON listing of all entries. With a path: returns the specific file content. Example JSON response for listing: ``` { "archive": "/documents/archive.zip", "entries": [ { "name": "file1.txt", "size": 1024, "modified": "2025-01-10T12:00:00Z" }, { "name": "folder/", "size": 0, "modified": "2025-01-10T12:00:00Z" }, { "name": "folder/file2.txt", "size": 2048, "modified": "2025-01-10T12:00:00Z" } ] } ``` #### View File from Archive ``` # Read and return a single file from archive hoody files view /documents/archive.zip -c ``` Maps to `GET /{archive}?view_file`. Returns raw file content with auto-detected MIME type. Useful for inspecting files without full extraction. #### Download Directory as ZIP ``` # Create and download directory as ZIP archive hoody files zip /documents/project -c ``` Maps to `GET /{directory}?zip`. Creates a ZIP archive of the directory and returns it for download. #### Extraction History and Status ``` # Get history of past extractions (successful and failed) hoody files history -c -o json # Get progress of currently running extractions hoody files active -c -o json # Alternative command for active extractions hoody files all -c -o json ``` Maps to: - `GET /?extraction_history` — extraction history - `GET /?extractions` — active extractions - `GET /api/v1/extractions` — active extractions (API v1) Example JSON response for extraction history: ``` { "extractions": [ { "id": "ext-001", "archive": "/documents/archive.zip", "destination": "/documents/extracted/", "status": "completed", "entries_extracted": 15, "started": "2025-01-15T10:00:00Z", "completed": "2025-01-15T10:05:00Z" }, { "id": "ext-002", "archive": "/documents/broken.tar.gz", "destination": "/documents/extracted/", "status": "failed", "error": "corrupt archive header", "started": "2025-01-15T11:00:00Z", "completed": "2025-01-15T11:00:01Z" } ] } ``` Example JSON response for active extractions: ``` { "extractions": [ { "id": "ext-003", "archive": "/documents/large-archive.zip", "destination": "/documents/extracted/", "status": "extracting", "progress": 67.5, "entries_processed": 135, "entries_total": 200 } ] } ``` --- ### 5. Download Management #### Download from Remote URL ``` # Download a file from a remote URL to the server hoody files url /documents/ -c ``` Maps to `GET /{directory}?download`. Downloads a file from a specified URL into the target directory. #### Download History ``` # Get history of past downloads hoody files history -c -o json ``` Maps to `GET /?download_history`. Example JSON response: ``` { "downloads": [ { "id": "dl-001", "url": "https://example.com/file.zip", "destination": "/documents/file.zip", "status": "completed", "size": 10485760, "started": "2025-01-15T09:00:00Z", "completed": "2025-01-15T09:02:00Z" }, { "id": "dl-002", "url": "https://example.com/data.tar.gz", "destination": "/documents/data.tar.gz", "status": "completed", "size": 52428800, "started": "2025-01-15T08:00:00Z", "completed": "2025-01-15T08:05:00Z" } ] } ``` #### Active Downloads ``` # Get progress of currently running downloads hoody files active /documents/ -c -o json # Alternative command hoody files all -c -o json ``` Maps to: - `GET /{directory}?downloads` — active downloads for directory - `GET /api/v1/downloads` — all active downloads (API v1) Example JSON response: ``` { "downloads": [ { "id": "dl-003", "url": "https://example.com/large-file.zip", "destination": "/documents/large-file.zip", "status": "downloading", "progress": 45.2, "downloaded_bytes": 473957171, "total_bytes": 1048576000, "speed_bytes_per_sec": 5452595 } ] } ``` --- ### 6. Backend Management Backends are connected storage providers. hoody-files supports 62 backend types covering cloud storage, object storage, file hosting, network protocols, media platforms, decentralized storage, and specialized layers. #### List Connected Backends ``` # List all connected backends hoody files list -c -o json ``` Maps to `GET /api/v1/backends`. Example JSON response: ``` { "backends": [ { "id": "bk-s3-001", "type": "s3", "name": "my-s3-bucket", "status": "connected" }, { "id": "bk-gdrive-001", "type": "drive", "name": "my-google-drive", "status": "connected" }, { "id": "bk-local-001", "type": "local", "name": "container-storage", "status": "connected" } ] } ``` #### Connect a New Backend Each backend type has its own connection command. The CLI will prompt for required credentials interactively, or they can be passed via flags. **Cloud Storage Providers:** ``` # Google Drive (OAuth flow) hoody files drive -c # Dropbox (OAuth flow) hoody files dropbox -c # OneDrive (OAuth flow) hoody files onedrive -c # Box (OAuth flow) hoody files box -c # pCloud hoody files pcloud -c # MEGA hoody files mega -c # iCloud Drive hoody files iclouddrive -c # SugarSync hoody files sugarsync -c # OpenDrive hoody files opendrive -c # HiDrive hoody files hidrive -c # Koofr (also Digi Storage and Koofr-compatible providers) hoody files koofr -c # ProtonDrive hoody files protondrive -c ``` **Object Storage (S3-Compatible):** ``` # AWS S3 or S3-compatible (MinIO, DigitalOcean Spaces, etc.) hoody files s3 -c # Backblaze B2 (requires: account, key) hoody files b2 -c # Google Cloud Storage (not Google Drive) hoody files google-cloud-storage -c # Azure Blob Storage hoody files azureblob -c # Azure Files hoody files azurefiles -c # Oracle Cloud Infrastructure Object Storage hoody files oracleobjectstorage -c # QingStor hoody files qingstor -c # OpenStack Swift (Rackspace, Blomp, Memset, OVH) hoody files swift -c ``` **File Hosting Services:** ``` # 1fichier hoody files fichier -c # GoFile hoody files gofile -c # Linkbox hoody files linkbox -c # Pixeldrain hoody files pixeldrain -c # Premiumize.me hoody files premiumizeme -c # Put.io hoody files putio -c # Uloz.to hoody files ulozto -c # Uptobox hoody files uptobox -c # Files.com hoody files filescom -c # Enterprise File Fabric (requires: url) hoody files filefabric -c # ShareFile hoody files sharefile -c # Quatrix hoody files quatrix -c # Seafile hoody files seafile -c # Internet Archive hoody files internetarchive -c ``` **Network Protocol Backends:** ``` # FTP (requires: host) hoody files ftp -c # SFTP/SSH hoody files sftp -c # HTTP server hoody files http -c # WebDAV (Nextcloud, ownCloud, etc.) hoody files webdav -c # SMB/CIFS hoody files smb -c # Hadoop HDFS hoody files hdfs -c ``` **Specialized Layer Backends:** ``` # Alias to existing backend path (requires: remote) hoody files alias -c # Cache layer (requires: remote) hoody files cache -c # Chunker for large files (requires: remote) hoody files chunker -c # Combine multiple remotes (requires: upstreams) hoody files combine -c # Compression layer (requires: remote) hoody files compress -c # Encryption layer (requires: remote, password) hoody files crypt -c # Better checksums (requires: remote) hoody files hasher -c # In-memory storage hoody files memory -c # Union merge of multiple remotes hoody files union -c # Local filesystem hoody files local -c ``` **Media and Photo Services:** ``` # Cloudinary (requires: api_key, api_secret, cloud_name) hoody files cloudinary -c # ImageKit hoody files imagekit -c # Google Photos hoody files google-photos -c ``` **Decentralized Storage:** ``` # Storj Decentralized Cloud Storage hoody files storj -c # Tardigrade (Storj) hoody files tardigrade -c # Sia decentralized storage hoody files sia -c ``` **Regional Providers:** ``` # Mail.ru Cloud hoody files mailru -c # Jottacloud hoody files jottacloud -c # Akamai NetStorage hoody files netstorage -c # Yandex Disk hoody files yandex -c # Zoho WorkDrive hoody files zoho -c # PikPak hoody files pikpak -c ``` #### Get Backend Details ``` # Get detailed information about a specific backend hoody files get -c -o json ``` Maps to `GET /api/v1/backends/{id}`. Example JSON response: ``` { "id": "bk-s3-001", "type": "s3", "name": "my-s3-bucket", "status": "connected", "config": { "provider": "AWS", "region": "us-east-1", "bucket": "my-bucket", "endpoint": "s3.amazonaws.com" }, "connected_since": "2025-01-10T08:00:00Z" } ``` #### Update Backend Credentials ``` # Rotate credentials for an existing backend hoody files update -c ``` Maps to `PUT /api/v1/backends/{id}`. Allows rotating passwords, tokens, OAuth refresh tokens, S3 keys, and passphrases. Identity fields (host, user, port, type) cannot be changed — disconnect and reconnect to change those. #### Test Backend Connection ``` # Verify that a backend connection is working hoody files test -c -o json ``` Maps to `GET /api/v1/backends/{id}/test`. Example JSON response: ``` { "id": "bk-s3-001", "status": "connected", "latency_ms": 45, "tested_at": "2025-01-15T10:30:00Z" } ``` #### Disconnect a Backend ``` # Disconnect and remove a backend connection hoody files disconnect -c --yes ``` Maps to `DELETE /api/v1/backends/{id}`. #### All 62 Supported Backend Types | Category | Types | |----------|-------| | **Cloud Storage** | drive, dropbox, onedrive, box, pcloud, mega, iclouddrive, sugarsync, opendrive, hidrive, koofr, protondrive | | **Object Storage** | s3, b2, google-cloud-storage, azureblob, azurefiles, oracleobjectstorage, qingstor, swift | | **File Hosting** | fichier, gofile, linkbox, pixeldrain, premiumizeme, putio, ulozto, uptobox, filescom, filefabric, sharefile, quatrix, seafile, internetarchive | | **Network Protocols** | ftp, sftp, http, webdav, smb, hdfs | | **Specialized Layers** | alias, cache, chunker, combine, compress, crypt, hasher, memory, union, local | | **Media** | cloudinary, imagekit, google-photos | | **Decentralized** | storj, tardigrade, sia | | **Regional** | mailru, jottacloud, netstorage, yandex, zoho, pikpak | --- ### 7. Mount Management Mounts create persistent FUSE filesystem mounts for connected backends, allowing direct file system access to remote storage. All mounts are automatically persisted and restored on server restart. #### List Active Mounts ``` # List all active filesystem mounts hoody files list -c -o json # Filter by label hoody files list -c -o json ``` Maps to `GET /api/v1/mounts`. Supports filtering by label via query parameter. Example JSON response: ``` { "mounts": [ { "id": "mnt-001", "backend_id": "bk-s3-001", "mount_point": "/mnt/s3-bucket", "status": "mounted", "label": "production-data", "created": "2025-01-10T08:00:00Z" }, { "id": "mnt-002", "backend_id": "bk-gdrive-001", "mount_point": "/mnt/google-drive", "status": "mounted", "label": "documents", "created": "2025-01-12T14:00:00Z" } ] } ``` #### Create a FUSE Mount ``` # Create a persistent FUSE mount for a connected backend hoody files create -c # Using aliases hoody files new -c hoody files add -c ``` Maps to `POST /api/v1/mounts`. Requires a connected backend ID. The mount is automatically persisted and restored on server restart. #### Get Mount Details ``` # Get detailed information about a specific mount hoody files get -c -o json ``` Maps to `GET /api/v1/mounts/{id}`. Example JSON response: ``` { "id": "mnt-001", "backend_id": "bk-s3-001", "mount_point": "/mnt/s3-bucket", "status": "mounted", "label": "production-data", "vfs_config": { "cache_size_mb": 1024, "buffer_size_mb": 64, "read_ahead_kb": 256 }, "created": "2025-01-10T08:00:00Z", "last_accessed": "2025-01-15T10:30:00Z" } ``` #### Update Mount Configuration ``` # Update VFS configuration for an existing mount hoody files update -c ``` Maps to `PATCH /api/v1/mounts/{id}`. Allows changing cache settings, buffer sizes, and other VFS parameters. #### Remove a Mount ``` # Remove mount and disconnect FUSE filesystem hoody files unmount -c --yes ``` Maps to `DELETE /api/v1/mounts/{id}`. --- ### 8. Journal System The journal tracks all file mutations for auditing, debugging, and recovery. It records every write, delete, rename, and permission change. #### Query Journal Entries ``` # Query file mutation journal entries hoody files query -c -o json ``` Maps to `GET /api/v1/journal`. Supports cursor-based pagination via `after_id` parameter and optional filters. Example JSON response: ``` { "entries": [ { "id": "jrn-001", "operation": "write", "path": "/documents/report.pdf", "timestamp": "2025-01-15T10:30:00Z", "size_bytes": 1048576, "backend_id": "bk-s3-001" }, { "id": "jrn-002", "operation": "delete", "path": "/documents/temp.txt", "timestamp": "2025-01-15T10:35:00Z", "backend_id": "bk-local-001" }, { "id": "jrn-003", "operation": "rename", "path": "/documents/old-name.pdf", "new_path": "/documents/new-name.pdf", "timestamp": "2025-01-15T10:40:00Z", "backend_id": "bk-s3-001" } ], "cursor": "jrn-003", "has_more": false } ``` #### Flush Journal ``` # Force all pending journal entries to be written and fsynced to disk hoody files flush -c -o json ``` Maps to `POST /api/v1/journal/flush`. Returns 200 with `flushed: true` if all entries were durably persisted, or 503 with `flushed: false` if flush failed. Example JSON response (success): ``` { "flushed": true, "entries_written": 15, "flush_duration_ms": 120 } ``` Example JSON response (failure): ``` { "flushed": false, "error": "disk full", "entries_pending": 15 } ``` #### Journal Statistics ``` # Get storage statistics for the journal system hoody files stats -c -o json ``` Maps to `GET /api/v1/journal/stats`. Returns entry counts, blob storage usage, writer health, and pruning info. Example JSON response: ``` { "entry_count": 1500, "blob_storage_bytes": 52428800, "writer_health": "healthy", "last_prune": "2025-01-14T00:00:00Z", "oldest_entry": "2025-01-01T00:00:00Z", "newest_entry": "2025-01-15T10:40:00Z" } ``` --- ### 9. Image Processing hoody-files provides on-the-fly image processing with format conversion, resizing, and effects. Works for both local files and all 60+ remote cloud storage backends. #### Process and Convert Images ``` # Process image with thumbnail generation and conversion hoody files process-image /images/photo.jpg -c ``` Maps to `GET /{image}?thumbnail`. Supports format conversion, resizing, and effects. **Supported Input Formats:** JPEG, PNG, WebP, GIF, BMP **Supported Output Formats:** JPEG, PNG, WebP, GIF, BMP --- ### 10. Remote File Access Access files from remote servers ad-hoc without creating a persistent backend connection. These commands map to the `?type=` query parameter endpoints. #### Access via FTP ``` # Access file via FTP hoody files ftp /path/to/file -c ``` Maps to `GET /{path}?type=ftp`. Connects to a remote FTP server and retrieves the file. #### Access via Git ``` # Fetch file from Git repository (GitHub, GitLab, Bitbucket, custom) hoody files fetch-from-git /path/to/file -c ``` Maps to `GET /{path}?type=git`. Access files from GitHub, GitLab, Bitbucket, or custom Git servers. #### Access via S3 ``` # Access file from S3 or S3-compatible storage hoody files s3 /path/to/file -c ``` Maps to `GET /{path}?type=s3`. Access AWS S3 or S3-compatible storage (MinIO, DigitalOcean Spaces, etc.). #### Access via SSH/SFTP ``` # Access file via SSH/SFTP hoody files ssh /path/to/file -c # Upload file to remote SSH server hoody files ssh-upload /path/to/file -c ``` Maps to: - `GET /{path}?type=ssh` — read file from SSH server - `PUT /{path}?type=ssh` — upload file to SSH server #### Access via WebDAV ``` # Access file via WebDAV (Nextcloud, ownCloud, etc.) hoody files webdav /path/to/file -c ``` Maps to `GET /{path}?type=webdav`. Connects to WebDAV servers like Nextcloud or ownCloud. --- ### 11. System and Health #### Health Check ``` # Check service health hoody files health -c -o json ``` Maps to `GET /api/v1/files/health`. Returns service identity, build and start timestamps, resource usage, and caller metadata. Example JSON response: ``` { "service": "hoody-files", "status": "healthy", "version": "1.0.0", "build_time": "2025-01-10T12:00:00Z", "start_time": "2025-01-15T08:00:00Z", "uptime_seconds": 86400, "memory_usage_mb": 256, "cpu_usage_percent": 2.5, "active_connections": 12 } ``` #### API Version ``` # Get current API version and server information hoody files version -c -o json ``` Maps to `GET /api/v1/version`. Example JSON response: ``` { "version": "1.0.0", "api_version": "v1", "server": "hoody-files", "build_date": "2025-01-10", "go_version": "1.22.0" } ``` --- ## Advanced Operations ### Full Backend Lifecycle Complete workflow for connecting, verifying, using, updating, and disconnecting a backend: ``` # Step 1: Connect to S3 backend hoody files s3 -c # Step 2: Verify the connection works hoody files test -c -o json # Step 3: List files on the backend hoody files get / -c -o json # Step 4: Upload a file hoody files put /data/new-file.txt -c # Step 5: Verify upload with stat hoody files stat /data/new-file.txt -c -o json # Step 6: Update credentials if rotation needed hoody files update -c # Step 7: Re-test after credential update hoody files test -c -o json # Step 8: Disconnect when no longer needed hoody files disconnect -c --yes # Step 9: Verify disconnection hoody files list -c -o json ``` ### Archive Extraction Workflow Complete workflow for downloading, previewing, selectively extracting, and verifying archives: ``` # Step 1: Download archive from remote URL hoody files url /downloads/ -c # Step 2: Verify download in history hoody files history -c -o json # Step 3: Preview archive contents before extracting hoody files preview /downloads/archive.zip -c -o json # Step 4: View a specific file from the archive hoody files view /downloads/archive.zip -c # Step 5: Extract specific files only hoody files extract-file /downloads/archive.zip -c # Step 6: Or extract entire archive hoody files create /downloads/archive.zip -c # Step 7: Monitor extraction progress hoody files active -c -o json # Step 8: Verify extracted files hoody files get /downloads/extracted/ -c -o json # Step 9: Check extraction history hoody files history -c -o json ``` ### Multi-Backend File Operations Copy or move files between different storage backends: ``` # Step 1: Connect source backend (S3) hoody files s3 -c # Step 2: Connect destination backend (Google Drive) hoody files drive -c # Step 3: List source files hoody files get /s3-data/ -c -o json # Step 4: Copy file from S3 to Google Drive hoody files copy /s3-data/report.pdf -c # Step 5: Verify copy on destination hoody files stat /drive-dest/report.pdf -c -o json # Step 6: Move file (copy + delete source) hoody files move /s3-data/old-report.pdf -c # Step 7: Verify source is removed hoody files get /s3-data/ -c -o json ``` ### Mount and Access Workflow Create a persistent mount for direct filesystem access to remote storage: ``` # Step 1: Connect backend hoody files s3 -c # Step 2: Test backend connection hoody files test -c -o json # Step 3: Create FUSE mount hoody files create -c # Step 4: Verify mount is active hoody files list -c -o json # Step 5: Get mount details hoody files get -c -o json # Step 6: Access mounted files directly hoody files get /mnt/s3-bucket/ -c -o json # Step 7: Upload files to mounted storage hoody files put /mnt/s3-bucket/new-data.txt -c # Step 8: Update mount VFS configuration for performance hoody files update -c # Step 9: Verify updated configuration hoody files get -c -o json # Step 10: Unmount when done hoody files unmount -c --yes # Step 11: Verify unmount hoody files list -c -o json ``` ### Batch File Operations with Search Use glob and grep for batch file discovery and operations: ``` # Step 1: Find all PDF files recursively hoody files glob /documents -c -o json # Step 2: Search for files containing specific text hoody files grep /documents -c -o json # Step 3: Search directory with query hoody files search /documents -c -o json # Step 4: Copy matching files to backup location hoody files copy /documents/reports/ -c # Step 5: Set permissions on copied files hoody files chmod /backup/reports/ -c # Step 6: Change ownership hoody files chown /backup/reports/ -c # Step 7: Verify operations via journal hoody files query -c -o json # Step 8: Clean up temporary files hoody files delete /documents/temp/ -c --yes ``` ### Error Recovery Patterns Handle common errors and recover gracefully: ``` # Step 1: Check service health hoody files health -c -o json # Step 2: Check API version for compatibility hoody files version -c -o json # Step 3: Test backend connection if operations fail hoody files test -c -o json # Step 4: Check journal for failed operations hoody files query -c -o json # Step 5: Flush journal if entries are pending hoody files flush -c -o json # Step 6: Verify journal health hoody files stats -c -o json # Step 7: Update backend credentials if auth expired hoody files update -c # Step 8: Re-test connection after credential update hoody files test -c -o json # Step 9: Retry the failed operation hoody files put /documents/file.txt -c # Step 10: Verify retry succeeded hoody files stat /documents/file.txt -c -o json ``` ### Journal-Based Auditing Track all file changes for compliance and debugging: ``` # Query all recent mutations hoody files query -c -o json # Get journal statistics (entry counts, storage usage) hoody files stats -c -o json # Force flush pending entries to disk hoody files flush -c -o json # Verify flush succeeded hoody files stats -c -o json ``` ### Layered Backend Architecture Build complex storage layers by stacking specialized backends: ``` # Step 1: Connect base S3 backend hoody files s3 -c # Step 2: Add encryption layer on top hoody files crypt -c # Step 3: Add caching layer hoody files cache -c # Step 4: Add chunking for large files hoody files chunker -c # Step 5: Test the layered backend hoody files test -c -o json # Step 6: Use the layered backend normally hoody files put /data/large-file.bin -c # Step 7: Verify file stats hoody files stat /data/large-file.bin -c -o json ``` ### Image Processing Pipeline Process images across cloud storage: ``` # Step 1: Connect to cloud storage with images hoody files drive -c # Step 2: List image files hoody files glob /photos -c -o json # Step 3: Process and convert image hoody files process-image /photos/vacation.jpg -c # Step 4: Verify processed output hoody files stat /photos/vacation-thumb.webp -c -o json ``` --- ## Quick Reference ### Endpoint Groups Summary | Group | Endpoint Count | CLI Commands | Description | |-------|---------------|--------------|-------------| | File Operations (legacy) | 7 | get, dir, put, upload, patch, delete, rm, touch, metadata, options | Direct file CRUD on `/{path}` | | File Operations (query) | 5 | search, url, active, zip, process-image | Query-based operations on `/{path}?...` | | Archive Operations | 4 | create, extract-file, preview, view | Archive extract/preview on `/{archive}?...` | | History/Status | 3 | history, active, all | Download and extraction history | | Remote Access | 6 | ftp, fetch-from-git, s3, ssh, ssh-upload, webdav | Ad-hoc remote file access | | File API v1 | 15 | append, chmod, chown, copy, move, glob, grep, health, move, realpath, stat, operation, modify-properties, put, delete, get | Structured API v1 file operations | | Backends (management) | 5 | list, get, update, disconnect, test | Backend CRUD and testing | | Backends (connect) | 62 | s3, drive, dropbox, onedrive, etc. | Connect 62 backend types | | Downloads | 1 | all | Active download status | | Extractions | 1 | all | Active extraction status | | Journal | 3 | query, flush, stats | File mutation journal | | Mounts | 5 | list, create, get, update, unmount | Persistent FUSE mounts | | System | 2 | health, version | Service health and version | ### Essential CLI Parameters | Parameter | Description | Example | |-----------|-------------|---------| | `-c ` | Target container (required for all operations) | `-c abc123def456ghi` | | `-o json` | JSON output format (machine-readable) | `-o json` | | `-o yaml` | YAML output format | `-o yaml` | | `-o wide` | Wide table format | `-o wide` | | `-o raw` | Raw output format | `-o raw` | | `--yes` | Skip confirmation prompts (for delete operations) | `--yes` | | `--token ` | API token (Bearer auth) | `--token abc123` | | `--username ` | Username for authentication | `--username admin` | | `--password ` | Password for authentication | `--password secret` | | `--config ` | Path to config file | `--config ~/.hoody/config.json` | | `--profile ` | Named configuration profile | `--profile production` | ### Command Aliases | Primary Command | Aliases | |-----------------|---------| | `hoody files` | `hoody file`, `hoody f`, `hoody fs` | | `hoody files delete` | `hoody files rm`, `hoody files remove` | | `hoody files create` | `hoody files new`, `hoody files add` | ### Authentication Methods ``` # Method 1: Interactive login hoody auth login # Method 2: Token flag per command hoody files get / -c --token # Method 3: Environment variable export HOODY_TOKEN="your-api-token" hoody files get / -c # Method 4: Username/password hoody files get / -c --username admin --password secret # Method 5: Config file hoody files get / -c --config ~/.hoody/config.json # Method 6: Named profile hoody files get / -c --profile production ``` ### Response Format Examples **Table (default):** ``` NAME TYPE SIZE MODIFIED report.pdf file 1.0 MB 2025-01-15 images directory 0 B 2025-01-14 data.csv file 2.5 MB 2025-01-13 ``` **JSON (`-o json`):** ``` { "path": "/documents", "items": [ { "name": "report.pdf", "type": "file", "size": 1048576, "modified": "2025-01-15T10:30:00Z" } ] } ``` ### Backend Required Fields Reference | Backend | Required Fields | |---------|----------------| | alias | `remote` | | b2 | `account`, `key` | | cache | `remote` | | chunker | `remote` | | cloudinary | `api_key`, `api_secret`, `cloud_name` | | combine | `upstreams` | | compress | `remote` | | crypt | `password`, `remote` | | filefabric | `url` | | ftp | `host` | All other backends either use OAuth flows, interactive prompts, or have no required fields in the schema. ### Complete Endpoint Path Reference | Method | Path | CLI Command | |--------|------|-------------| | GET | `/{path}` | `hoody files get`, `hoody files dir` | | PUT | `/{path}` | `hoody files put`, `hoody files upload` | | PATCH | `/{path}` | `hoody files patch`, `hoody files modify-properties` | | DELETE | `/{path}` | `hoody files delete`, `hoody files rm` | | HEAD | `/{path}` | `hoody files metadata` | | OPTIONS | `/{path}` | `hoody files options` | | PUT | `/{path}?touch` | `hoody files touch` | | GET | `/{directory}?q` | `hoody files search` | | GET | `/{directory}?download` | `hoody files url` | | GET | `/{directory}?downloads` | `hoody files active` | | GET | `/{directory}?zip` | `hoody files zip` | | GET | `/{image}?thumbnail` | `hoody files process-image` | | GET | `/{archive}?extract` | `hoody files create` | | GET | `/{archive}?extract_file` | `hoody files extract-file` | | GET | `/{archive}?preview` | `hoody files preview` | | GET | `/{archive}?view_file` | `hoody files view` | | GET | `/?download_history` | `hoody files history` | | GET | `/?extraction_history` | `hoody files history` | | GET | `/?extractions` | `hoody files active` | | GET | `/{path}?type=ftp` | `hoody files ftp` | | GET | `/{path}?type=git` | `hoody files fetch-from-git` | | GET | `/{path}?type=s3` | `hoody files s3` | | GET | `/{path}?type=ssh` | `hoody files ssh` | | PUT | `/{path}?type=ssh` | `hoody files ssh-upload` | | GET | `/{path}?type=webdav` | `hoody files webdav` | | GET | `/api/v1/backends` | `hoody files list` | | GET | `/api/v1/backends/{id}` | `hoody files get` | | PUT | `/api/v1/backends/{id}` | `hoody files update` | | DELETE | `/api/v1/backends/{id}` | `hoody files disconnect` | | GET | `/api/v1/backends/{id}/test` | `hoody files test` | | POST | `/api/v1/backends/{type}` | `hoody files ` (62 types) | | GET | `/api/v1/downloads` | `hoody files all` | | GET | `/api/v1/extractions` | `hoody files all` | | GET | `/api/v1/files/{path}` | `hoody files get` | | POST | `/api/v1/files/{path}` | `hoody files operation` | | PUT | `/api/v1/files/{path}` | `hoody files put` | | PATCH | `/api/v1/files/{path}` | `hoody files modify-properties` | | DELETE | `/api/v1/files/{path}` | `hoody files delete` | | PUT | `/api/v1/files/append/{path}` | `hoody files append` | | PATCH | `/api/v1/files/chmod/{path}` | `hoody files chmod` | | PATCH | `/api/v1/files/chown/{path}` | `hoody files chown` | | POST | `/api/v1/files/copy/{path}` | `hoody files copy` | | GET | `/api/v1/files/glob/{path}` | `hoody files glob` | | GET | `/api/v1/files/grep/{path}` | `hoody files grep` | | GET | `/api/v1/files/health` | `hoody files health` | | POST | `/api/v1/files/move/{path}` | `hoody files move` | | GET | `/api/v1/files/realpath/{path}` | `hoody files realpath` | | GET | `/api/v1/files/stat/{path}` | `hoody files stat` | | GET | `/api/v1/journal` | `hoody files query` | | POST | `/api/v1/journal/flush` | `hoody files flush` | | GET | `/api/v1/journal/stats` | `hoody files stats` | | GET | `/api/v1/mounts` | `hoody files list` | | POST | `/api/v1/mounts` | `hoody files create` | | GET | `/api/v1/mounts/{id}` | `hoody files get` | | PATCH | `/api/v1/mounts/{id}` | `hoody files update` | | DELETE | `/api/v1/mounts/{id}` | `hoody files unmount` | | GET | `/api/v1/version` | `hoody files version` |