# hoody-curl Subskill ## Overview **hoody-curl** is a universal HTTP proxy service that GET-ifies any REST API for universal access. It stores, replays, and schedules HTTP requests through simple CLI commands, eliminating the need for complex curl configurations. ### When to Use - **API Testing**: Execute HTTP requests against any endpoint with full curl capabilities - **Scheduled Requests**: Create cron-based recurring HTTP calls for monitoring or data collection - **Session Management**: Maintain cookie-based authentication across multiple requests - **File Downloads**: Save and retrieve HTTP response bodies from storage - **Async Operations**: Submit long-running requests as background jobs - **Event Monitoring**: Subscribe to real-time job lifecycle events via WebSocket ### How It Fits Hoody Philosophy hoody-curl embodies "GET-ify any REST API for universal access" by: - Proxying complex API calls through simple, repeatable CLI commands - Providing persistent storage for request configurations and results - Enabling scheduled execution without external cron services - Maintaining session state for authenticated workflows - Offering transparent access to raw HTTP responses ### Core Concepts | Concept | Description | |---------|-------------| | **Jobs** | Async HTTP requests that run in background (Pending → Running → Completed/Failed) | | **Schedules** | Cron-based recurring requests that persist across restarts | | **Sessions** | Cookie containers for stateful HTTP interactions | | **Storage** | Persistent file storage for downloaded responses | --- ## Common Workflows ### 1. Health Check and Service Status ``` # Check service health hoody curl health -c my-container # Get Prometheus metrics hoody curl metrics -c my-container -o json ``` ### 2. Execute Simple HTTP Request (GET) ``` # Simple GET request via query parameters hoody curl get-url -c my-container --url "https://api.example.com/data" # With machine-readable output hoody curl get-url -c my-container --url "https://api.example.com/data" -o json ``` ### 3. Execute Advanced HTTP Request (POST) ``` # POST request with full configuration hoody curl exec -c my-container \ --url "https://api.example.com/submit" \ --method POST \ --header "Content-Type: application/json" \ --data '{"key": "value"}' # Async mode - returns job ID for tracking hoody curl exec -c my-container \ --url "https://api.example.com/long-task" \ --mode async ``` ### 4. Monitor Async Jobs ``` # List all async jobs hoody curl list -c my-container # Get specific job details hoody curl get -c my-container # Get job response body (for completed jobs) hoody curl result -c my-container # Cancel a pending/running job hoody curl cancel -c my-container ``` ### 5. Create Recurring Schedule ``` # Create a schedule that runs every 5 minutes hoody curl create -c my-container \ --cron "*/5 * * * * *" \ --url "https://api.example.com/health" \ --method GET # List all schedules hoody curl list -c my-container # Get schedule details hoody curl get -c my-container # Toggle schedule on/off hoody curl toggle -c my-container --enabled false # Delete a schedule hoody curl delete -c my-container --yes ``` ### 6. Manage Cookie Sessions ``` # List all sessions hoody curl list -c my-container # Get session details hoody curl get -c my-container # Get only cookies from a session hoody curl cookies -c my-container # Delete a session hoody curl delete -c my-container --yes ``` ### 7. Manage Downloaded Files ``` # List all saved files hoody curl list -c my-container # Download a saved file hoody curl get "by-domain/example.com/response.json" -c my-container # Delete a saved file hoody curl delete "by-domain/example.com/response.json" -c my-container --yes ``` ### 8. Subscribe to Job Events ``` # Subscribe to real-time job events via WebSocket hoody curl events -c my-container ``` --- ## Advanced Operations ### Multi-Step Workflow: Authenticated API Scraping ``` # Step 1: Create a session for cookie persistence hoody curl exec -c my-container \ --url "https://example.com/login" \ --method POST \ --data '{"username": "user", "password": "pass"}" \ --session my-session # Step 2: Verify session cookies hoody curl cookies my-session -c my-container # Step 3: Use session for authenticated requests hoody curl exec -c my-container \ --url "https://example.com/api/data" \ --session my-session # Step 4: Schedule recurring authenticated requests hoody curl create -c my-container \ --cron "0 */30 * * * *" \ --url "https://example.com/api/data" \ --session my-session ``` ### Multi-Step Workflow: File Download Pipeline ``` # Step 1: Execute request with file saving enabled hoody curl exec -c my-container \ --url "https://example.com/report.pdf" \ --save true # Step 2: List saved files to find the path hoody curl list -c my-container # Step 3: Download the saved file hoody curl get "by-domain/example.com/report.pdf" -c my-container ``` ### Error Recovery Patterns **Job Failed - Check and Retry:** ``` # Check job status and error details hoody curl get -c my-container # If transient error, create new request hoody curl exec -c my-container \ --url "https://api.example.com/data" \ --mode async ``` **Schedule Not Running - Verify State:** ``` # Check schedule status hoody curl get -c my-container # Ensure schedule is enabled hoody curl toggle -c my-container --enabled true ``` ### Performance Considerations | Scenario | Recommendation | |----------|----------------| | High-frequency requests | Use schedules instead of manual execution | | Large responses | Enable file saving to storage | | Long-running requests | Use async mode (`--mode async`) | | Multiple authenticated endpoints | Reuse sessions across requests | | Monitoring/alerting | Use WebSocket events for real-time updates | ### Cron Expression Format hoody-curl uses 6-field cron expressions: ``` second minute hour day month weekday ``` **Examples:** - `*/5 * * * * *` - Every 5 seconds - `0 */15 * * * *` - Every 15 minutes - `0 0 9 * * 1-5` - 9 AM on weekdays - `0 0 0 1 * *` - Midnight on 1st of month --- ## Quick Reference ### Essential Commands | Command | Description | |---------|-------------| | `hoody curl health` | Service health check | | `hoody curl exec` | Execute HTTP request (aliases: run) | | `hoody curl get-url` | Simple GET via query params | | `hoody curl list` | List jobs/schedules/sessions/storage | | `hoody curl get ` | Get details by ID or path | | `hoody curl cancel ` | Cancel async job | | `hoody curl result ` | Get job response body | | `hoody curl create` | Create schedule (aliases: new, add) | | `hoody curl toggle ` | Enable/disable schedule | | `hoody curl delete ` | Delete resource (requires --yes) | | `hoody curl cookies ` | Get session cookies | | `hoody curl events` | Subscribe to WebSocket events | | `hoody curl metrics` | Prometheus metrics | ### Common Parameters | Parameter | Description | |-----------|-------------| | `-c ` | Target container (required) | | `-o json` | Machine-readable JSON output | | `--url ` | Target URL for request | | `--method ` | HTTP method (GET, POST, etc.) | | `--data ` | Request body | | `--header

` | Request headers | | `--session ` | Cookie session name | | `--mode ` | Execution mode | | `--save ` | Save response to storage | | `--cron ` | Cron schedule expression | | `--enabled ` | Schedule enabled state | | `--yes` | Skip deletion confirmation | ### Typical Response Formats **Job Object:** ``` { "id": "job_abc123", "status": "completed", "url": "https://api.example.com/data", "method": "GET", "created_at": "2025-01-15T10:30:00Z", "completed_at": "2025-01-15T10:30:02Z", "response_status": 200 } ``` **Schedule Object:** ``` { "id": "sched_xyz789", "cron": "*/5 * * * * *", "enabled": true, "next_run": "2025-01-15T10:35:00Z", "request": { "url": "https://api.example.com/health", "method": "GET" } } ``` **Session Object:** ``` { "id": "sess_def456", "name": "my-session", "created_at": "2025-01-15T10:00:00Z", "last_used": "2025-01-15T10:30:00Z", "cookie_count": 5 } ``` **Health Response:** ``` { "status": "healthy", "version": "1.0.0", "uptime": 86400 } ```