hookdeck-cli: Instructions file for Codex

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
• main.go - Main entry point (repo root)
• REFERENCE.md - Complete CLI documentation and examples

Key Files

• https://api.hookdeck.com/2026-09-01/openapi - API specification (source of truth for all API interactions)
• pkg/cmd/sources/ - Fetches and caches the OpenAPI spec for source type enum and auth rules; use for validation and help in source and connection management
• pkg/cmd/helptext.go - Shared Short/Long help for resource commands (sources, connections); use when adding or editing command help to avoid duplication
• .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

# 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)