feat: add name-based lookup and improve error handling for connection get

- Add support for passing connection name to 'connection get' command
- Implement resolveConnectionID() to accept both ID and name
- Improve 404 error handling with user-friendly messages
- Add tests for name-based lookup and error cases
- Update command usage and help text to reflect name support

Author: leggetter

pkg/cmd/connection_get.go

@@ -5,10 +5,12 @@ import (
 	"encoding/json"
 	"fmt"
 	"os"
+	"strings"
 
 	"github.com/spf13/cobra"
 
 	"github.com/hookdeck/hookdeck-cli/pkg/ansi"
+	"github.com/hookdeck/hookdeck-cli/pkg/hookdeck"
 	"github.com/hookdeck/hookdeck-cli/pkg/validators"
 )
 
@@ -22,14 +24,19 @@ func newConnectionGetCmd() *connectionGetCmd {
 	cc := &connectionGetCmd{}
 
 	cc.cmd = &cobra.Command{
-		Use:   "get <connection-id>",
+		Use:   "get <connection-id-or-name>",
 		Args:  validators.ExactArgs(1),
 		Short: "Get connection details",
 		Long: `Get detailed information about a specific connection.
 
+You can specify either a connection ID or name.
+
 Examples:
-  # Get connection details
-  hookdeck connection get conn_abc123`,
+	 # Get connection by ID
+	 hookdeck connection get conn_abc123
+	 
+	 # Get connection by name
+	 hookdeck connection get my-connection`,
 		RunE: cc.runConnectionGetCmd,
 	}
 
@@ -43,14 +50,20 @@ func (cc *connectionGetCmd) runConnectionGetCmd(cmd *cobra.Command, args []strin
 		return err
 	}
 
-	connectionID := args[0]
-	client := Config.GetAPIClient()
+	connectionIDOrName := args[0]
+	apiClient := Config.GetAPIClient()
 	ctx := context.Background()
 
+	// Resolve connection ID from name or ID
+	connectionID, err := resolveConnectionID(ctx, apiClient, connectionIDOrName)
+	if err != nil {
+		return err
+	}
+
 	// Get connection by ID
-	conn, err := client.GetConnection(ctx, connectionID)
+	conn, err := apiClient.GetConnection(ctx, connectionID)
 	if err != nil {
-		return fmt.Errorf("failed to get connection: %w", err)
+		return formatConnectionError(err, connectionIDOrName)
 	}
 
 	if cc.output == "json" {
@@ -141,3 +154,62 @@ func (cc *connectionGetCmd) runConnectionGetCmd(cmd *cobra.Command, args []strin
 
 	return nil
 }
+
+// resolveConnectionID accepts both connection names and IDs
+// Try as ID first (if it starts with conn_ or web_), then lookup by name
+func resolveConnectionID(ctx context.Context, client *hookdeck.Client, nameOrID string) (string, error) {
+	// If it looks like a connection ID, try it directly
+	if strings.HasPrefix(nameOrID, "conn_") || strings.HasPrefix(nameOrID, "web_") {
+		// Try to get it to verify it exists
+		_, err := client.GetConnection(ctx, nameOrID)
+		if err == nil {
+			return nameOrID, nil
+		}
+		// If we get a 404, fall through to name lookup
+		// For other errors, format and return the error
+		errMsg := strings.ToLower(err.Error())
+		if !strings.Contains(errMsg, "404") && !strings.Contains(errMsg, "not found") {
+			return "", err
+		}
+		// 404 on ID lookup - fall through to try name lookup
+	}
+
+	// Try to find by name
+	params := map[string]string{
+		"name": nameOrID,
+	}
+
+	result, err := client.ListConnections(ctx, params)
+	if err != nil {
+		return "", fmt.Errorf("failed to lookup connection by name '%s': %w", nameOrID, err)
+	}
+
+	if result.Pagination.Limit == 0 || len(result.Models) == 0 {
+		return "", fmt.Errorf("connection not found: '%s'\n\nPlease check the connection name or ID and try again", nameOrID)
+	}
+
+	if len(result.Models) > 1 {
+		return "", fmt.Errorf("multiple connections found with name '%s', please use the connection ID instead", nameOrID)
+	}
+
+	return result.Models[0].ID, nil
+}
+
+// formatConnectionError provides user-friendly error messages for connection get failures
+func formatConnectionError(err error, identifier string) error {
+	errMsg := err.Error()
+
+	// Check for 404/not found errors (case-insensitive)
+	errMsgLower := strings.ToLower(errMsg)
+	if strings.Contains(errMsgLower, "404") || strings.Contains(errMsgLower, "not found") {
+		return fmt.Errorf("connection not found: '%s'\n\nPlease check the connection name or ID and try again", identifier)
+	}
+
+	// Check for network/timeout errors
+	if strings.Contains(errMsg, "timeout") || strings.Contains(errMsg, "connection refused") {
+		return fmt.Errorf("failed to connect to Hookdeck API: %w\n\nPlease check your network connection and try again", err)
+	}
+
+	// Default to the original error with some context
+	return fmt.Errorf("failed to get connection '%s': %w", identifier, err)
+}

test/acceptance/connection_test.go

@@ -62,6 +62,82 @@ func TestConnectionCreateAndDelete(t *testing.T) {
 	t.Logf("Successfully created and retrieved connection: %s", conn.Name)
 }
 
+// TestConnectionGetByName tests that connection get works with connection name
+func TestConnectionGetByName(t *testing.T) {
+	if testing.Short() {
+		t.Skip("Skipping acceptance test in short mode")
+	}
+
+	cli := NewCLIRunner(t)
+	timestamp := generateTimestamp()
+
+	connName := "test-get-by-name-" + timestamp
+	sourceName := "test-src-" + timestamp
+	destName := "test-dst-" + timestamp
+
+	// Create a test connection
+	var createResp Connection
+	err := cli.RunJSON(&createResp,
+		"connection", "create",
+		"--name", connName,
+		"--source-name", sourceName,
+		"--source-type", "WEBHOOK",
+		"--destination-name", destName,
+		"--destination-type", "CLI",
+		"--destination-cli-path", "/webhooks",
+	)
+	require.NoError(t, err, "Should create test connection")
+	require.NotEmpty(t, createResp.ID, "Connection should have an ID")
+
+	// Cleanup
+	t.Cleanup(func() {
+		deleteConnection(t, cli, createResp.ID)
+	})
+
+	// Test 1: Get by ID (original behavior)
+	var getByID Connection
+	err = cli.RunJSON(&getByID, "connection", "get", createResp.ID)
+	require.NoError(t, err, "Should be able to get connection by ID")
+	assert.Equal(t, createResp.ID, getByID.ID, "Connection ID should match")
+
+	// Test 2: Get by name (new behavior)
+	var getByName Connection
+	err = cli.RunJSON(&getByName, "connection", "get", connName)
+	require.NoError(t, err, "Should be able to get connection by name")
+	assert.Equal(t, createResp.ID, getByName.ID, "Connection ID should match when retrieved by name")
+	assert.Equal(t, connName, getByName.Name, "Connection name should match")
+
+	// Test 3: Verify both methods return the same connection
+	assert.Equal(t, getByID.ID, getByName.ID, "Getting by ID and name should return same connection")
+
+	t.Logf("Successfully tested connection get by both ID (%s) and name (%s)", createResp.ID, connName)
+}
+
+// TestConnectionGetNotFound tests error handling for non-existent connections
+func TestConnectionGetNotFound(t *testing.T) {
+	if testing.Short() {
+		t.Skip("Skipping acceptance test in short mode")
+	}
+
+	cli := NewCLIRunner(t)
+
+	// Test 1: Non-existent ID
+	stdout, stderr, err := cli.Run("connection", "get", "conn_nonexistent123")
+	require.Error(t, err, "Should error when connection ID doesn't exist")
+	combinedOutput := stdout + stderr
+	assert.Contains(t, combinedOutput, "connection not found", "Error should indicate connection not found")
+	assert.Contains(t, combinedOutput, "Please check the connection name or ID", "Error should suggest checking the identifier")
+
+	// Test 2: Non-existent name
+	stdout, stderr, err = cli.Run("connection", "get", "nonexistent-connection-name-xyz")
+	require.Error(t, err, "Should error when connection name doesn't exist")
+	combinedOutput = stdout + stderr
+	assert.Contains(t, combinedOutput, "connection not found", "Error should indicate connection not found")
+	assert.Contains(t, combinedOutput, "Please check the connection name or ID", "Error should suggest checking the identifier")
+
+	t.Logf("Successfully tested error handling for non-existent connections")
+}
+
 // TestConnectionWithWebhookSource tests creating a connection with a WEBHOOK source
 func TestConnectionWithWebhookSource(t *testing.T) {
 	if testing.Short() {