feat(calendar): add subscribe command (#327) (thanks @cdthompson)

Add new `calendar subscribe` command to add an existing calendar to the
user's calendar list. Supports optional flags for color, hidden state,
and selection state.

Aliases: sub, add-calendar

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

CHANGELOG.md

@@ -6,6 +6,7 @@
 - Sheets: add `sheets insert` to insert rows/columns into a sheet. (#203) — thanks @andybergon.
 - Sheets: add `sheets links` (alias `hyperlinks`) to list cell links from ranges, including rich-text links. (#374) — thanks @omothm.
 - Sheets: add `sheets create --parent` to place new spreadsheets in a Drive folder. (#424) — thanks @ManManavadaria.
+- Calendar: add `calendar subscribe` (aliases `sub`, `add-calendar`) to add a shared calendar to the current account’s calendar list. (#327) — thanks @cdthompson.
 - Gmail: add `watch serve --history-types` filtering (`messageAdded|messageDeleted|labelAdded|labelRemoved`) and include `deletedMessageIds` in webhook payloads. (#168) — thanks @salmonumbrella.
 - Contacts: support `--org`, `--title`, `--url`, `--note`, and `--custom` on create/update; include custom fields in get output with deterministic ordering. (#199) — thanks @phuctm97.
 - Drive: add `drive ls --all` (alias `--global`) to list across all accessible files; make `--all` and `--parent` mutually exclusive. (#107) — thanks @struong.

internal/cmd/calendar.go

@@ -14,6 +14,7 @@ import (
 
 type CalendarCmd struct {
 	Calendars       CalendarCalendarsCmd       `cmd:"" name:"calendars" help:"List calendars"`
+	Subscribe       CalendarSubscribeCmd       `cmd:"" name:"subscribe" aliases:"sub,add-calendar" help:"Add a calendar to your calendar list"`
 	ACL             CalendarAclCmd             `cmd:"" name:"acl" aliases:"permissions,perms" help:"List calendar ACL"`
 	Events          CalendarEventsCmd          `cmd:"" name:"events" aliases:"list,ls" help:"List events from a calendar or all calendars"`
 	Event           CalendarEventCmd           `cmd:"" name:"event" aliases:"get,info,show" help:"Get event"`
@@ -107,6 +108,55 @@ func (c *CalendarCalendarsCmd) Run(ctx context.Context, flags *RootFlags) error
 	return nil
 }
 
+type CalendarSubscribeCmd struct {
+	CalendarID string `arg:"" name:"calendarId" help:"Calendar ID to subscribe to (e.g., user@example.com or calendar ID)"`
+	ColorID    string `name:"color-id" help:"Color ID (1-24, see 'calendar colors')"`
+	Hidden     bool   `name:"hidden" help:"Hide from the calendar list UI"`
+	Selected   bool   `name:"selected" help:"Show events in the calendar UI" default:"true" negatable:""`
+}
+
+func (c *CalendarSubscribeCmd) Run(ctx context.Context, flags *RootFlags) error {
+	u := ui.FromContext(ctx)
+	account, err := requireAccount(flags)
+	if err != nil {
+		return err
+	}
+	calendarID := strings.TrimSpace(c.CalendarID)
+	if calendarID == "" {
+		return usage("calendarId required")
+	}
+	colorID, err := validateCalendarColorId(c.ColorID)
+	if err != nil {
+		return err
+	}
+
+	svc, err := newCalendarService(ctx, account)
+	if err != nil {
+		return err
+	}
+
+	entry := &calendar.CalendarListEntry{
+		Id:       calendarID,
+		Hidden:   c.Hidden,
+		Selected: c.Selected,
+	}
+	if colorID != "" {
+		entry.ColorId = colorID
+	}
+
+	added, err := svc.CalendarList.Insert(entry).Do()
+	if err != nil {
+		return err
+	}
+	if outfmt.IsJSON(ctx) {
+		return outfmt.WriteJSON(ctx, os.Stdout, map[string]any{"calendar": added})
+	}
+	u.Out().Printf("subscribed\t%s", added.Id)
+	u.Out().Printf("name\t%s", added.Summary)
+	u.Out().Printf("role\t%s", added.AccessRole)
+	return nil
+}
+
 type CalendarAclCmd struct {
 	CalendarID string `arg:"" name:"calendarId" help:"Calendar ID"`
 	Max        int64  `name:"max" aliases:"limit" help:"Max results" default:"100"`

internal/cmd/calendar_validate.go

@@ -27,6 +27,21 @@ func validateColorId(s string) (string, error) {
 	return s, nil
 }
 
+func validateCalendarColorId(s string) (string, error) {
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return "", nil
+	}
+	id, err := strconv.Atoi(s)
+	if err != nil {
+		return "", fmt.Errorf("invalid calendar color ID: %q (must be 1-24)", s)
+	}
+	if id < 1 || id > 24 {
+		return "", fmt.Errorf("calendar color ID must be 1-24 (got %d)", id)
+	}
+	return s, nil
+}
+
 func validateVisibility(s string) (string, error) {
 	s = strings.TrimSpace(strings.ToLower(s))
 	if s == "" {

internal/cmd/calendar_validate_test.go

@@ -17,6 +17,21 @@ func TestValidateColorID(t *testing.T) {
 	}
 }
 
+func TestValidateCalendarColorID(t *testing.T) {
+	if got, err := validateCalendarColorId(""); err != nil || got != "" {
+		t.Fatalf("expected empty ok, got %q %v", got, err)
+	}
+	if got, err := validateCalendarColorId("24"); err != nil || got != "24" {
+		t.Fatalf("expected valid id, got %q %v", got, err)
+	}
+	if _, err := validateCalendarColorId("25"); err == nil {
+		t.Fatalf("expected error for out of range")
+	}
+	if _, err := validateCalendarColorId("nope"); err == nil {
+		t.Fatalf("expected error for non-numeric")
+	}
+}
+
 func TestValidateVisibilityMore(t *testing.T) {
 	if got, err := validateVisibility(""); err != nil || got != "" {
 		t.Fatalf("expected empty ok, got %q %v", got, err)

internal/cmd/execute_calendar_test.go

@@ -64,3 +64,163 @@ func TestExecute_CalendarCalendars_JSON(t *testing.T) {
 		t.Fatalf("unexpected calendars: %#v", parsed.Calendars)
 	}
 }
+
+func TestExecute_CalendarSubscribe_JSON(t *testing.T) {
+	origNew := newCalendarService
+	t.Cleanup(func() { newCalendarService = origNew })
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !(strings.Contains(r.URL.Path, "calendarList") && r.Method == http.MethodPost) {
+			http.NotFound(w, r)
+			return
+		}
+		var req map[string]any
+		if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"id":         req["id"],
+			"summary":    "Test Calendar",
+			"accessRole": "reader",
+		})
+	}))
+	defer srv.Close()
+
+	svc, err := calendar.NewService(context.Background(),
+		option.WithoutAuthentication(),
+		option.WithHTTPClient(srv.Client()),
+		option.WithEndpoint(srv.URL+"/"),
+	)
+	if err != nil {
+		t.Fatalf("NewService: %v", err)
+	}
+	newCalendarService = func(context.Context, string) (*calendar.Service, error) { return svc, nil }
+
+	out := captureStdout(t, func() {
+		_ = captureStderr(t, func() {
+			if err := Execute([]string{"--json", "--account", "a@b.com", "calendar", "subscribe", "test@example.com"}); err != nil {
+				t.Fatalf("Execute: %v", err)
+			}
+		})
+	})
+
+	var parsed struct {
+		Calendar struct {
+			ID         string `json:"id"`
+			Summary    string `json:"summary"`
+			AccessRole string `json:"accessRole"`
+		} `json:"calendar"`
+	}
+	if err := json.Unmarshal([]byte(out), &parsed); err != nil {
+		t.Fatalf("json parse: %v\nout=%q", err, out)
+	}
+	if parsed.Calendar.ID != "test@example.com" {
+		t.Fatalf("unexpected calendar id: %s", parsed.Calendar.ID)
+	}
+	if parsed.Calendar.AccessRole != "reader" {
+		t.Fatalf("unexpected access role: %s", parsed.Calendar.AccessRole)
+	}
+}
+
+func TestExecute_CalendarSubscribe_Flags(t *testing.T) {
+	origNew := newCalendarService
+	t.Cleanup(func() { newCalendarService = origNew })
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !(strings.Contains(r.URL.Path, "calendarList") && r.Method == http.MethodPost) {
+			http.NotFound(w, r)
+			return
+		}
+
+		var req struct {
+			ID       string `json:"id"`
+			ColorID  string `json:"colorId"`
+			Hidden   bool   `json:"hidden"`
+			Selected bool   `json:"selected"`
+		}
+		if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+			return
+		}
+		if req.ID != "team@example.com" {
+			t.Fatalf("unexpected calendar id: %q", req.ID)
+		}
+		if req.ColorID != "24" {
+			t.Fatalf("unexpected color id: %q", req.ColorID)
+		}
+		if !req.Hidden {
+			t.Fatalf("expected hidden=true")
+		}
+		if req.Selected {
+			t.Fatalf("expected selected=false")
+		}
+
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"id":         req.ID,
+			"summary":    "Team Calendar",
+			"accessRole": "reader",
+		})
+	}))
+	defer srv.Close()
+
+	svc, err := calendar.NewService(context.Background(),
+		option.WithoutAuthentication(),
+		option.WithHTTPClient(srv.Client()),
+		option.WithEndpoint(srv.URL+"/"),
+	)
+	if err != nil {
+		t.Fatalf("NewService: %v", err)
+	}
+	newCalendarService = func(context.Context, string) (*calendar.Service, error) { return svc, nil }
+
+	if err := Execute([]string{"--account", "a@b.com", "calendar", "subscribe", "--color-id", "24", "--hidden", "--no-selected", "team@example.com"}); err != nil {
+		t.Fatalf("Execute: %v", err)
+	}
+}
+
+func TestExecute_CalendarSubscribe_Text(t *testing.T) {
+	origNew := newCalendarService
+	t.Cleanup(func() { newCalendarService = origNew })
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !(strings.Contains(r.URL.Path, "calendarList") && r.Method == http.MethodPost) {
+			http.NotFound(w, r)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"id":         "user@example.com",
+			"summary":    "User Calendar",
+			"accessRole": "writer",
+		})
+	}))
+	defer srv.Close()
+
+	svc, err := calendar.NewService(context.Background(),
+		option.WithoutAuthentication(),
+		option.WithHTTPClient(srv.Client()),
+		option.WithEndpoint(srv.URL+"/"),
+	)
+	if err != nil {
+		t.Fatalf("NewService: %v", err)
+	}
+	newCalendarService = func(context.Context, string) (*calendar.Service, error) { return svc, nil }
+
+	out := captureStdout(t, func() {
+		_ = captureStderr(t, func() {
+			if err := Execute([]string{"--account", "a@b.com", "calendar", "subscribe", "user@example.com"}); err != nil {
+				t.Fatalf("Execute: %v", err)
+			}
+		})
+	})
+
+	if !strings.Contains(out, "user@example.com") {
+		t.Fatalf("expected calendar id in output: %s", out)
+	}
+	if !strings.Contains(out, "writer") {
+		t.Fatalf("expected access role in output: %s", out)
+	}
+}