diff --git a/.plans/resource-management-implementation.md b/.plans/resource-management-implementation.md new file mode 100644 index 0000000..dc26d88 --- /dev/null +++ b/.plans/resource-management-implementation.md @@ -0,0 +1,508 @@ +# Hookdeck CLI Resource Management Implementation Plan + +## Background + +The Hookdeck CLI currently supports limited commands in `@pkg/cmd` with basic project management. This plan outlines implementing comprehensive resource management for projects, connections, sources, destinations, and transformations using the Hookdeck API (https://api.hookdeck.com/2025-07-01/openapi). + +## OpenAPI to CLI Conversion Strategy + +**See `AGENTS.md` sections 2-3 for comprehensive guidance on:** +- Parameter mapping rules (nested JSON → flat CLI flags) +- Flag naming conventions and standards +- Command structure patterns +- Conditional validation implementation with type-driven validation +- Help system integration for dynamic type-specific help + +**Key Principle**: All CLI commands must follow the established conversion patterns documented in `AGENTS.md` to ensure consistency across the entire codebase. + +## Objectives + +1. **Extend project management** - Add create, update, delete capabilities beyond current list/use +2. **Implement connection management** - Full CRUD operations for webhook connections +3. **Add source management** - Manage webhook sources with various provider types +4. **Add destination management** - Manage HTTP, CLI, and Mock API destinations +5. **Add transformation management** - Manage JavaScript code transformations +6. **Create reference documentation** - Comprehensive `REFERENCE.md` with examples +7. **Maintain consistency** - Follow existing CLI patterns and architecture + +## Success Criteria + +- All resource types support standard CRUD operations (list, get, create, update, delete) +- Commands follow existing CLI patterns and conventions +- Comprehensive error handling and validation +- Interactive selection for user-friendly experience +- Clear, actionable reference documentation +- Backward compatibility with existing commands + +--- + +## Task List + +### Phase 1: Foundation and Project Enhancement + +#### Task 1.1: Extend Project Commands +**Files to modify:** +- `pkg/cmd/project.go` - Add new subcommands +- `pkg/cmd/project_create.go` (new) +- `pkg/cmd/project_update.go` (new) +- `pkg/cmd/project_delete.go` (new) +- `pkg/hookdeck/projects.go` - Add API methods + +**API Endpoints:** +- POST `/teams` - Create project +- PUT `/teams/{id}` - Update project +- DELETE `/teams/{id}` - Delete project + +#### Task 1.2: Create Shared Utilities and CLI Framework +**Files to create:** +- `pkg/cmd/shared.go` - Common patterns for all resources +- `pkg/validators/resources.go` - Resource-specific validation +- `pkg/cli/flags.go` - OpenAPI to CLI flag conversion framework +- `pkg/cli/validation.go` - Conditional validation framework +- `pkg/cli/types.go` - Type registry and parameter mapping + +**Core Framework Components:** + +##### 1. OpenAPI to CLI Conversion Engine +```go +type FlagMapper struct { + // Maps OpenAPI parameter paths to CLI flags + // Example: "configs.strategy" -> "--strategy" + ParameterMap map[string]string + + // Conditional flag sets based on type parameter + // Example: type="delivery" enables "--strategy", "--connections" + ConditionalFlags map[string][]string + + // Validation rules per type + TypeValidators map[string]func(flags map[string]interface{}) error +} +``` + +##### 2. Type-Driven Parameter Validation +```go +type TypeRegistry struct { + // Source types: STRIPE, GITHUB, SHOPIFY, etc. + SourceTypes map[string]SourceTypeConfig + + // Destination types: HTTP, CLI, MOCK_API + DestinationTypes map[string]DestinationTypeConfig + + // Issue trigger types: delivery, transformation, backpressure + TriggerTypes map[string]TriggerTypeConfig +} + +type SourceTypeConfig struct { + RequiredFlags []string // Required parameters for this type + OptionalFlags []string // Optional parameters for this type + Validator func(flags map[string]interface{}) error + HelpText string // Type-specific help text +} +``` + +##### 3. Progressive Validation Framework +```go +type ValidationChain struct { + // Pre-validation: Check flag combinations + PreValidators []func(flags map[string]interface{}) error + + // Type validation: Validate based on --type parameter + TypeValidator func(typeValue string, flags map[string]interface{}) error + + // Post-validation: Final consistency checks + PostValidators []func(flags map[string]interface{}) error +} +``` + +**Utilities to implement:** +- Standard CRUD command templates with type-aware validation +- Common output formatting functions +- Interactive selection helpers with type-specific prompts +- Error handling patterns with contextual help +- OpenAPI schema to CLI flag conversion utilities +- Conditional parameter validation framework + +### Phase 2: Core Resource Management + +#### Task 2.1: Implement Source Management +**Files to create:** +- `pkg/cmd/source.go` - Main source command group +- `pkg/cmd/source_list.go` - List sources with filtering +- `pkg/cmd/source_get.go` - Get single source details +- `pkg/cmd/source_create.go` - Create new sources +- `pkg/cmd/source_update.go` - Update existing sources +- `pkg/cmd/source_delete.go` - Delete sources +- `pkg/cmd/source_enable.go` - Enable disabled sources +- `pkg/cmd/source_disable.go` - Disable sources +- `pkg/source/source.go` - API wrapper functions +- `pkg/hookdeck/sources.go` - Client methods and models + +**API Endpoints:** +- GET `/sources` - List sources +- GET `/sources/{id}` - Get source +- POST `/sources` - Create source +- PUT `/sources/{id}` - Update source +- DELETE `/sources/{id}` - Delete source +- PUT `/sources/{id}/enable` - Enable source +- PUT `/sources/{id}/disable` - Disable source + +**Key Features:** +- Support for 80+ source types (Stripe, GitHub, Shopify, etc.) +- Authentication configuration per source type +- URL generation and display +- Type-specific validation and help + +**Implementation Example - Source Creation with Type Validation:** +```go +// pkg/cmd/source_create.go +func newSourceCreateCommand() *cobra.Command { + var flags struct { + Name string + Type string + Description string + URL string + WebhookSecret string + APIKey string + BasicAuth string + // ... other type-specific flags + } + + cmd := &cobra.Command{ + Use: "create", + PreRunE: func(cmd *cobra.Command, args []string) error { + // Progressive validation + return validateSourceCreateFlags(&flags) + }, + RunE: func(cmd *cobra.Command, args []string) error { + return createSource(&flags) + }, + } + + // Standard flags + cmd.Flags().StringVar(&flags.Name, "name", "", "Source name (required)") + cmd.Flags().StringVar(&flags.Type, "type", "", "Source type: STRIPE, GITHUB, SHOPIFY, etc. (required)") + cmd.Flags().StringVar(&flags.Description, "description", "", "Source description") + + // Type-specific flags (conditionally validated) + cmd.Flags().StringVar(&flags.WebhookSecret, "webhook-secret", "", "Webhook secret for verification") + cmd.Flags().StringVar(&flags.APIKey, "api-key", "", "API key for authentication") + cmd.Flags().StringVar(&flags.BasicAuth, "basic-auth", "", "Basic auth credentials") + + return cmd +} + +func validateSourceCreateFlags(flags *sourceCreateFlags) error { + // Required flags + if flags.Name == "" { + return errors.New("--name is required") + } + if flags.Type == "" { + return errors.New("--type is required") + } + + // Type-specific validation + return validateSourceType(flags.Type, flags) +} + +func validateSourceType(sourceType string, flags *sourceCreateFlags) error { + switch sourceType { + case "STRIPE": + if flags.WebhookSecret == "" { + return errors.New("--webhook-secret is required for Stripe sources") + } + if flags.BasicAuth != "" { + return errors.New("--basic-auth is not supported for Stripe sources") + } + return nil + + case "GITHUB": + if flags.WebhookSecret == "" { + return errors.New("--webhook-secret is required for GitHub sources") + } + return nil + + case "HTTP": + // HTTP sources are flexible - any auth method allowed + return nil + + default: + return fmt.Errorf("unsupported source type: %s. Supported types: STRIPE, GITHUB, SHOPIFY, HTTP, ...", sourceType) + } +} +``` + +#### Task 2.2: Implement Destination Management +**Files to create:** +- `pkg/cmd/destination.go` - Main destination command group +- `pkg/cmd/destination_list.go` +- `pkg/cmd/destination_get.go` +- `pkg/cmd/destination_create.go` +- `pkg/cmd/destination_update.go` +- `pkg/cmd/destination_delete.go` +- `pkg/cmd/destination_enable.go` +- `pkg/cmd/destination_disable.go` +- `pkg/destination/destination.go` +- `pkg/hookdeck/destinations.go` + +**API Endpoints:** +- GET `/destinations` - List destinations +- GET `/destinations/{id}` - Get destination +- POST `/destinations` - Create destination +- PUT `/destinations/{id}` - Update destination +- DELETE `/destinations/{id}` - Delete destination +- PUT `/destinations/{id}/enable` - Enable destination +- PUT `/destinations/{id}/disable` - Disable destination + +**Key Features:** +- HTTP, CLI, and Mock API destination types +- Authentication configuration (Bearer, Basic, API Key, OAuth2, etc.) +- Rate limiting configuration +- Path forwarding settings + +#### Task 2.3: Implement Connection Management +**Files to create:** +- `pkg/cmd/connection.go` - Main connection command group +- `pkg/cmd/connection_list.go` +- `pkg/cmd/connection_get.go` +- `pkg/cmd/connection_create.go` +- `pkg/cmd/connection_update.go` +- `pkg/cmd/connection_delete.go` +- `pkg/cmd/connection_enable.go` +- `pkg/cmd/connection_disable.go` +- `pkg/cmd/connection_pause.go` +- `pkg/cmd/connection_unpause.go` +- `pkg/connection/connection.go` +- `pkg/hookdeck/connections.go` + +**API Endpoints:** +- GET `/connections` - List connections +- GET `/connections/{id}` - Get connection +- POST `/connections` - Create connection +- PUT `/connections/{id}` - Update connection +- DELETE `/connections/{id}` - Delete connection +- PUT `/connections/{id}/enable` - Enable connection +- PUT `/connections/{id}/disable` - Disable connection +- PUT `/connections/{id}/pause` - Pause connection +- PUT `/connections/{id}/unpause` - Unpause connection + +**Key Features:** +- Link sources to destinations +- Rule configuration (retry, filter, transform, delay, deduplicate) +- Connection status management +- Full name display (source -> destination) + +#### Task 2.4: Implement Transformation Management +**Files to create:** +- `pkg/cmd/transformation.go` - Main transformation command group +- `pkg/cmd/transformation_list.go` +- `pkg/cmd/transformation_get.go` +- `pkg/cmd/transformation_create.go` +- `pkg/cmd/transformation_update.go` +- `pkg/cmd/transformation_delete.go` +- `pkg/cmd/transformation_test.go` - Test transformation code +- `pkg/transformation/transformation.go` +- `pkg/hookdeck/transformations.go` + +**API Endpoints:** +- GET `/transformations` - List transformations +- GET `/transformations/{id}` - Get transformation +- POST `/transformations` - Create transformation +- PUT `/transformations/{id}` - Update transformation +- DELETE `/transformations/{id}` - Delete transformation +- PUT `/transformations/run` - Test transformation + +**Key Features:** +- JavaScript code management +- Environment variable configuration +- Code testing and validation +- Execution history viewing + +### Phase 3: Advanced Features and Integration + +#### Task 3.1: Add Interactive Creation Wizards +**Files to modify:** +- All `*_create.go` files + +**Features:** +- Interactive prompts for resource creation +- Type-specific guidance and validation +- Template-based code generation for transformations +- Smart defaults based on existing resources + +#### Task 3.2: Implement Resource Relationships +**Files to create:** +- `pkg/cmd/connection_wizard.go` - Guided connection creation + +**Features:** +- Show source/destination relationships +- Validate connections before creation +- Suggest optimal configurations +- Display dependency chains + +#### Task 3.3: Add Bulk Operations +**Files to create:** +- `pkg/cmd/bulk.go` - Bulk operation commands +- `pkg/cmd/bulk_enable.go` +- `pkg/cmd/bulk_disable.go` +- `pkg/cmd/bulk_delete.go` + +**Features:** +- Bulk enable/disable resources +- Batch operations with confirmation +- Progress indicators for large operations +- Rollback capabilities + +### Phase 4: Documentation and Examples + +#### Task 4.1: Create Reference Documentation +**Files to create:** +- `REFERENCE.md` - Comprehensive CLI reference + +**Content Structure:** +```markdown +# Hookdeck CLI Reference + +## Projects +### Create a project +### List projects +### Update project settings +### Delete a project + +## Sources +### Create webhook sources +### Configure source authentication +### Manage source types +### List and filter sources + +## Destinations +### Create HTTP destinations +### Configure authentication +### Set up rate limiting +### Manage destination types + +## Connections +### Link sources to destinations +### Configure retry rules +### Set up transformations +### Manage connection lifecycle + +## Transformations +### Write JavaScript transformations +### Test transformation code +### Manage environment variables +### View execution history + +## Advanced Usage +### Bulk operations +### Resource relationships +### Configuration management +### Troubleshooting +``` + +#### Task 4.2: Add Command Examples +**Files to modify:** +- All command files - Add comprehensive examples to help text + +**Example patterns:** +```go +cmd.Example = ` # List all sources + hookdeck source list + + # Create a Stripe source + hookdeck source create --name stripe-prod --type STRIPE + + # Create an HTTP destination + hookdeck destination create --name api-endpoint --url https://api.example.com/webhooks + + # Connect source to destination + hookdeck connection create --source stripe-prod --destination api-endpoint --name stripe-to-api` +``` + +### Phase 5: Testing and Validation + +#### Task 5.1: Add Command Tests +**Files to create:** +- `pkg/cmd/*_test.go` - Unit tests for all commands +- `test/integration/` - Integration test suite + +#### Task 5.2: Add API Client Tests +**Files to create:** +- `pkg/hookdeck/*_test.go` - API client tests +- Mock API responses for testing + +#### Task 5.3: Create CLI Acceptance Tests +**Files to create:** +- `test/acceptance/` - End-to-end CLI tests +- Test scenarios for complete workflows + +--- + +## Implementation Architecture + +### Command Structure +``` +hookdeck +├── project +│ ├── list +│ ├── create +│ ├── update +│ └── delete +├── source +│ ├── list +│ ├── get +│ ├── create +│ ├── update +│ ├── delete +│ ├── enable +│ └── disable +├── destination +│ ├── list +│ ├── get +│ ├── create +│ ├── update +│ ├── delete +│ ├── enable +│ └── disable +├── connection +│ ├── list +│ ├── get +│ ├── create +│ ├── update +│ ├── delete +│ ├── enable +│ ├── disable +│ ├── pause +│ └── unpause +└── transformation + ├── list + ├── get + ├── create + ├── update + ├── delete + └── test +``` + +### Data Flow +```mermaid +graph TD + A[CLI Command] --> B[Validation Layer] + B --> C[API Client] + C --> D[Hookdeck API] + D --> E[Response Processing] + E --> F[Output Formatting] + F --> G[User Display] +``` + +### Error Handling Strategy +1. **Input Validation** - Validate arguments and flags before API calls +2. **API Error Mapping** - Transform API errors into user-friendly messages +3. **Retry Logic** - Implement exponential backoff for transient failures +4. **Graceful Degradation** - Provide fallback options when possible + +### Configuration Management +1. **Profile Support** - Multiple API key/project configurations +2. **Environment Variables** - Support for CI/CD environments +3. **Config File** - TOML-based configuration with validation +4. **Command Overrides** - Allow per-command configuration + +This comprehensive plan provides a roadmap for implementing full resource management in the Hookdeck CLI while maintaining consistency with existing patterns and ensuring a great developer experience. \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..bfee3cb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,313 @@ +# AGENTS Guidelines for Hookdeck CLI + +This repository contains the Hookdeck CLI, a Go-based command-line tool for managing webhook infrastructure. When working with this codebase, please follow these guidelines to maintain consistency and ensure proper functionality. + +## 1. Project Structure & Navigation + +### Core Directories +- `pkg/cmd/` - All CLI commands (Cobra-based) +- `pkg/hookdeck/` - API client and models +- `pkg/config/` - Configuration management +- `pkg/listen/` - Local webhook forwarding functionality +- `cmd/hookdeck/` - Main entry point +- `REFERENCE.md` - Complete CLI documentation and examples + +### Key Files +- `https://api.hookdeck.com/2025-07-01/openapi` - API specification (source of truth for all API interactions) +- `.plans/` - Implementation plans and architectural decisions +- `AGENTS.md` - This file (guidelines for AI agents) + +## 2. OpenAPI to CLI Conversion Standards + +When adding new CLI commands that interact with the Hookdeck API, follow these conversion patterns: + +### Parameter Mapping Rules +```bash +# Nested JSON objects → Flat CLI flags +API: { "configs": { "strategy": "final_attempt" } } +CLI: --strategy final_attempt + +# Arrays → Comma-separated values +API: { "connections": ["conn_1", "conn_2"] } +CLI: --connections "conn_1,conn_2" + +# Boolean presence → Presence flags +API: { "channels": { "email": {} } } +CLI: --email + +# Complex objects with values → Value flags +API: { "channels": { "slack": { "channel_name": "#alerts" } } } +CLI: --slack-channel "#alerts" +``` + +### Flag Naming Conventions +- **Resource identifiers**: Always `--name` for human-readable names +- **Type parameters**: + - **Individual resource commands**: Use `--type` (clear context) + - Sources: `hookdeck source create --type STRIPE` + - Destinations: `hookdeck destination create --type HTTP` + - Issue Triggers: `hookdeck issue-trigger create --type delivery` + - **Connection creation**: Use prefixed flags to avoid ambiguity when creating inline resources + - `--source-type STRIPE` when creating source inline + - `--destination-type HTTP` when creating destination inline + - This prevents confusion between source and destination types in single command +- **Authentication**: Standard patterns (`--api-key`, `--webhook-secret`, `--basic-auth`) + - **Connection creation**: Use prefixed authentication to avoid collisions + - `--source-webhook-secret` for source authentication + - `--destination-api-key` for destination authentication +- **Collections**: Use comma-separated values (`--connections "a,b,c"`) +- **Booleans**: Use presence flags (`--email`, `--pagerduty`, `--force`) + +### Command Structure Standards +```bash +# Standard CRUD pattern +hookdeck [resource-id] [flags] + +# Examples + +# Individual resource creation (clear context) +hookdeck source create --type STRIPE --webhook-secret abc123 +hookdeck destination create --type HTTP --url https://api.example.com + +# Connection creation with inline resources (requires prefixed flags) +hookdeck connection create \ + --source-type STRIPE --source-name "stripe-prod" \ + --source-webhook-secret "whsec_abc123" \ + --destination-type HTTP --destination-name "my-api" \ + --destination-url "https://api.example.com/webhooks" +``` + +## 3. Conditional Validation Implementation + +When `--type` parameters control other valid parameters, implement progressive validation: + +### Type-Driven Validation Pattern +```go +func validateResourceFlags(flags map[string]interface{}) error { + // Handle different validation scenarios based on command context + + // Individual resource creation (use --type) + if resourceType, ok := flags["type"].(string); ok { + return validateSingleResourceType(resourceType, flags) + } + + // Connection creation with inline resources (use prefixed flags) + if sourceType, ok := flags["source_type"].(string); ok { + if err := validateSourceType(sourceType, flags); err != nil { + return err + } + } + if destType, ok := flags["destination_type"].(string); ok { + if err := validateDestinationType(destType, flags); err != nil { + return err + } + } + + return nil +} + +func validateTypeA(flags map[string]interface{}) error { + // Type-specific required/forbidden parameter validation + if flags["required_param"] == nil { + return errors.New("--required-param is required for TYPE_A") + } + if flags["forbidden_param"] != nil { + return errors.New("--forbidden-param is not supported for TYPE_A") + } + return nil +} +``` + +### Validation Layers (in order) +1. **Flag parsing validation** - Ensure flag values are correctly typed +2. **Type-specific validation** - Validate based on `--type` parameter +3. **Cross-parameter validation** - Check relationships between parameters +4. **API schema validation** - Final validation against OpenAPI constraints + +### Help System Integration +Provide dynamic help text based on selected type: +```go +func getTypeSpecificHelp(command, selectedType string) string { + // Return contextual help for the specific type + // Show only relevant flags and their requirements +} +``` + +## 4. Code Organization Patterns + +### Command File Structure +Each resource follows this pattern: +``` +pkg/cmd/ +├── resource.go # Main command group +├── resource_list.go # List resources with filtering +├── resource_get.go # Get single resource details +├── resource_create.go # Create new resources (with type validation) +├── resource_update.go # Update existing resources +├── resource_delete.go # Delete resources +└── resource_enable.go # Enable/disable operations (if applicable) +``` + +### API Client Pattern +``` +pkg/hookdeck/ +├── client.go # Base HTTP client +├── resources.go # Resource-specific API methods +└── models.go # API response models +``` + +## 5. Development Workflow + +### Building and Testing +```bash +# Build the CLI +go build -o hookdeck cmd/hookdeck/main.go + +# Run tests +go test ./... + +# Run specific package tests +go test ./pkg/cmd/ + +# Run with race detection +go test -race ./... +``` + +### Linting and Formatting +```bash +# Format code +go fmt ./... + +# Run linter (if available) +golangci-lint run + +# Vet code +go vet ./... +``` + +### Local Development +```bash +# Run CLI directly during development +go run cmd/hookdeck/main.go + +# Example: Test login command +go run cmd/hookdeck/main.go login --help +``` + +## 6. Documentation Standards + +### CLI Documentation +- **REFERENCE.md**: Must include all commands with examples +- Use status indicators: ✅ Current vs 🚧 Planned +- Include realistic examples with actual API responses +- Document all flag combinations and their validation rules + +### Code Documentation +- Document exported functions and types +- Include usage examples for complex functions +- Explain validation logic and type relationships +- Comment on OpenAPI schema mappings where non-obvious + +## 7. Error Handling Patterns + +### CLI Error Messages +```go +// Good: Specific, actionable error messages +return errors.New("--webhook-secret is required for Stripe sources") + +// Good: Suggest alternatives +return fmt.Errorf("unsupported source type: %s. Supported types: STRIPE, GITHUB, HTTP", sourceType) + +// Avoid: Generic or unclear messages +return errors.New("invalid configuration") +``` + +### API Error Handling +```go +// Handle API errors gracefully +if apiErr, ok := err.(*hookdeck.APIError); ok { + if apiErr.StatusCode == 400 { + return fmt.Errorf("invalid request: %s", apiErr.Message) + } +} +``` + +## 8. Dependencies and External Libraries + +### Core Dependencies +- **Cobra**: CLI framework - follow existing patterns +- **Viper**: Configuration management +- **Go standard library**: Prefer over external dependencies when possible + +### Adding New Dependencies +1. Evaluate if functionality exists in current dependencies +2. Prefer well-maintained, standard libraries +3. Update `go.mod` and commit changes +4. Document new dependency usage patterns + +## 9. Testing Guidelines + +### Unit Testing +- Test validation logic thoroughly +- Mock API calls for command tests +- Test error conditions and edge cases +- Include examples of valid/invalid flag combinations + +### Integration Testing +- Test actual API interactions in isolated tests +- Use test fixtures for complex API responses +- Validate command output formats + +## 10. Useful Commands Reference + +| Command | Purpose | +|---------|---------| +| `go run cmd/hookdeck/main.go --help` | View CLI help | +| `go build -o hookdeck cmd/hookdeck/main.go` | Build CLI binary | +| `go test ./pkg/cmd/` | Test command implementations | +| `go generate ./...` | Run code generation (if used) | +| `golangci-lint run` | Run comprehensive linting | + +## 11. Common Patterns to Follow + +### Interactive Prompts +When required parameters are missing, prompt interactively: +```go +if flags.Type == "" { + // Show available types and prompt for selection + selectedType, err := promptForType() + if err != nil { + return err + } + flags.Type = selectedType +} +``` + +### Resource Reference Handling +```go +// Accept both names and IDs +func resolveResourceID(nameOrID string) (string, error) { + // Try as ID first, then lookup by name + if isValidID(nameOrID) { + return nameOrID, nil + } + return lookupByName(nameOrID) +} +``` + +### Output Formatting +```go +// Support multiple output formats (when --format is implemented) +switch outputFormat { +case "json": + return printJSON(resource) +case "yaml": + return printYAML(resource) +default: + return printTable(resource) +} +``` + +--- + +Following these guidelines ensures consistent, maintainable CLI commands that provide an excellent user experience while maintaining architectural consistency with the existing codebase. \ No newline at end of file diff --git a/REFERENCE.md b/REFERENCE.md new file mode 100644 index 0000000..2b201b7 --- /dev/null +++ b/REFERENCE.md @@ -0,0 +1,2047 @@ +# Hookdeck CLI Reference + +The Hookdeck CLI provides comprehensive webhook infrastructure management including authentication, project management, resource management, event and attempt querying, and local development tools. This reference covers all available commands and their usage. + +## Table of Contents + +### Current Functionality ✅ +- [Global Options](#global-options) +- [Authentication](#authentication) +- [Projects](#projects) (list and use only) +- [Local Development](#local-development) +- [CI/CD Integration](#cicd-integration) +- [Utilities](#utilities) +- [Current Limitations](#current-limitations) + +### Planned Functionality 🚧 +- [Advanced Project Management](#advanced-project-management) +- [Sources](#sources) +- [Destinations](#destinations) +- [Connections](#connections) +- [Transformations](#transformations) +- [Events](#events) +- [Issue Triggers](#issue-triggers) +- [Attempts](#attempts) +- [Bookmarks](#bookmarks) +- [Integrations](#integrations) +- [Issues](#issues) +- [Requests](#requests) +- [Bulk Operations](#bulk-operations) +- [Notifications](#notifications) +- [Implementation Status](#implementation-status) + +## Global Options + +All commands support these global options: + +### ✅ Current Global Options +```bash +--profile, -p string Profile name (default "default") +--api-key string Your API key to use for the command (hidden) +--cli-key string CLI key for legacy auth (deprecated, hidden) +--color string Turn on/off color output (on, off, auto) +--config string Config file (default is $HOME/.config/hookdeck/config.toml) +--device-name string Device name for this CLI instance +--log-level string Log level: debug, info, warn, error (default "info") +--insecure Allow invalid TLS certificates +--version, -v Show version information +--help, -h Show help information +``` + +### 🚧 Planned Global Options +```bash +--project string Project ID to use (overrides profile) +--format string Output format: table, json, yaml (default "table") +``` + +## Authentication + +**All Parameters:** +```bash +# Login command parameters +--api-key string API key for direct authentication +--interactive, -i Interactive login with prompts (boolean flag) +--profile string Profile name to use for login + +# Logout command parameters +--all, -a Logout all profiles (boolean flag) +--profile string Profile name to logout + +# Whoami command parameters +# (No additional parameters - uses global options only) +``` + +### ✅ Login +```bash +# Interactive login with prompts +hookdeck login +hookdeck login --interactive +hookdeck login -i + +# Login with API key directly +hookdeck login --api-key your_api_key + +# Use different profile +hookdeck login --profile production +``` + +### ✅ Logout +```bash +# Logout current profile +hookdeck logout + +# Logout specific profile +hookdeck logout --profile production + +# Logout all profiles +hookdeck logout --all +hookdeck logout -a +``` + +### ✅ Check authentication status +```bash +hookdeck whoami + +# Example output: +# Using profile default (use -p flag to use a different config profile) +# +# Logged in as john@example.com (John Doe) on project Production in organization Acme Corp +``` + +## Projects + +**All Parameters:** +```bash +# Project list command parameters +[organization_substring] [project_substring] # Positional arguments for filtering +# (No additional flag parameters) + +# Project use command parameters +[project-id] # Positional argument for specific project ID +--profile string # Profile name to use + +# Project create command parameters (planned) +--name string # Required: Project name +--description string # Optional: Project description + +# Project get command parameters (planned) +[project-id] # Positional argument for specific project ID + +# Project update command parameters (planned) + # Required positional argument for project ID +--name string # Update project name +--description string # Update project description + +# Project delete command parameters (planned) + # Required positional argument for project ID +--force # Force delete without confirmation (boolean flag) +``` + +Projects are top-level containers for your webhook infrastructure. + +### ✅ List projects +```bash +# List all projects you have access to +hookdeck project list + +# Filter by organization substring +hookdeck project list acme + +# Filter by organization and project substrings +hookdeck project list acme production + +# Example output: +# [Acme Corp] Production +# [Acme Corp] Staging (current) +# [Test Org] Development +``` + +### ✅ Use project (set as current) +```bash +# Interactive selection from available projects +hookdeck project use + +# Use specific project by ID +hookdeck project use proj_123 + +# Use with different profile +hookdeck project use --profile production +``` + +## Local Development + +**All Parameters:** +```bash +# Listen command parameters +[port or URL] # Required positional argument (e.g., "3000" or "http://localhost:3000") +[source] # Optional positional argument for source name +[connection] # Optional positional argument for connection name +--path string # Specific path to forward to (e.g., "/webhooks") +--no-wss # Force unencrypted WebSocket connection (hidden flag) +``` + +### ✅ Listen for webhooks +```bash +# Start webhook forwarding to localhost (with interactive prompts) +hookdeck listen + +# Forward to specific port +hookdeck listen 3000 + +# Forward to specific URL +hookdeck listen http://localhost:3000 + +# Forward with source and connection specified +hookdeck listen 3000 stripe-webhooks payment-connection + +# Forward to specific path +hookdeck listen --path /webhooks + +# Force unencrypted WebSocket connection (hidden flag) +hookdeck listen --no-wss + +# Arguments: +# - port or URL: Required (e.g., "3000" or "http://localhost:3000") +# - source: Optional source name to forward from +# - connection: Optional connection name +``` + +The `listen` command forwards webhooks from Hookdeck to your local development server, allowing you to test webhook integrations locally. + +## CI/CD Integration + +**All Parameters:** +```bash +# CI command parameters +--api-key string # API key (defaults to HOOKDECK_API_KEY env var) +--name string # CI name (e.g., $GITHUB_REF for GitHub Actions) +``` + +### ✅ CI command +```bash +# Run in CI/CD environments +hookdeck ci + +# Specify API key explicitly (defaults to HOOKDECK_API_KEY env var) +hookdeck ci --api-key + +# Specify CI name (e.g., for GitHub Actions) +hookdeck ci --name $GITHUB_REF +``` + +This command provides CI/CD specific functionality for automated deployments and testing. + +## Utilities + +**All Parameters:** +```bash +# Completion command parameters +[shell] # Positional argument for shell type (bash, zsh, fish, powershell) +--shell string # Explicit shell selection flag + +# Version command parameters +# (No additional parameters - uses global options only) +``` + +### ✅ Shell completion +```bash +# Generate completion for bash +hookdeck completion bash + +# Generate completion for zsh +hookdeck completion zsh + +# Generate completion for fish +hookdeck completion fish + +# Generate completion for PowerShell +hookdeck completion powershell + +# Specify shell explicitly +hookdeck completion --shell bash +``` + +### ✅ Version information +```bash +hookdeck version + +# Short version +hookdeck --version +``` + +## Current Limitations + +The Hookdeck CLI is currently focused on authentication, basic project management, and local development. The following functionality is planned but not yet implemented: + +- ❌ **No structured output formats** - Only plain text with ANSI colors +- ❌ **No `--format` flag** - Cannot output JSON, YAML, or tables +- ❌ **No resource management** - Cannot manage sources, destinations, or connections +- ❌ **No transformation management** - Cannot create or manage JavaScript transformations +- ❌ **No event querying** - Cannot view or retry webhook events +- ❌ **No bulk operations** - Cannot perform batch operations on resources +- ❌ **No advanced filtering** - Limited query capabilities +- ❌ **No project creation** - Cannot create, update, or delete projects via CLI + +--- + +# 🚧 Planned Functionality + +*The following sections document planned functionality that is not yet implemented. This serves as a specification for future development.* + +## Implementation Status + +| Command Category | Status | Available Commands | Planned Commands | +|------------------|--------|-------------------|------------------| +| Authentication | ✅ **Current** | `login`, `logout`, `whoami` | *None needed* | +| Project Management | 🔄 **Partial** | `list`, `use` | `create`, `get`, `update`, `delete` | +| Local Development | ✅ **Current** | `listen` | *Enhancements planned* | +| CI/CD | ✅ **Current** | `ci` | *Enhancements planned* | +| Source Management | 🚧 **Planned** | *None* | Full CRUD + 80+ provider types | +| Destination Management | 🚧 **Planned** | *None* | Full CRUD + auth types | +| Connection Management | 🚧 **Planned** | *None* | Full CRUD + lifecycle management | +| Transformation Management | 🚧 **Planned** | *None* | Full CRUD + execution + testing | +| Event Querying | 🚧 **Planned** | *None* | List, get, retry, search | +| Issue Trigger Management | 🚧 **Planned** | *None* | Full CRUD + notification channels | +| Attempt Management | 🚧 **Planned** | *None* | List, get, retry, filter, analyze | +| Bookmark Management | 🚧 **Planned** | *None* | Full CRUD + trigger/replay | +| Integration Management | 🚧 **Planned** | *None* | Full CRUD + attach/detach | +| Issue Management | 🚧 **Planned** | *None* | List, get, update, dismiss | +| Request Management | 🚧 **Planned** | *None* | List, get, retry, raw access | +| Bulk Operations | 🚧 **Planned** | *None* | Bulk retry for events/requests/ignored | +| Notifications | 🚧 **Planned** | *None* | Webhook notifications | +| Output Formatting | 🚧 **Planned** | Basic text only | JSON, YAML, table, CSV | + +## Advanced Project Management + +🚧 **PLANNED FUNCTIONALITY** - Not yet implemented + +*Note: These project management commands are planned for implementation as documented in `.plans/resource-management-implementation.md` and are being developed in the `feat/project-create` branch.* + +### Create a project +```bash +# Create with interactive prompts +hookdeck project create + +# Create with flags +hookdeck project create --name "My Project" --description "Production webhooks" +``` + +### Get project details +```bash +# Get current project +hookdeck project get + +# Get specific project +hookdeck project get proj_123 + +# Get with full details +hookdeck project get proj_123 --log-level debug +``` + +### Update project +```bash +# Update interactively +hookdeck project update + +# Update specific project +hookdeck project update proj_123 --name "Updated Name" + +# Update description +hookdeck project update proj_123 --description "New description" +``` + +### Delete project +```bash +# Delete with confirmation +hookdeck project delete proj_123 + +# Force delete without confirmation +hookdeck project delete proj_123 --force +``` + +## Sources + +**All Parameters:** +```bash +# Source list command parameters +--name string # Filter by name pattern (supports wildcards) +--type string # Filter by source type (96+ types supported) +--disabled # Include disabled sources (boolean flag) +--order-by string # Sort by: name, created_at, updated_at +--dir string # Sort direction: asc, desc +--limit integer # Limit number of results (0-255) +--next string # Next page token for pagination +--prev string # Previous page token for pagination + +# Source count command parameters +--name string # Filter by name pattern +--disabled # Include disabled sources (boolean flag) + +# Source get command parameters + # Required positional argument for source ID +--include string # Include additional data (e.g., "config.auth") + +# Source create command parameters +--name string # Required: Source name +--type string # Required: Source type (see type-specific parameters below) +--description string # Optional: Source description + +# Type-specific parameters for source create/update/upsert: +# When --type=STRIPE, GITHUB, SHOPIFY, SLACK, TWILIO, etc.: +--webhook-secret string # Webhook secret for signature verification + +# When --type=PAYPAL: +--webhook-id string # PayPal webhook ID (not webhook_secret) + +# When --type=GITLAB, OKTA, MERAKI, etc.: +--api-key string # API key for authentication + +# When --type=BRIDGE, FIREBLOCKS, DISCORD, TELNYX, etc.: +--public-key string # Public key for signature verification + +# When --type=POSTMARK, PIPEDRIVE, etc.: +--username string # Username for basic authentication +--password string # Password for basic authentication + +# When --type=RING_CENTRAL, etc.: +--token string # Authentication token + +# When --type=EBAY (complex multi-field authentication): +--environment string # PRODUCTION or SANDBOX +--dev-id string # Developer ID +--client-id string # Client ID +--client-secret string # Client secret +--verification-token string # Verification token + +# When --type=TIKTOK_SHOP (multi-key authentication): +--webhook-secret string # Webhook secret +--app-key string # Application key + +# When --type=FISERV: +--webhook-secret string # Webhook secret +--store-name string # Optional: Store name + +# When --type=VERCEL_LOG_DRAINS: +--webhook-secret string # Webhook secret +--log-drains-secret string # Optional: Log drains secret + +# When --type=HTTP (custom HTTP source): +--auth-type string # Authentication type (HMAC, API_KEY, BASIC, etc.) +--algorithm string # HMAC algorithm (sha256, sha1, etc.) +--encoding string # HMAC encoding (hex, base64, etc.) +--header-key string # Header name for signature/API key +--webhook-secret string # Secret for HMAC verification +--auth-key string # API key for API_KEY auth type +--auth-username string # Username for BASIC auth type +--auth-password string # Password for BASIC auth type +--allowed-methods string # Comma-separated HTTP methods (GET,POST,PUT,DELETE) +--custom-response-status integer # Custom response status code +--custom-response-body string # Custom response body +--custom-response-headers string # Custom response headers (key=value,key2=value2) + +# Source update command parameters + # Required positional argument for source ID +--name string # Update source name +--description string # Update source description +# Plus any type-specific parameters listed above + +# Source upsert command parameters (create or update by name) +--name string # Required: Source name (used for matching existing) +--type string # Required: Source type +# Plus any type-specific parameters listed above + +# Source delete command parameters + # Required positional argument for source ID +--force # Force delete without confirmation (boolean flag) + +# Source enable/disable/archive/unarchive command parameters + # Required positional argument for source ID +``` + +**Type Validation Rules:** +- **webhook_secret_key types**: STRIPE, GITHUB, SHOPIFY, SLACK, TWILIO, SQUARE, WOOCOMMERCE, TEBEX, MAILCHIMP, PADDLE, TREEZOR, PRAXIS, CUSTOMERIO, EXACT_ONLINE, FACEBOOK, WHATSAPP, REPLICATE, TIKTOK, FISERV, VERCEL_LOG_DRAINS, etc. +- **webhook_id types**: PAYPAL (uses webhook_id instead of webhook_secret) +- **api_key types**: GITLAB, OKTA, MERAKI, CLOUDSIGNAL, etc. +- **public_key types**: BRIDGE, FIREBLOCKS, DISCORD, TELNYX, etc. +- **basic_auth types**: POSTMARK, PIPEDRIVE, etc. +- **token types**: RING_CENTRAL, etc. +- **complex_auth types**: EBAY (5 fields), TIKTOK_SHOP (2 fields) +- **minimal_config types**: AWS_SNS (no additional auth required) + +🚧 **PLANNED FUNCTIONALITY** - Not yet implemented + +Sources represent the webhook providers that send webhooks to Hookdeck. The API supports 96+ provider types with specific authentication requirements. + +### List sources +```bash +# List all sources +hookdeck source list + +# Filter by name pattern +hookdeck source list --name "stripe*" + +# Filter by type (supports 80+ types) +hookdeck source list --type STRIPE + +# Include disabled sources +hookdeck source list --disabled + +# Limit results +hookdeck source list --limit 50 + +# Combined filtering +hookdeck source list --name "*prod*" --type GITHUB --limit 25 +``` + +### Count sources +```bash +# Count all sources +hookdeck source count + +# Count with filters +hookdeck source count --name "*stripe*" --disabled +``` + +### Get source details +```bash +# Get source by ID +hookdeck source get + +# Include authentication configuration +hookdeck source get --include config.auth +``` + +### Create a source + +#### Interactive creation +```bash +# Create with interactive prompts +hookdeck source create +``` + +#### Platform-specific sources (80+ supported types) + +##### Payment Platforms +```bash +# Stripe - Payment webhooks +hookdeck source create --name "stripe-prod" --type STRIPE --webhook-secret "whsec_1a2b3c..." + +# PayPal - Payment events (uses webhook_id not webhook_secret) +hookdeck source create --name "paypal-prod" --type PAYPAL --webhook-id "webhook_id_value" + +# Square - POS and payment events +hookdeck source create --name "square-webhooks" --type SQUARE --webhook-secret "webhook_secret" +``` + +##### Repository and CI/CD +```bash +# GitHub - Repository webhooks +hookdeck source create --name "github-repo" --type GITHUB --webhook-secret "github_secret" + +# GitLab - Repository and CI webhooks +hookdeck source create --name "gitlab-project" --type GITLAB --api-key "gitlab_token" + +# Bitbucket - Repository events +hookdeck source create --name "bitbucket-repo" --type BITBUCKET --webhook-secret "webhook_secret" +``` + +##### E-commerce Platforms +```bash +# Shopify - Store webhooks +hookdeck source create --name "shopify-store" --type SHOPIFY --webhook-secret "shopify_secret" + +# WooCommerce - WordPress e-commerce +hookdeck source create --name "woocommerce-store" --type WOOCOMMERCE --webhook-secret "webhook_secret" + +# Magento - Enterprise e-commerce +hookdeck source create --name "magento-store" --type MAGENTO --webhook-secret "webhook_secret" +``` + +##### Communication Platforms +```bash +# Slack - Workspace events +hookdeck source create --name "slack-workspace" --type SLACK --webhook-secret "slack_signing_secret" + +# Twilio - SMS and voice webhooks +hookdeck source create --name "twilio-sms" --type TWILIO --webhook-secret "twilio_auth_token" + +# Discord - Bot interactions +hookdeck source create --name "discord-bot" --type DISCORD --public-key "discord_public_key" + +# Teams - Microsoft Teams webhooks +hookdeck source create --name "teams-notifications" --type TEAMS --webhook-secret "teams_secret" +``` + +##### Cloud Services +```bash +# AWS SNS - Cloud notifications +hookdeck source create --name "aws-sns" --type AWS_SNS + +# Azure Event Grid - Azure events +hookdeck source create --name "azure-events" --type AZURE_EVENT_GRID --webhook-secret "webhook_secret" + +# Google Cloud Pub/Sub - GCP events +hookdeck source create --name "gcp-pubsub" --type GOOGLE_CLOUD_PUBSUB --webhook-secret "webhook_secret" +``` + +##### CRM and Marketing +```bash +# Salesforce - CRM events +hookdeck source create --name "salesforce-crm" --type SALESFORCE --webhook-secret "salesforce_secret" + +# HubSpot - Marketing automation +hookdeck source create --name "hubspot-marketing" --type HUBSPOT --webhook-secret "hubspot_secret" + +# Mailchimp - Email marketing +hookdeck source create --name "mailchimp-campaigns" --type MAILCHIMP --webhook-secret "mailchimp_secret" +``` + +##### Authentication and Identity +```bash +# Auth0 - Identity events +hookdeck source create --name "auth0-identity" --type AUTH0 --webhook-secret "auth0_secret" + +# Okta - Identity management +hookdeck source create --name "okta-identity" --type OKTA --api-key "okta_api_key" + +# Firebase Auth - Authentication events +hookdeck source create --name "firebase-auth" --type FIREBASE_AUTH --webhook-secret "firebase_secret" +``` + +##### Complex Authentication Examples +```bash +# eBay - Multi-field authentication +hookdeck source create --name "ebay-marketplace" --type EBAY \ + --environment PRODUCTION \ + --dev-id "dev_id" \ + --client-id "client_id" \ + --client-secret "client_secret" \ + --verification-token "verification_token" + +# TikTok Shop - Multi-key authentication +hookdeck source create --name "tiktok-shop" --type TIKTOK_SHOP \ + --webhook-secret "webhook_secret" \ + --app-key "app_key" + +# Custom HTTP with HMAC authentication +hookdeck source create --name "custom-api" --type HTTP \ + --auth-type HMAC \ + --algorithm sha256 \ + --encoding hex \ + --header-key "X-Signature" \ + --webhook-secret "hmac_secret" +``` + +### Update a source +```bash +# Update name and description +hookdeck source update --name "new-name" --description "Updated description" + +# Update webhook secret +hookdeck source update --webhook-secret "new_secret" + +# Update type-specific configuration +hookdeck source update --api-key "new_api_key" +``` + +### Upsert a source (create or update by name) +```bash +# Create or update source by name +hookdeck source upsert --name "stripe-prod" --type STRIPE --webhook-secret "new_secret" +``` + +### Delete a source +```bash +# Delete source (with confirmation) +hookdeck source delete + +# Force delete without confirmation +hookdeck source delete --force +``` + +### Enable/Disable sources +```bash +# Enable source +hookdeck source enable + +# Disable source +hookdeck source disable + +# Archive source +hookdeck source archive + +# Unarchive source +hookdeck source unarchive +``` + +## Destinations + +**All Parameters:** +```bash +# Destination list command parameters +--name string # Filter by name pattern (supports wildcards) +--type string # Filter by destination type (HTTP, CLI, MOCK_API) +--disabled # Include disabled destinations (boolean flag) +--limit integer # Limit number of results (default varies) + +# Destination count command parameters +--name string # Filter by name pattern +--disabled # Include disabled destinations (boolean flag) + +# Destination get command parameters + # Required positional argument for destination ID +--include string # Include additional data (e.g., "config.auth") + +# Destination create command parameters +--name string # Required: Destination name +--type string # Optional: Destination type (HTTP, CLI, MOCK_API) - defaults to HTTP +--description string # Optional: Destination description + +# Type-specific parameters for destination create/update/upsert: +# When --type=HTTP (default): +--url string # Required: Destination URL +--auth-type string # Authentication type (BEARER_TOKEN, BASIC_AUTH, API_KEY, OAUTH2_CLIENT_CREDENTIALS) +--auth-token string # Bearer token for BEARER_TOKEN auth +--auth-username string # Username for BASIC_AUTH +--auth-password string # Password for BASIC_AUTH +--auth-key string # API key for API_KEY auth +--auth-header string # Header name for API_KEY auth (e.g., "X-API-Key") +--auth-server string # OAuth2 token server URL for OAUTH2_CLIENT_CREDENTIALS +--client-id string # OAuth2 client ID +--client-secret string # OAuth2 client secret +--headers string # Custom headers (key=value,key2=value2) + +# When --type=CLI: +--path string # Optional: Path for CLI destination + +# When --type=MOCK_API: +# (No additional type-specific parameters required) + +# Destination update command parameters + # Required positional argument for destination ID +--name string # Update destination name +--description string # Update destination description +--url string # Update destination URL (for HTTP type) +# Plus any type-specific auth parameters listed above + +# Destination upsert command parameters (create or update by name) +--name string # Required: Destination name (used for matching existing) +--type string # Optional: Destination type +# Plus any type-specific parameters listed above + +# Destination delete command parameters + # Required positional argument for destination ID +--force # Force delete without confirmation (boolean flag) + +# Destination enable/disable/archive/unarchive command parameters + # Required positional argument for destination ID +``` + +**Type Validation Rules:** +- **HTTP destinations**: Require `--url`, support all authentication types +- **CLI destinations**: No URL required, optional `--path` parameter +- **MOCK_API destinations**: No additional parameters required, used for testing + +**Authentication Type Combinations:** +- **BEARER_TOKEN**: Requires `--auth-token` +- **BASIC_AUTH**: Requires `--auth-username` and `--auth-password` +- **API_KEY**: Requires `--auth-key` and `--auth-header` +- **OAUTH2_CLIENT_CREDENTIALS**: Requires `--auth-server`, `--client-id`, and `--client-secret` + +🚧 **PLANNED FUNCTIONALITY** - Not yet implemented + +Destinations are the endpoints where webhooks are delivered. + +### List destinations +```bash +# List all destinations +hookdeck destination list + +# Filter by name pattern +hookdeck destination list --name "api*" + +# Filter by type +hookdeck destination list --type HTTP + +# Include disabled destinations +hookdeck destination list --disabled + +# Limit results +hookdeck destination list --limit 50 +``` + +### Count destinations +```bash +# Count all destinations +hookdeck destination count + +# Count with filters +hookdeck destination count --name "*prod*" --disabled +``` + +### Get destination details +```bash +# Get destination by ID +hookdeck destination get + +# Include authentication configuration +hookdeck destination get --include config.auth +``` + +### Create a destination +```bash +# Create with interactive prompts +hookdeck destination create + +# HTTP destination with URL +hookdeck destination create --name "my-api" --type HTTP --url "https://api.example.com/webhooks" + +# CLI destination for local development +hookdeck destination create --name "local-dev" --type CLI + +# Mock API destination for testing +hookdeck destination create --name "test-mock" --type MOCK_API + +# HTTP with bearer token authentication +hookdeck destination create --name "secure-api" --type HTTP \ + --url "https://api.example.com/webhooks" \ + --auth-type BEARER_TOKEN \ + --auth-token "your_token" + +# HTTP with basic authentication +hookdeck destination create --name "basic-auth-api" --type HTTP \ + --url "https://api.example.com/webhooks" \ + --auth-type BASIC_AUTH \ + --auth-username "api_user" \ + --auth-password "secure_password" + +# HTTP with API key authentication +hookdeck destination create --name "api-key-endpoint" --type HTTP \ + --url "https://api.example.com/webhooks" \ + --auth-type API_KEY \ + --auth-key "your_api_key" \ + --auth-header "X-API-Key" + +# HTTP with custom headers +hookdeck destination create --name "custom-headers-api" --type HTTP \ + --url "https://api.example.com/webhooks" \ + --headers "Content-Type=application/json,X-Custom-Header=value" + +# HTTP with OAuth2 client credentials +hookdeck destination create --name "oauth2-api" --type HTTP \ + --url "https://api.example.com/webhooks" \ + --auth-type OAUTH2_CLIENT_CREDENTIALS \ + --auth-server "https://auth.example.com/token" \ + --client-id "your_client_id" \ + --client-secret "your_client_secret" +``` + +### Update a destination +```bash +# Update name and URL +hookdeck destination update --name "new-name" --url "https://new-api.example.com" + +# Update authentication +hookdeck destination update --auth-token "new_token" +``` + +### Upsert a destination (create or update by name) +```bash +# Create or update destination by name +hookdeck destination upsert --name "my-api" --type HTTP --url "https://api.example.com" +``` + +### Delete a destination +```bash +# Delete destination (with confirmation) +hookdeck destination delete + +# Force delete without confirmation +hookdeck destination delete --force +``` + +### Enable/Disable destinations +```bash +# Enable destination +hookdeck destination enable + +# Disable destination +hookdeck destination disable + +# Archive destination +hookdeck destination archive + +# Unarchive destination +hookdeck destination unarchive +``` + +## Connections + +**All Parameters:** +```bash +# Connection list command parameters +--name string # Filter by name pattern (supports wildcards) +--source-id string # Filter by source ID +--destination-id string # Filter by destination ID +--disabled # Include disabled connections (boolean flag) +--paused # Include paused connections (boolean flag) +--limit integer # Limit number of results (default varies) + +# Connection count command parameters +--name string # Filter by name pattern +--disabled # Include disabled connections (boolean flag) +--paused # Include paused connections (boolean flag) + +# Connection get command parameters + # Required positional argument for connection ID + +# Connection create command parameters +--name string # Required: Connection name +--description string # Optional: Connection description + +# Option 1: Using existing resources +--source string # Source ID or name (existing resource) +--destination string # Destination ID or name (existing resource) + +# Option 2: Creating inline source (uses prefixed flags to avoid collision) +--source-type string # Source type (STRIPE, GITHUB, etc.) +--source-name string # Source name for inline creation +--source-description string # Source description for inline creation +# Plus source type-specific auth parameters with 'source-' prefix: +--webhook-secret string # For webhook_secret_key source types +--api-key string # For api_key source types (conflicts resolved by context) +--public-key string # For public_key source types +--username string # For basic_auth source types +--password string # For basic_auth source types +--token string # For token source types +# Complex auth parameters for specific source types: +--environment string # EBAY only +--dev-id string # EBAY only +--client-id string # EBAY only (may conflict with destination OAuth2) +--client-secret string # EBAY only (may conflict with destination OAuth2) +--verification-token string # EBAY only +--app-key string # TIKTOK_SHOP only + +# Option 3: Creating inline destination (uses prefixed flags to avoid collision) +--destination-type string # Destination type (HTTP, CLI, MOCK_API) +--destination-name string # Destination name for inline creation +--destination-description string # Destination description for inline creation +--destination-url string # URL for HTTP destinations +# Plus destination auth parameters with 'destination-' prefix: +--destination-auth-type string # Auth type (BEARER_TOKEN, BASIC_AUTH, etc.) +--destination-auth-token string # Bearer token +--destination-auth-username string # Basic auth username +--destination-auth-password string # Basic auth password +--destination-auth-key string # API key +--destination-auth-header string # API key header name +--destination-auth-server string # OAuth2 token server +--destination-client-id string # OAuth2 client ID (avoids collision with source EBAY) +--destination-client-secret string # OAuth2 client secret (avoids collision with source EBAY) +--destination-headers string # Custom headers + +# Advanced connection configuration +--transformation string # Transformation ID or name +--retry-strategy string # Retry strategy (exponential, linear, etc.) +--retry-count integer # Maximum retry attempts +--retry-interval integer # Retry interval in milliseconds +--delay integer # Processing delay in milliseconds +--filter-headers string # Header filters (key=pattern,key2=pattern2) +--filter-body string # Body filters (comma-separated patterns) + +# Connection update command parameters + # Required positional argument for connection ID +--name string # Update connection name +--description string # Update connection description +--source string # Update source reference +--destination string # Update destination reference +--transformation string # Update transformation reference + +# Connection upsert command parameters (create or update by name) +--name string # Required: Connection name (used for matching existing) +# Plus any create parameters listed above + +# Connection delete command parameters + # Required positional argument for connection ID +--force # Force delete without confirmation (boolean flag) + +# Connection lifecycle management command parameters + # Required positional argument for connection ID +# Commands: enable, disable, archive, unarchive, pause, unpause +``` + +**Parameter Collision Resolution:** +When creating connections with inline resources, prefixed flags prevent ambiguity: + +- **Source inline creation**: Uses `--source-type`, source-specific auth params (no prefix needed for most) +- **Destination inline creation**: Uses `--destination-type`, `--destination-auth-*` prefixed auth params +- **OAuth2 collision resolution**: + - Source EBAY: `--client-id`, `--client-secret` + - Destination OAuth2: `--destination-client-id`, `--destination-client-secret` + +**Validation Rules:** +- Must specify either `--source` (existing) OR `--source-type` + `--source-name` (inline) +- Must specify either `--destination` (existing) OR `--destination-type` + `--destination-name` (inline) +- Cannot mix inline and existing for same resource type +- Type-specific parameters validated based on `--source-type` and `--destination-type` values + +🚧 **PLANNED FUNCTIONALITY** - Not yet implemented + +Connections link sources to destinations and define processing rules. The connection create command handles flag collision resolution using prefixed flags when creating inline resources. + +### List connections +```bash +# List all connections +hookdeck connection list + +# Filter by name pattern +hookdeck connection list --name "*prod*" + +# Filter by source ID +hookdeck connection list --source-id + +# Filter by destination ID +hookdeck connection list --destination-id + +# Include disabled connections +hookdeck connection list --disabled + +# Include paused connections +hookdeck connection list --paused + +# Limit results +hookdeck connection list --limit 50 +``` + +### Count connections +```bash +# Count all connections +hookdeck connection count + +# Count with filters +hookdeck connection count --name "*stripe*" --disabled --paused +``` + +### Get connection details +```bash +# Get connection by ID +hookdeck connection get +``` + +### Create a connection + +#### Using existing resources +```bash +# Simple connection with existing resources +hookdeck connection create --name "stripe-to-api" --source --destination + +# With transformation +hookdeck connection create --name "stripe-to-api" \ + --source \ + --destination \ + --transformation +``` + +#### Creating resources inline (using prefixed flags to avoid collision) +```bash +# Create connection with inline source and destination +hookdeck connection create --name "stripe-to-api" \ + --source-type STRIPE \ + --source-name "stripe-prod" \ + --webhook-secret "whsec_abc123" \ + --destination-type HTTP \ + --destination-name "my-api" \ + --destination-url "https://api.example.com/webhooks" + +# Mixed approach: existing source, new destination +hookdeck connection create --name "stripe-to-new-api" \ + --source \ + --destination-type HTTP \ + --destination-name "new-endpoint" \ + --destination-url "https://new-api.example.com/hooks" + +# Mixed approach: new source, existing destination +hookdeck connection create --name "github-to-existing" \ + --source-type GITHUB \ + --source-name "github-repo" \ + --webhook-secret "github_secret_123" \ + --destination +``` + +#### Advanced connection configurations +```bash +# Connection with retry rules +hookdeck connection create --name "reliable-connection" \ + --source \ + --destination \ + --retry-strategy exponential \ + --retry-count 5 \ + --retry-interval 1000 + +# Connection with delay rule +hookdeck connection create --name "delayed-processing" \ + --source \ + --destination \ + --delay 30000 + +# Connection with filtering +hookdeck connection create --name "filtered-webhooks" \ + --source \ + --destination \ + --filter-headers "X-Event-Type=payment.*" \ + --filter-body "type=invoice.payment_succeeded,invoice.payment_failed" +``` + +### Update a connection +```bash +# Update connection properties +hookdeck connection update --name "new-name" --description "Updated description" + +# Update source or destination +hookdeck connection update --source --destination + +# Update transformation +hookdeck connection update --transformation +``` + +### Upsert a connection (create or update by name) +```bash +# Create or update connection by name +hookdeck connection upsert --name "stripe-to-api" --source --destination +``` + +### Delete a connection +```bash +# Delete connection (with confirmation) +hookdeck connection delete + +# Force delete without confirmation +hookdeck connection delete --force +``` + +### Connection lifecycle management +```bash +# Enable connection +hookdeck connection enable + +# Disable connection +hookdeck connection disable + +# Archive connection +hookdeck connection archive + +# Unarchive connection +hookdeck connection unarchive + +# Pause connection (temporary) +hookdeck connection pause + +# Unpause connection +hookdeck connection unpause +``` + +## Transformations + +**All Parameters:** +```bash +# Transformation list command parameters +--name string # Filter by name pattern (supports wildcards) +--limit integer # Limit number of results (default varies) + +# Transformation count command parameters +--name string # Filter by name pattern + +# Transformation get command parameters + # Required positional argument for transformation ID + +# Transformation create command parameters +--name string # Required: Transformation name +--code string # Required: JavaScript code for the transformation +--description string # Optional: Transformation description +--env string # Optional: Environment variables (KEY=value,KEY2=value2) + +# Transformation update command parameters + # Required positional argument for transformation ID +--name string # Update transformation name +--code string # Update JavaScript code +--description string # Update transformation description +--env string # Update environment variables (KEY=value,KEY2=value2) + +# Transformation upsert command parameters (create or update by name) +--name string # Required: Transformation name (used for matching existing) +--code string # Required: JavaScript code +--description string # Optional: Transformation description +--env string # Optional: Environment variables + +# Transformation delete command parameters + # Required positional argument for transformation ID +--force # Force delete without confirmation (boolean flag) + +# Transformation run command parameters (testing) +--code string # Required: JavaScript code to test +--request string # Required: Request JSON for testing + +# Transformation executions command parameters + # Required positional argument for transformation ID +--limit integer # Limit number of execution results + +# Transformation execution command parameters (get single execution) + # Required positional argument for transformation ID + # Required positional argument for execution ID +``` + +**Environment Variables Format:** +- Use comma-separated key=value pairs: `KEY1=value1,KEY2=value2` +- Supports debugging flags: `DEBUG=true,LOG_LEVEL=info` +- Can reference external services: `API_URL=https://api.example.com,API_KEY=secret` + +🚧 **PLANNED FUNCTIONALITY** - Not yet implemented + +Transformations allow you to modify webhook payloads using JavaScript. + +### List transformations +```bash +# List all transformations +hookdeck transformation list + +# Filter by name pattern +hookdeck transformation list --name "*stripe*" + +# Limit results +hookdeck transformation list --limit 50 +``` + +### Count transformations +```bash +# Count all transformations +hookdeck transformation count + +# Count with filters +hookdeck transformation count --name "*formatter*" +``` + +### Get transformation details +```bash +# Get transformation by ID +hookdeck transformation get +``` + +### Create a transformation +```bash +# Create with interactive prompts +hookdeck transformation create + +# Create with inline code +hookdeck transformation create --name "stripe-formatter" \ + --code 'export default function(request) { + request.body.processed_at = new Date().toISOString(); + request.body.webhook_source = "stripe"; + return request; + }' + +# Create with environment variables +hookdeck transformation create --name "api-enricher" \ + --code 'export default function(request) { + const { API_KEY } = process.env; + request.headers["X-API-Key"] = API_KEY; + return request; + }' \ + --env "API_KEY=your_key,DEBUG=true" + +# Create with description +hookdeck transformation create --name "payment-processor" \ + --description "Processes payment webhooks and adds metadata" \ + --code 'export default function(request) { + if (request.body.type?.includes("payment")) { + request.body.category = "payment"; + request.body.priority = "high"; + } + return request; + }' +``` + +### Update a transformation +```bash +# Update transformation code +hookdeck transformation update \ + --code 'export default function(request) { /* updated code */ return request; }' + +# Update name and description +hookdeck transformation update --name "new-name" --description "Updated description" + +# Update environment variables +hookdeck transformation update --env "API_KEY=new_key,DEBUG=false" +``` + +### Upsert a transformation (create or update by name) +```bash +# Create or update transformation by name +hookdeck transformation upsert --name "stripe-formatter" \ + --code 'export default function(request) { return request; }' +``` + +### Delete a transformation +```bash +# Delete transformation (with confirmation) +hookdeck transformation delete + +# Force delete without confirmation +hookdeck transformation delete --force +``` + +### Test a transformation +```bash +# Test with sample request JSON +hookdeck transformation run --code 'export default function(request) { return request; }' \ + --request '{"headers": {"content-type": "application/json"}, "body": {"test": true}}' +``` + +### Get transformation executions +```bash +# List executions for a transformation +hookdeck transformation executions --limit 50 + +# Get specific execution details +hookdeck transformation execution +``` + +## Events + +**All Parameters:** +```bash +# Event list command parameters +--id string # Filter by event IDs (comma-separated) +--status string # Filter by status (SUCCESSFUL, FAILED, PENDING) +--webhook-id string # Filter by webhook ID (connection) +--destination-id string # Filter by destination ID +--source-id string # Filter by source ID +--attempts integer # Filter by number of attempts (minimum: 0) +--response-status integer # Filter by HTTP response status (200-600) +--successful-at string # Filter by success date (ISO date-time) +--created-at string # Filter by creation date (ISO date-time) +--error-code string # Filter by error code +--cli-id string # Filter by CLI ID +--last-attempt-at string # Filter by last attempt date (ISO date-time) +--search-term string # Search in body/headers/path (minimum 3 characters) +--headers string # Header matching (JSON string) +--body string # Body matching (JSON string) +--parsed-query string # Query parameter matching (JSON string) +--path string # Path matching +--order-by string # Sort by: created_at +--dir string # Sort direction: asc, desc +--limit integer # Limit number of results (0-255) +--next string # Next page token for pagination +--prev string # Previous page token for pagination + +# Event get command parameters + # Required positional argument for event ID + +# Event raw-body command parameters + # Required positional argument for event ID + +# Event retry command parameters + # Required positional argument for event ID + +# Event mute command parameters + # Required positional argument for event ID +``` + +🚧 **PLANNED FUNCTIONALITY** - Not yet implemented + +### List events +```bash +# List recent events +hookdeck event list + +# Filter by webhook ID (connection) +hookdeck event list --webhook-id + +# Filter by source ID +hookdeck event list --source-id + +# Filter by destination ID +hookdeck event list --destination-id + +# Filter by status +hookdeck event list --status SUCCESSFUL +hookdeck event list --status FAILED +hookdeck event list --status PENDING + +# Limit results +hookdeck event list --limit 100 + +# Combined filtering +hookdeck event list --webhook-id --status FAILED --limit 50 +``` + +### Get event details +```bash +# Get event by ID +hookdeck event get + +# Get event raw body +hookdeck event raw-body +``` + +### Retry events +```bash +# Retry single event +hookdeck event retry +``` + +### Mute events +```bash +# Mute event (stop retries) +hookdeck event mute +``` + +## Attempts + +**All Parameters:** +```bash +# Attempt list command parameters +--event-id string # Filter by specific event ID +--destination-id string # Filter by destination ID +--status string # Filter by attempt status (FAILED, SUCCESSFUL) +--trigger string # Filter by trigger type (INITIAL, MANUAL, BULK_RETRY, UNPAUSE, AUTOMATIC) +--error-code string # Filter by error code (TIMEOUT, CONNECTION_REFUSED, etc.) +--bulk-retry-id string # Filter by bulk retry operation ID +--successful-at string # Filter by success timestamp (ISO format or operators) +--delivered-at string # Filter by delivery timestamp (ISO format or operators) +--responded-at string # Filter by response timestamp (ISO format or operators) +--order-by string # Sort by field (created_at, delivered_at, responded_at) +--dir string # Sort direction (asc, desc) +--limit integer # Limit number of results (0-255) +--next string # Next page token for pagination +--prev string # Previous page token for pagination + +# Attempt get command parameters + # Required positional argument for attempt ID + +# Attempt retry command parameters + # Required positional argument for attempt ID to retry +--force # Force retry without confirmation (boolean flag) +``` + +🚧 **PLANNED FUNCTIONALITY** - Not yet implemented + +Attempts represent individual delivery attempts for webhook events, including success/failure status, response details, and performance metrics. + +### List attempts +```bash +# List all attempts +hookdeck attempt list + +# List attempts for a specific event +hookdeck attempt list --event-id evt_123 + +# List attempts for a destination +hookdeck attempt list --destination-id dest_456 + +# Filter by status +hookdeck attempt list --status FAILED +hookdeck attempt list --status SUCCESSFUL + +# Filter by trigger type +hookdeck attempt list --trigger MANUAL +hookdeck attempt list --trigger BULK_RETRY + +# Filter by error code +hookdeck attempt list --error-code TIMEOUT +hookdeck attempt list --error-code CONNECTION_REFUSED + +# Filter by bulk retry operation +hookdeck attempt list --bulk-retry-id retry_789 + +# Filter by timestamp (various operators supported) +hookdeck attempt list --delivered-at "2024-01-01T00:00:00Z" +hookdeck attempt list --successful-at ">2024-01-01T00:00:00Z" + +# Sort and limit results +hookdeck attempt list --order-by delivered_at --dir desc --limit 100 + +# Pagination +hookdeck attempt list --limit 50 --next + +# Combined filtering +hookdeck attempt list --event-id evt_123 --status FAILED --error-code TIMEOUT +``` + +### Get attempt details +```bash +# Get attempt by ID +hookdeck attempt get att_123 + +# Example output includes: +# - Attempt ID and number +# - Event and destination IDs +# - HTTP method and requested URL +# - Response status and body +# - Trigger type and error code +# - Delivery and response latency +# - Timestamps (delivered_at, responded_at, successful_at) +``` + +### Retry attempts +```bash +# Retry a specific attempt +hookdeck attempt retry att_123 + +# Force retry without confirmation +hookdeck attempt retry att_123 --force + +# Note: This creates a new attempt for the same event +``` + + +## Issues + +🚧 **PLANNED FUNCTIONALITY** - Not yet implemented + +### List issues +```bash +# List all issues +hookdeck issue list + +# Filter by status +hookdeck issue list --status ACTIVE +hookdeck issue list --status DISMISSED + +# Filter by type +hookdeck issue list --type DELIVERY_ISSUE +hookdeck issue list --type TRANSFORMATION_ISSUE + +# Limit results +hookdeck issue list --limit 100 +``` + +### Count issues +```bash +# Count all issues +hookdeck issue count + +# Count with filters +hookdeck issue count --status ACTIVE --type DELIVERY_ISSUE +``` + +### Get issue details +```bash +# Get issue by ID +hookdeck issue get +``` + +## Issue Triggers + +**All Parameters:** +```bash +# Issue trigger list command parameters +--name string # Filter by name pattern (supports wildcards) +--type string # Filter by trigger type (delivery, transformation, backpressure) +--disabled # Include disabled triggers (boolean flag) +--limit integer # Limit number of results (default varies) + +# Issue trigger get command parameters + # Required positional argument for trigger ID + +# Issue trigger create command parameters +--name string # Optional: Unique name for the trigger +--type string # Required: Trigger type (delivery, transformation, backpressure) +--description string # Optional: Trigger description + +# Type-specific configuration parameters: +# When --type=delivery: +--strategy string # Required: Strategy (first_attempt, final_attempt) +--connections string # Required: Connection patterns or IDs (comma-separated or "*") + +# When --type=transformation: +--log-level string # Required: Log level (debug, info, warn, error, fatal) +--transformations string # Required: Transformation patterns or IDs (comma-separated or "*") + +# When --type=backpressure: +--delay integer # Required: Minimum delay in milliseconds (60000-86400000) +--destinations string # Required: Destination patterns or IDs (comma-separated or "*") + +# Notification channel parameters (at least one required): +--email # Enable email notifications (boolean flag) +--slack-channel string # Slack channel name (e.g., "#alerts") +--pagerduty # Enable PagerDuty notifications (boolean flag) +--opsgenie # Enable Opsgenie notifications (boolean flag) + +# Issue trigger update command parameters + # Required positional argument for trigger ID +--name string # Update trigger name +--description string # Update trigger description +# Plus any type-specific and notification parameters listed above + +# Issue trigger upsert command parameters (create or update by name) +--name string # Required: Trigger name (used for matching existing) +--type string # Required: Trigger type +# Plus any type-specific and notification parameters listed above + +# Issue trigger delete command parameters + # Required positional argument for trigger ID +--force # Force delete without confirmation (boolean flag) + +# Issue trigger enable/disable command parameters + # Required positional argument for trigger ID +``` + +**Type Validation Rules:** +- **delivery type**: Requires `--strategy` and `--connections` + - `--strategy` values: `first_attempt`, `final_attempt` + - `--connections` accepts: connection IDs, connection name patterns, or `"*"` for all +- **transformation type**: Requires `--log-level` and `--transformations` + - `--log-level` values: `debug`, `info`, `warn`, `error`, `fatal` + - `--transformations` accepts: transformation IDs, transformation name patterns, or `"*"` for all +- **backpressure type**: Requires `--delay` and `--destinations` + - `--delay` range: 60000-86400000 milliseconds (1 minute to 1 day) + - `--destinations` accepts: destination IDs, destination name patterns, or `"*"` for all + +**Notification Channel Combinations:** +- Multiple notification channels can be enabled simultaneously +- `--email` is a boolean flag (no additional configuration) +- `--slack-channel` requires a channel name (e.g., "#alerts", "#monitoring") +- `--pagerduty` and `--opsgenie` are boolean flags requiring pre-configured integrations + +🚧 **PLANNED FUNCTIONALITY** - Not yet implemented + +Issue triggers automatically detect and create issues when specific conditions are met. + +### List issue triggers +```bash +# List all issue triggers +hookdeck issue-trigger list + +# Filter by name pattern +hookdeck issue-trigger list --name "*delivery*" + +# Filter by type +hookdeck issue-trigger list --type delivery +hookdeck issue-trigger list --type transformation +hookdeck issue-trigger list --type backpressure + +# Include disabled triggers +hookdeck issue-trigger list --disabled + +# Limit results +hookdeck issue-trigger list --limit 50 +``` + +### Get issue trigger details +```bash +# Get issue trigger by ID +hookdeck issue-trigger get +``` + +### Create issue triggers + +#### Delivery failure trigger +```bash +# Trigger on final delivery attempt failure +hookdeck issue-trigger create --type delivery \ + --name "delivery-failures" \ + --strategy final_attempt \ + --connections "conn1,conn2" \ + --email \ + --slack-channel "#alerts" + +# Trigger on first delivery attempt failure +hookdeck issue-trigger create --type delivery \ + --name "immediate-delivery-alerts" \ + --strategy first_attempt \ + --connections "*" \ + --pagerduty +``` + +#### Transformation error trigger +```bash +# Trigger on transformation errors +hookdeck issue-trigger create --type transformation \ + --name "transformation-errors" \ + --log-level error \ + --transformations "*" \ + --email \ + --opsgenie + +# Trigger on specific transformation debug logs +hookdeck issue-trigger create --type transformation \ + --name "debug-logs" \ + --log-level debug \ + --transformations "trans1,trans2" \ + --slack-channel "#debug" +``` + +#### Backpressure trigger +```bash +# Trigger on destination backpressure +hookdeck issue-trigger create --type backpressure \ + --name "backpressure-alert" \ + --delay 300000 \ + --destinations "*" \ + --email \ + --pagerduty +``` + +### Update issue trigger +```bash +# Update trigger name and description +hookdeck issue-trigger update --name "new-name" --description "Updated description" + +# Update notification channels +hookdeck issue-trigger update --email --slack-channel "#new-alerts" + +# Update type-specific configuration +hookdeck issue-trigger update --strategy first_attempt --connections "new_conn" +``` + +### Upsert issue trigger (create or update by name) +```bash +# Create or update issue trigger by name +hookdeck issue-trigger upsert --name "delivery-failures" --type delivery --strategy final_attempt +``` + +### Delete issue trigger +```bash +# Delete issue trigger (with confirmation) +hookdeck issue-trigger delete + +# Force delete without confirmation +hookdeck issue-trigger delete --force +``` + +### Enable/Disable issue triggers +```bash +# Enable issue trigger +hookdeck issue-trigger enable + +# Disable issue trigger +hookdeck issue-trigger disable +``` + +## Bookmarks + +**All Parameters:** +```bash +# Bookmark list command parameters +--name string # Filter by name pattern (supports wildcards) +--webhook-id string # Filter by webhook ID (connection) +--label string # Filter by label +--limit integer # Limit number of results (default varies) + +# Bookmark get command parameters + # Required positional argument for bookmark ID + +# Bookmark raw-body command parameters + # Required positional argument for bookmark ID + +# Bookmark create command parameters +--event-data-id string # Required: Event data ID to bookmark +--webhook-id string # Required: Webhook ID (connection) +--label string # Required: Label for categorization +--name string # Optional: Bookmark name + +# Bookmark update command parameters + # Required positional argument for bookmark ID +--name string # Update bookmark name +--label string # Update bookmark label + +# Bookmark delete command parameters + # Required positional argument for bookmark ID +--force # Force delete without confirmation (boolean flag) + +# Bookmark trigger command parameters (replay) + # Required positional argument for bookmark ID +``` + +🚧 **PLANNED FUNCTIONALITY** - Not yet implemented + +Bookmarks allow you to save webhook payloads for testing and replay. + +### List bookmarks +```bash +# List all bookmarks +hookdeck bookmark list + +# Filter by name pattern +hookdeck bookmark list --name "*test*" + +# Filter by webhook ID (connection) +hookdeck bookmark list --webhook-id + +# Filter by label +hookdeck bookmark list --label test_data + +# Limit results +hookdeck bookmark list --limit 50 +``` + +### Get bookmark details +```bash +# Get bookmark by ID +hookdeck bookmark get + +# Get bookmark raw body +hookdeck bookmark raw-body +``` + +### Create a bookmark +```bash +# Create bookmark from event +hookdeck bookmark create --event-data-id \ + --webhook-id \ + --label test_payload \ + --name "stripe-payment-test" +``` + +### Update a bookmark +```bash +# Update bookmark properties +hookdeck bookmark update --name "new-name" --label new_label +``` + +### Delete a bookmark +```bash +# Delete bookmark (with confirmation) +hookdeck bookmark delete + +# Force delete without confirmation +hookdeck bookmark delete --force +``` + +### Trigger bookmark (replay) +```bash +# Trigger bookmark to replay webhook +hookdeck bookmark trigger +``` + +## Integrations + +🚧 **PLANNED FUNCTIONALITY** - Not yet implemented + +Integrations connect third-party services to your Hookdeck workspace. + +### List integrations +```bash +# List all integrations +hookdeck integration list + +# Limit results +hookdeck integration list --limit 50 +``` + +### Get integration details +```bash +# Get integration by ID +hookdeck integration get +``` + +### Create an integration +```bash +# Create integration (provider-specific configuration required) +hookdeck integration create --provider PROVIDER_NAME +``` + +### Update an integration +```bash +# Update integration (provider-specific configuration) +hookdeck integration update +``` + +### Delete an integration +```bash +# Delete integration (with confirmation) +hookdeck integration delete + +# Force delete without confirmation +hookdeck integration delete --force +``` + +### Attach/Detach sources +```bash +# Attach source to integration +hookdeck integration attach + +# Detach source from integration +hookdeck integration detach +``` + +## Requests + +🚧 **PLANNED FUNCTIONALITY** - Not yet implemented + +Requests represent raw incoming webhook requests before processing. + +### List requests +```bash +# List all requests +hookdeck request list + +# Filter by source ID +hookdeck request list --source-id + +# Filter by verification status +hookdeck request list --verified true +hookdeck request list --verified false + +# Filter by rejection cause +hookdeck request list --rejection-cause INVALID_SIGNATURE + +# Limit results +hookdeck request list --limit 100 +``` + +### Get request details +```bash +# Get request by ID +hookdeck request get + +# Get request raw body +hookdeck request raw-body +``` + +### Retry request +```bash +# Retry request processing +hookdeck request retry +``` + +### List request events +```bash +# List events generated from request +hookdeck request events --limit 50 + +# List ignored events from request +hookdeck request ignored-events --limit 50 +``` + +## Bulk Operations + +**All Parameters:** +```bash +# Bulk event-retry command parameters +--limit integer # Limit number of results for list operations +--query string # JSON query for filtering resources to retry + # Required positional argument for get/cancel operations + +# Bulk request-retry command parameters +--limit integer # Limit number of results for list operations +--query string # JSON query for filtering resources to retry + # Required positional argument for get/cancel operations + +# Bulk ignored-event-retry command parameters +--limit integer # Limit number of results for list operations +--query string # JSON query for filtering resources to retry + # Required positional argument for get/cancel operations +``` + +**Query JSON Format Examples:** +- Event retry: `'{"status": "FAILED", "webhook_id": "conn_123"}'` +- Request retry: `'{"verified": false, "source_id": "src_123"}'` +- Ignored event retry: `'{"webhook_id": "conn_123"}'` + +**Operations Available:** +- `list` - List bulk operations +- `create` - Create new bulk operation +- `plan` - Dry run to see what would be affected +- `get` - Get operation details +- `cancel` - Cancel running operation + +🚧 **PLANNED FUNCTIONALITY** - Not yet implemented + +Bulk operations allow you to perform actions on multiple resources at once. + +### Event Bulk Retry +```bash +# List bulk event retry operations +hookdeck bulk event-retry list --limit 50 + +# Create bulk event retry operation +hookdeck bulk event-retry create --query '{"status": "FAILED", "webhook_id": "conn_123"}' + +# Plan bulk event retry (dry run) +hookdeck bulk event-retry plan --query '{"status": "FAILED"}' + +# Get bulk operation details +hookdeck bulk event-retry get + +# Cancel bulk operation +hookdeck bulk event-retry cancel +``` + +### Request Bulk Retry +```bash +# List bulk request retry operations +hookdeck bulk request-retry list --limit 50 + +# Create bulk request retry operation +hookdeck bulk request-retry create --query '{"verified": false, "source_id": "src_123"}' + +# Plan bulk request retry (dry run) +hookdeck bulk request-retry plan --query '{"verified": false}' + +# Get bulk operation details +hookdeck bulk request-retry get + +# Cancel bulk operation +hookdeck bulk request-retry cancel +``` + +### Ignored Events Bulk Retry +```bash +# List bulk ignored event retry operations +hookdeck bulk ignored-event-retry list --limit 50 + +# Create bulk ignored event retry operation +hookdeck bulk ignored-event-retry create --query '{"webhook_id": "conn_123"}' + +# Plan bulk ignored event retry (dry run) +hookdeck bulk ignored-event-retry plan --query '{"webhook_id": "conn_123"}' + +# Get bulk operation details +hookdeck bulk ignored-event-retry get + +# Cancel bulk operation +hookdeck bulk ignored-event-retry cancel +``` + +## Notifications + +🚧 **PLANNED FUNCTIONALITY** - Not yet implemented + +### Send webhook notification +```bash +# Send webhook notification +hookdeck notification webhook --url "https://example.com/webhook" \ + --payload '{"message": "Test notification", "timestamp": "2023-12-01T10:00:00Z"}' +``` + +--- + +## Command Parameter Patterns + +### Type-Driven Validation +Many commands use type-driven validation where the `--type` parameter determines which additional flags are required or valid: + +- **Source creation**: `--type STRIPE` requires `--webhook-secret`, while `--type GITLAB` requires `--api-key` +- **Issue trigger creation**: `--type delivery` requires `--strategy` and `--connections`, while `--type transformation` requires `--log-level` and `--transformations` + +### Collision Resolution +The `hookdeck connection create` command uses prefixed flags to avoid parameter collision when creating inline resources: + +- **Individual resource commands**: Use `--type` (clear context) +- **Connection creation with inline resources**: Use `--source-type` and `--destination-type` (disambiguation) + +### Parameter Conversion Patterns +- **Nested JSON → Flat flags**: `{"configs": {"strategy": "final_attempt"}}` becomes `--strategy final_attempt` +- **Arrays → Comma-separated**: `{"connections": ["conn1", "conn2"]}` becomes `--connections "conn1,conn2"` +- **Boolean presence → Presence flags**: `{"channels": {"email": {}}}` becomes `--email` +- **Complex objects → Value flags**: `{"channels": {"slack": {"channel_name": "#alerts"}}}` becomes `--slack-channel "#alerts"` + +### Global Conventions +- **Resource IDs**: Use `` format in documentation +- **Optional parameters**: Enclosed in square brackets `[--optional-flag]` +- **Required vs optional**: Indicated by command syntax and parameter descriptions +- **Filtering**: Most list commands support filtering by name patterns, IDs, and status +- **Pagination**: All list commands support `--limit` for result limiting +- **Force operations**: Destructive operations support `--force` to skip confirmations + +This comprehensive reference provides complete coverage of all Hookdeck CLI commands, including current functionality and planned features with their full parameter specifications. \ No newline at end of file