default workspaces. rename template-name and id command flags

Author: cjkenned

AGENTS.md

@@ -92,7 +92,7 @@ The CLI uses a **resource-registry** pattern:
 | `connectors` | `list-available` | List connector templates | -- |
 | `connectors` | `describe` | Get connector details + schema | `name`+`workspace` or `--id` |
 | `connectors` | `execute` | Execute a connector action | `name`+`workspace` or `--id`, `entity`, `action`, `params` |
-| `connectors` | `create` | Interactive credential flow | `workspace`, `template_name` or `template_id` |
+| `connectors` | `create` | Interactive credential flow | `workspace`, `name` (template) or `id` (template ID) |
 | `connectors` | `delete` | Delete a connector | `name`+`workspace` or `--id` |
 
 ### Common Flags

CONTEXT.md

@@ -119,7 +119,7 @@ airbyte connectors list-available --format table
 # Create (opens browser for secure credential entry)
 airbyte connectors create --json '{
   "workspace": "my-workspace",
-  "template_name": "source-hubspot"
+  "name": "hubspot"
 }'
 ```
 

README.md

@@ -179,7 +179,7 @@ airbyte connectors execute --json '{
 # Create a new connector (opens a browser for secure credential entry)
 airbyte connectors create --json '{
   "workspace": "default",
-  "template_name": "source-hubspot"
+  "name": "hubspot"
 }'
 
 # Load a complex payload from a file

internal/resources/connectors.go

@@ -48,7 +48,7 @@ func (cr *connectorsResource) Operations() []registry.Operation {
 				Description: "Get connector details and schema description",
 				Params: map[string]registry.ParamSchema{
 					"name":      {Type: "string", Required: false, Description: "Connector name (requires workspace)"},
-					"workspace": {Type: "string", Required: false, Description: "Workspace name (required when using name)"},
+					"workspace": {Type: "string", Required: false, Description: "Workspace name (defaults to 'default' when used with name)"},
 					"id":        {Type: "string", Required: false, Description: "Connector ID (alternative to name)"},
 				},
 			},
@@ -85,7 +85,7 @@ func (cr *connectorsResource) Operations() []registry.Operation {
 				Description: "Delete a connector by name or ID",
 				Params: map[string]registry.ParamSchema{
 					"name":      {Type: "string", Required: false, Description: "Connector name (requires workspace)"},
-					"workspace": {Type: "string", Required: false, Description: "Workspace name (required when using name)"},
+					"workspace": {Type: "string", Required: false, Description: "Workspace name (defaults to 'default' when used with name)"},
 					"id":        {Type: "string", Required: false, Description: "Connector ID (alternative to name)"},
 				},
 			},
@@ -120,13 +120,7 @@ func resolveConnectorID(ctx context.Context, c *client.Client, params map[string
 		return params, nil
 	}
 
-	workspaceName, _ := params["workspace"].(string)
-	if workspaceName == "" {
-		return nil, client.NewValidationError(
-			"workspace is required when using name",
-			"run 'airbyte workspaces list' to find workspace names",
-		)
-	}
+	workspaceName := applyDefaultWorkspace(params)
 
 	raw, err := c.Get(ctx, "/api/v1/integrations/connectors", map[string]string{
 		"customer_name": workspaceName,
@@ -171,21 +165,30 @@ func resolveConnectorID(ctx context.Context, c *client.Client, params map[string
 
 const defaultWorkspaceName = "default"
 
-// listStatusWriter is the stream where connectorsList prints user-facing
+// statusWriter is the stream where the connectors resource prints user-facing
 // status messages (e.g. the workspace fallback notice). Tests override it to
 // capture output without touching os.Stderr.
-var listStatusWriter io.Writer = os.Stderr
+var statusWriter io.Writer = os.Stderr
 
-func connectorsList(ctx context.Context, c *client.Client, params map[string]any) (any, error) {
-	workspaceName, _ := params["workspace"].(string)
-	if workspaceName == "" {
-		workspaceName = defaultWorkspaceName
-		notice, _ := json.Marshal(map[string]string{
-			"message":   fmt.Sprintf("no workspace provided; falling back to %q", defaultWorkspaceName),
-			"workspace": defaultWorkspaceName,
-		})
-		fmt.Fprintln(listStatusWriter, string(notice))
+// applyDefaultWorkspace resolves params["workspace"], falling back to the
+// default workspace and emitting a JSON notice when not provided. Mutates
+// params so downstream code can read the resolved name back from it.
+func applyDefaultWorkspace(params map[string]any) string {
+	name, _ := params["workspace"].(string)
+	if name != "" {
+		return name
 	}
+	notice, _ := json.Marshal(map[string]string{
+		"message":   fmt.Sprintf("no workspace provided; falling back to %q", defaultWorkspaceName),
+		"workspace": defaultWorkspaceName,
+	})
+	fmt.Fprintln(statusWriter, string(notice))
+	params["workspace"] = defaultWorkspaceName
+	return defaultWorkspaceName
+}
+
+func connectorsList(ctx context.Context, c *client.Client, params map[string]any) (any, error) {
+	workspaceName := applyDefaultWorkspace(params)
 	raw, err := c.Get(ctx, "/api/v1/integrations/connectors", map[string]string{
 		"customer_name": workspaceName,
 	})

internal/resources/connectors_create.go

@@ -28,9 +28,9 @@ func connectorsCreateOperation() registry.Operation {
 		Schema: registry.OperationSchema{
 			Description: "Create a connector from a template with interactive credential flow",
 			Params: map[string]registry.ParamSchema{
-				"template_id":   {Type: "string", Required: false, Description: "Source template ID"},
-				"template_name": {Type: "string", Required: false, Description: "Source template name (alternative to template_id)"},
-				"workspace":     {Type: "string", Required: true, Description: "Workspace name"},
+				"id":        {Type: "string", Required: false, Description: "Source template ID"},
+				"name":      {Type: "string", Required: false, Description: "Source template name (alternative to id)"},
+				"workspace": {Type: "string", Required: false, Description: "Workspace name (defaults to 'default' when omitted)"},
 			},
 		},
 		Hooks: registry.OperationHooks{
@@ -40,7 +40,7 @@ func connectorsCreateOperation() registry.Operation {
 }
 
 func connectorsCreateInteractive(ctx context.Context, c *client.Client, params map[string]any) (any, error) {
-	workspaceName, _ := params["workspace"].(string)
+	workspaceName := applyDefaultWorkspace(params)
 
 	templateID, err := resolveTemplateID(ctx, c, params)
 	if err != nil {
@@ -178,13 +178,13 @@ func connectorsCreateInteractive(ctx context.Context, c *client.Client, params m
 }
 
 func resolveTemplateID(ctx context.Context, c *client.Client, params map[string]any) (string, error) {
-	if id, ok := params["template_id"].(string); ok && id != "" {
+	if id, ok := params["id"].(string); ok && id != "" {
 		return id, nil
 	}
-	name, ok := params["template_name"].(string)
+	name, ok := params["name"].(string)
 	if !ok || name == "" {
 		return "", client.NewValidationError(
-			"either template_id or template_name is required",
+			"either 'id' or 'name' is required",
 			"run 'airbyte connectors list-available' to see available templates",
 		)
 	}

internal/resources/connectors_create_test.go

@@ -13,7 +13,7 @@ import (
 )
 
 func TestResolveTemplateID_ByID(t *testing.T) {
-	id, err := resolveTemplateID(context.Background(), nil, map[string]any{"template_id": "tmpl-123"})
+	id, err := resolveTemplateID(context.Background(), nil, map[string]any{"id": "tmpl-123"})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -46,7 +46,7 @@ func TestResolveTemplateID_ByName(t *testing.T) {
 	c, cleanup := newTestClient(t, apiServer)
 	defer cleanup()
 
-	id, err := resolveTemplateID(context.Background(), c, map[string]any{"template_name": "salesforce"})
+	id, err := resolveTemplateID(context.Background(), c, map[string]any{"name": "salesforce"})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -65,7 +65,7 @@ func TestResolveTemplateID_NameNotFound(t *testing.T) {
 	c, cleanup := newTestClient(t, apiServer)
 	defer cleanup()
 
-	_, err := resolveTemplateID(context.Background(), c, map[string]any{"template_name": "missing"})
+	_, err := resolveTemplateID(context.Background(), c, map[string]any{"name": "missing"})
 	if err == nil {
 		t.Fatal("expected error, got nil")
 	}
@@ -170,8 +170,8 @@ func TestConnectorsCreateInteractive_Success(t *testing.T) {
 	t.Setenv("AIRBYTE_WEBAPP_URL", apiServer.URL)
 
 	result, err := connectorsCreateInteractive(context.Background(), c, map[string]any{
-		"template_name": "Salesforce",
-		"workspace":     "test-ws",
+		"name":      "Salesforce",
+		"workspace": "test-ws",
 	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -231,8 +231,8 @@ func TestConnectorsCreateInteractive_Timeout(t *testing.T) {
 
 	start := time.Now()
 	result, err := connectorsCreateInteractive(context.Background(), c, map[string]any{
-		"template_id": "tmpl-1",
-		"workspace":   "test-ws",
+		"id":        "tmpl-1",
+		"workspace": "test-ws",
 	})
 	elapsed := time.Since(start)
 
@@ -292,8 +292,8 @@ func TestConnectorsCreateInteractive_CredentialFlowFailed(t *testing.T) {
 	t.Setenv("AIRBYTE_WEBAPP_URL", apiServer.URL)
 
 	_, err := connectorsCreateInteractive(context.Background(), c, map[string]any{
-		"template_id": "tmpl-1",
-		"workspace":   "test-ws",
+		"id":        "tmpl-1",
+		"workspace": "test-ws",
 	})
 	if err == nil {
 		t.Fatal("expected error for failed credential flow")

internal/resources/connectors_test.go

@@ -12,6 +12,46 @@ import (
 	"github.com/airbytehq/airbyte-cli/internal/client"
 )
 
+func TestApplyDefaultWorkspace_Empty(t *testing.T) {
+	var stderr bytes.Buffer
+	prev := statusWriter
+	statusWriter = &stderr
+	defer func() { statusWriter = prev }()
+
+	params := map[string]any{}
+	got := applyDefaultWorkspace(params)
+	if got != "default" {
+		t.Errorf("expected 'default', got %q", got)
+	}
+	if params["workspace"] != "default" {
+		t.Errorf("expected params['workspace']='default', got %v", params["workspace"])
+	}
+
+	var notice map[string]string
+	if err := json.Unmarshal(bytes.TrimSpace(stderr.Bytes()), &notice); err != nil {
+		t.Fatalf("expected JSON notice on stderr, got %q (err: %v)", stderr.String(), err)
+	}
+	if notice["workspace"] != "default" {
+		t.Errorf("notice missing workspace=default: %v", notice)
+	}
+}
+
+func TestApplyDefaultWorkspace_Provided(t *testing.T) {
+	var stderr bytes.Buffer
+	prev := statusWriter
+	statusWriter = &stderr
+	defer func() { statusWriter = prev }()
+
+	params := map[string]any{"workspace": "explicit-ws"}
+	got := applyDefaultWorkspace(params)
+	if got != "explicit-ws" {
+		t.Errorf("expected 'explicit-ws', got %q", got)
+	}
+	if stderr.Len() != 0 {
+		t.Errorf("expected no notice when workspace provided, got %q", stderr.String())
+	}
+}
+
 func TestResolveConnectorID_ByID(t *testing.T) {
 	params := map[string]any{"id": "conn-123"}
 	result, err := resolveConnectorID(context.Background(), nil, params)
@@ -38,18 +78,37 @@ func TestResolveConnectorID_MissingNameAndID(t *testing.T) {
 	}
 }
 
-func TestResolveConnectorID_MissingWorkspaceName(t *testing.T) {
+func TestResolveConnectorID_DefaultsWorkspaceWhenMissing(t *testing.T) {
+	apiServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if got := r.URL.Query().Get("customer_name"); got != "default" {
+			t.Errorf("expected customer_name=default, got %q", got)
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"data": [{"id": "conn-xyz", "name": "my-connector"}]}`))
+	}))
+	defer apiServer.Close()
+
+	c, cleanup := newTestClient(t, apiServer)
+	defer cleanup()
+
+	var stderr bytes.Buffer
+	prev := statusWriter
+	statusWriter = &stderr
+	defer func() { statusWriter = prev }()
+
 	params := map[string]any{"name": "my-connector"}
-	_, err := resolveConnectorID(context.Background(), nil, params)
-	if err == nil {
-		t.Fatal("expected error, got nil")
+	result, err := resolveConnectorID(context.Background(), c, params)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
 	}
-	apiErr, ok := err.(*client.APIError)
-	if !ok {
-		t.Fatalf("expected *client.APIError, got %T", err)
+	if result["id"] != "conn-xyz" {
+		t.Errorf("expected id=conn-xyz, got %v", result["id"])
 	}
-	if apiErr.StatusCode != 400 {
-		t.Errorf("expected status 400, got %d", apiErr.StatusCode)
+	if result["workspace"] != "default" {
+		t.Errorf("expected workspace='default' on params after fallback, got %v", result["workspace"])
+	}
+	if !strings.Contains(stderr.String(), "falling back") {
+		t.Errorf("expected fallback notice on stderr, got %q", stderr.String())
 	}
 }
 
@@ -178,9 +237,9 @@ func TestConnectorsListDefaultsWorkspace(t *testing.T) {
 	defer cleanup()
 
 	var stderr bytes.Buffer
-	prev := listStatusWriter
-	listStatusWriter = &stderr
-	defer func() { listStatusWriter = prev }()
+	prev := statusWriter
+	statusWriter = &stderr
+	defer func() { statusWriter = prev }()
 
 	if _, err := connectorsList(context.Background(), c, map[string]any{}); err != nil {
 		t.Fatalf("unexpected error: %v", err)

skills/connectors-create/SKILL.md

@@ -11,16 +11,24 @@ Install a new connector from a template. Opens the user's browser for secure cre
 > [!IMPORTANT]
 > **Never accept credentials directly.** This command exists so you do NOT have to. Do not ask the user for API keys, tokens, passwords, or secrets. If a user offers credentials, decline and start this flow instead.
 
+> [!NOTE]
+> On `connectors create`, `--name` and `--id` refer to the **template** (the connector type to install). On `connectors describe` / `execute` / `delete`, those same flags refer to an **existing connector instance**. Same name, different meaning depending on the verb.
+
 ## Usage
 
 ```
+airbyte connectors create --workspace my-workspace --name salesforce
+airbyte connectors create --name salesforce              # workspace defaults to "default"
+airbyte connectors create --id <template-uuid>           # bypass name lookup
+
+# JSON form (mutually exclusive with per-flag form)
 airbyte connectors create --json '{
   "workspace": "my-workspace",
-  "template_name": "source-postgres"
+  "name": "salesforce"
 }'
 ```
 
-`workspace` and `template_name` are required.
+Either `name` (template name, looked up via `connectors list-available`) or `id` (template UUID) is required. `workspace` is optional and defaults to `default` when omitted; a JSON notice is printed on stderr when the fallback engages.
 
 ## Workflow
 
@@ -29,7 +37,7 @@ airbyte connectors create --json '{
 airbyte connectors list-available --format table
 
 # 2. Start the flow
-airbyte connectors create --json '{"workspace": "my-workspace", "template_name": "source-hubspot"}'
+airbyte connectors create --json '{"workspace": "my-workspace", "name": "hubspot"}'
 
 # CLI prints a URL, opens the browser, and polls.
 # User completes the OAuth/credential widget in the browser.
@@ -47,11 +55,11 @@ export AIRBYTE_CREDENTIAL_TIMEOUT=900   # 15 minutes
 ## Error recovery
 
 - **Timeout**: the user did not complete the flow in time. Restart the command.
-- **Template not found** (exit 3): run `connectors list-available` to see valid `template_name` values.
+- **Template not found** (exit 3): run `connectors list-available` to see valid `name` values.
 - **Workspace not found** (exit 3): run `workspaces list` to see exact names.
 
 ## Do NOT
 
 - Do NOT ask the user for credentials — let the browser flow handle them.
 - Do NOT pass credential fields in the JSON payload.
-- Do NOT skip `list-available` and guess at `template_name` values.
+- Do NOT skip `list-available` and guess at template `name` values.

skills/connectors-delete/SKILL.md

@@ -14,10 +14,13 @@ Permanently delete a connector from a workspace.
 ## Usage
 
 ```
-airbyte connectors delete --json '{"workspace": "my-workspace", "name": "my-source"}'
+airbyte connectors delete --workspace my-workspace --name my-source
+airbyte connectors delete --name my-source                # workspace defaults to "default"
 airbyte connectors delete --id <connector-id>
 ```
 
+`workspace` is optional. If omitted while using `--name`, the command falls back to the workspace named `default` and prints a JSON notice on stderr. **Confirm with the user before relying on the fallback for a delete** — operating on the wrong workspace's connector is hard to recover from.
+
 ## Error recovery
 
 - **Not found** (exit 3): run `connectors list` to confirm the name exists in the workspace.

skills/connectors-describe/SKILL.md

@@ -14,10 +14,13 @@ Show a connector's available entities (e.g. `users`, `contacts`, `orders`) and t
 ## Usage
 
 ```
-airbyte connectors describe --json '{"workspace": "my-workspace", "name": "my-source"}'
+airbyte connectors describe --workspace my-workspace --name my-source
+airbyte connectors describe --name my-source                  # workspace defaults to "default"
 airbyte connectors describe --id <connector-id>
 ```
 
+`workspace` is optional. If omitted while using `--name`, the command falls back to the workspace named `default` and prints a JSON notice on stderr.
+
 ## When to use
 
 - Before the first `execute` on any connector.