chore: import upstream snapshot with attribution

cmd/profile/add.go

@@ -0,0 +1,159 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package profile
+
+import (
+	"bufio"
+	"errors"
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/i18n"
+	"github.com/larksuite/cli/internal/output"
+)
+
+// NewCmdProfileAdd creates the profile add subcommand.
+func NewCmdProfileAdd(f *cmdutil.Factory) *cobra.Command {
+	var (
+		name           string
+		appID          string
+		appSecretStdin bool
+		brand          string
+		lang           string
+		use            bool
+	)
+
+	cmd := &cobra.Command{
+		Use:   "add",
+		Short: "Add a new profile",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return profileAddRun(f, name, appID, appSecretStdin, brand, lang, use)
+		},
+	}
+
+	cmd.Flags().StringVar(&name, "name", "", "profile name (required)")
+	cmd.Flags().StringVar(&appID, "app-id", "", "App ID (required)")
+	cmd.Flags().BoolVar(&appSecretStdin, "app-secret-stdin", false, "read App Secret from stdin")
+	cmd.Flags().StringVar(&brand, "brand", "feishu", "feishu or lark")
+	cmd.Flags().StringVar(&lang, "lang", "", "language preference (e.g. zh or zh_cn)")
+	cmd.Flags().BoolVar(&use, "use", false, "switch to this profile after adding")
+
+	_ = cmd.MarkFlagRequired("name")
+	_ = cmd.MarkFlagRequired("app-id")
+	cmdutil.SetRisk(cmd, "write")
+
+	return cmd
+}
+
+func profileAddRun(f *cmdutil.Factory, name, appID string, appSecretStdin bool, brand, lang string, useAfter bool) error {
+	if err := core.ValidateProfileName(name); err != nil {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "%v", err).
+			WithCause(err).
+			WithParam("--name")
+	}
+
+	langPref, err := cmdutil.ParseLangFlag(lang)
+	if err != nil {
+		return err
+	}
+	lang = string(langPref)
+
+	// Read secret from stdin
+	if !appSecretStdin {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "app secret must be provided via stdin").
+			WithHint("use --app-secret-stdin and pipe the secret").
+			WithParam("--app-secret-stdin")
+	}
+	scanner := bufio.NewScanner(f.IOStreams.In)
+	if !scanner.Scan() {
+		if err := scanner.Err(); err != nil {
+			return errs.NewValidationError(errs.SubtypeFailedPrecondition, "failed to read secret from stdin: %v", err).
+				WithCause(err).
+				WithParam("--app-secret-stdin")
+		}
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "stdin is empty, expected app secret").
+			WithHint("pipe the app secret to stdin").
+			WithParam("--app-secret-stdin")
+	}
+	appSecret := strings.TrimSpace(scanner.Text())
+	if appSecret == "" {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "app secret read from stdin is empty").
+			WithHint("pipe a non-empty app secret to stdin").
+			WithParam("--app-secret-stdin")
+	}
+
+	// Load or create config
+	multi, err := core.LoadMultiAppConfig()
+	if err != nil {
+		if !errors.Is(err, os.ErrNotExist) {
+			return errs.NewInternalError(errs.SubtypeFileIO, "failed to load config: %v", err).WithCause(err)
+		}
+		multi = &core.MultiAppConfig{}
+	}
+
+	// Check name uniqueness
+	if multi.FindApp(name) != nil {
+		return errs.NewValidationError(errs.SubtypeFailedPrecondition, "profile %q already exists", name).
+			WithHint("choose a different name, or remove the existing profile first").
+			WithParam("--name")
+	}
+
+	// Check app-id uniqueness — keychain stores secrets by appId, so
+	// multiple profiles sharing the same appId would collide on credentials.
+	for _, a := range multi.Apps {
+		if a.AppId == appID {
+			return errs.NewValidationError(errs.SubtypeFailedPrecondition, "app-id %q is already used by profile %q; each profile must have a unique app-id", appID, a.ProfileName()).
+				WithParam("--app-id")
+		}
+	}
+
+	// Store secret securely
+	secret, err := core.ForStorage(appID, core.PlainSecret(appSecret), f.Keychain)
+	if err != nil {
+		return errs.NewInternalError(errs.SubtypeStorage, "%v", err).WithCause(err)
+	}
+
+	parsedBrand := core.ParseBrand(brand)
+
+	// Capture current profile before appending (avoid setting PreviousApp to self)
+	var previousName string
+	if useAfter {
+		if currentApp := multi.CurrentAppConfig(""); currentApp != nil {
+			previousName = currentApp.ProfileName()
+		}
+	}
+
+	// Append profile
+	multi.Apps = append(multi.Apps, core.AppConfig{
+		Name:      name,
+		AppId:     appID,
+		AppSecret: secret,
+		Brand:     parsedBrand,
+		Lang:      i18n.Lang(lang),
+		Users:     []core.AppUser{},
+	})
+
+	if useAfter {
+		if previousName != "" {
+			multi.PreviousApp = previousName
+		}
+		multi.CurrentApp = name
+	}
+
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+	}
+
+	output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("Profile %q added (%s, %s)", name, appID, parsedBrand))
+	if useAfter {
+		output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("Switched to profile %q", name))
+	}
+	return nil
+}

cmd/profile/list.go

@@ -0,0 +1,87 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package profile
+
+import (
+	"errors"
+	"os"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/errs"
+	larkauth "github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
+)
+
+// profileListItem is the JSON output for a single profile entry.
+type profileListItem struct {
+	Name        string         `json:"name"`
+	AppID       string         `json:"appId"`
+	Brand       core.LarkBrand `json:"brand"`
+	Active      bool           `json:"active"`
+	User        string         `json:"user,omitempty"`
+	TokenStatus string         `json:"tokenStatus,omitempty"`
+}
+
+// NewCmdProfileList creates the profile list subcommand.
+func NewCmdProfileList(f *cmdutil.Factory) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "list",
+		Short: "List all profiles",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return profileListRun(f)
+		},
+	}
+	cmdutil.SetRisk(cmd, "read")
+	return cmd
+}
+
+func profileListRun(f *cmdutil.Factory) error {
+	multi, err := core.LoadMultiAppConfig()
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			output.PrintJson(f.IOStreams.Out, []profileListItem{})
+			return nil
+		}
+		return errs.NewValidationError(errs.SubtypeFailedPrecondition, "failed to load config: %v", err).WithCause(err)
+	}
+	if multi == nil || len(multi.Apps) == 0 {
+		output.PrintJson(f.IOStreams.Out, []profileListItem{})
+		return nil
+	}
+
+	// Intentionally uses "" to show the persistent active profile, not the ephemeral --profile override.
+	currentApp := multi.CurrentAppConfig("")
+	currentName := ""
+	if currentApp != nil {
+		currentName = currentApp.ProfileName()
+	}
+
+	items := make([]profileListItem, 0, len(multi.Apps))
+	for i := range multi.Apps {
+		app := &multi.Apps[i]
+		name := app.ProfileName()
+
+		item := profileListItem{
+			Name:   name,
+			AppID:  app.AppId,
+			Brand:  app.Brand,
+			Active: name == currentName,
+		}
+
+		if len(app.Users) > 0 {
+			item.User = app.Users[0].UserName
+			stored := larkauth.GetStoredToken(app.AppId, app.Users[0].UserOpenId)
+			if stored != nil {
+				item.TokenStatus = larkauth.TokenStatus(stored)
+			}
+		}
+
+		items = append(items, item)
+	}
+	output.PrintJson(f.IOStreams.Out, items)
+	return nil
+}

cmd/profile/profile.go

@@ -0,0 +1,29 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package profile
+
+import (
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+)
+
+// NewCmdProfile creates the profile command with subcommands.
+func NewCmdProfile(f *cmdutil.Factory) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "profile",
+		Short: "Manage configuration profiles",
+	}
+	cmdutil.DisableAuthCheck(cmd)
+	cmdutil.SetTips(cmd, []string{
+		"AI agents: Do NOT switch or remove profiles unless the user explicitly asks.",
+	})
+
+	cmd.AddCommand(NewCmdProfileList(f))
+	cmd.AddCommand(NewCmdProfileUse(f))
+	cmd.AddCommand(NewCmdProfileAdd(f))
+	cmd.AddCommand(NewCmdProfileRemove(f))
+	cmd.AddCommand(NewCmdProfileRename(f))
+	return cmd
+}

cmd/profile/profile_test.go

@@ -0,0 +1,642 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package profile
+
+import (
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/i18n"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+type failRenameFS struct {
+	vfs.OsFs
+	err error
+}
+
+func (fs *failRenameFS) Rename(oldpath, newpath string) error {
+	return fs.err
+}
+
+func setupProfileConfigDir(t *testing.T) string {
+	t.Helper()
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	return dir
+}
+
+func TestProfileAddRun_InvalidExistingConfigReturnsError(t *testing.T) {
+	dir := setupProfileConfigDir(t)
+	if err := os.WriteFile(filepath.Join(dir, "config.json"), []byte("{invalid json"), 0600); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	f.IOStreams.In = strings.NewReader("secret\n")
+
+	err := profileAddRun(f, "test", "app-test", true, "feishu", "zh", false)
+	if err == nil {
+		t.Fatal("expected error for invalid existing config")
+	}
+	if !strings.Contains(err.Error(), "failed to load config") {
+		t.Fatalf("error = %v, want failed to load config", err)
+	}
+	var internalErr *errs.InternalError
+	if !errors.As(err, &internalErr) {
+		t.Fatalf("error type = %T, want *errs.InternalError; err=%v", err, err)
+	}
+	if internalErr.Subtype != errs.SubtypeFileIO {
+		t.Fatalf("subtype = %q, want %q", internalErr.Subtype, errs.SubtypeFileIO)
+	}
+	if code := output.ExitCodeOf(err); code != output.ExitInternal {
+		t.Fatalf("exit code = %d, want %d (ExitInternal)", code, output.ExitInternal)
+	}
+}
+
+// TestProfileAddRun_Lang covers the unified --lang contract on profile add:
+// short codes and Feishu locales both canonicalize to the same stored locale,
+// empty stores no preference, and an unrecognized value errors.
+func TestProfileAddRun_Lang(t *testing.T) {
+	t.Run("short and locale canonicalize and persist alike", func(t *testing.T) {
+		for _, in := range []string{"ja", "ja_jp"} {
+			setupProfileConfigDir(t)
+			f, _, _, _ := cmdutil.TestFactory(t, nil)
+			f.IOStreams.In = strings.NewReader("secret\n")
+			if err := profileAddRun(f, "p", "app-p", true, "feishu", in, false); err != nil {
+				t.Fatalf("--lang %q: profileAddRun() error = %v", in, err)
+			}
+			saved, err := core.LoadMultiAppConfig()
+			if err != nil {
+				t.Fatalf("LoadMultiAppConfig() error = %v", err)
+			}
+			if app := saved.FindApp("p"); app == nil || app.Lang != i18n.LangJaJP {
+				t.Errorf("--lang %q: stored Lang = %v, want %q", in, app, i18n.LangJaJP)
+			}
+		}
+	})
+
+	t.Run("empty stores no preference", func(t *testing.T) {
+		setupProfileConfigDir(t)
+		f, _, _, _ := cmdutil.TestFactory(t, nil)
+		f.IOStreams.In = strings.NewReader("secret\n")
+		if err := profileAddRun(f, "p", "app-p", true, "feishu", "", false); err != nil {
+			t.Fatalf("profileAddRun() error = %v", err)
+		}
+		saved, _ := core.LoadMultiAppConfig()
+		if app := saved.FindApp("p"); app == nil || app.Lang != "" {
+			t.Errorf("stored Lang = %v, want \"\" (unset)", app)
+		}
+	})
+
+	t.Run("invalid lang errors", func(t *testing.T) {
+		setupProfileConfigDir(t)
+		f, _, _, _ := cmdutil.TestFactory(t, nil)
+		f.IOStreams.In = strings.NewReader("secret\n")
+		err := profileAddRun(f, "p", "app-p", true, "feishu", "ZH", false)
+		if err == nil {
+			t.Fatal("expected validation error for --lang ZH, got nil")
+		}
+		var valErr *errs.ValidationError
+		if !errors.As(err, &valErr) || output.ExitCodeOf(err) != output.ExitValidation {
+			t.Fatalf("expected typed validation error with ExitValidation, got %T: %v", err, err)
+		}
+	})
+}
+
+func TestProfileAddRun_UseAfterUpdatesCurrentAndPrevious(t *testing.T) {
+	setupProfileConfigDir(t)
+	multi := &core.MultiAppConfig{
+		CurrentApp: "default",
+		Apps: []core.AppConfig{
+			{Name: "default", AppId: "app-default", AppSecret: core.PlainSecret("secret-default"), Brand: core.BrandFeishu},
+		},
+	}
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		t.Fatalf("SaveMultiAppConfig() error = %v", err)
+	}
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	f.IOStreams.In = strings.NewReader("secret-new\n")
+
+	if err := profileAddRun(f, "target", "app-target", true, "lark", "en", true); err != nil {
+		t.Fatalf("profileAddRun() error = %v", err)
+	}
+
+	saved, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatalf("LoadMultiAppConfig() error = %v", err)
+	}
+	if saved.CurrentApp != "target" {
+		t.Fatalf("CurrentApp = %q, want %q", saved.CurrentApp, "target")
+	}
+	if saved.PreviousApp != "default" {
+		t.Fatalf("PreviousApp = %q, want %q", saved.PreviousApp, "default")
+	}
+	if len(saved.Apps) != 2 {
+		t.Fatalf("len(Apps) = %d, want 2", len(saved.Apps))
+	}
+}
+
+func TestProfileRemoveRun_RemovesCurrentProfileAndSwitchesToFirstRemaining(t *testing.T) {
+	setupProfileConfigDir(t)
+	multi := &core.MultiAppConfig{
+		CurrentApp:  "target",
+		PreviousApp: "default",
+		Apps: []core.AppConfig{
+			{Name: "default", AppId: "app-default", AppSecret: core.PlainSecret("secret-default"), Brand: core.BrandFeishu},
+			{Name: "target", AppId: "app-target", AppSecret: core.PlainSecret("secret-target"), Brand: core.BrandLark},
+		},
+	}
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		t.Fatalf("SaveMultiAppConfig() error = %v", err)
+	}
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	if err := profileRemoveRun(f, "target"); err != nil {
+		t.Fatalf("profileRemoveRun() error = %v", err)
+	}
+
+	saved, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatalf("LoadMultiAppConfig() error = %v", err)
+	}
+	if saved.CurrentApp != "default" {
+		t.Fatalf("CurrentApp = %q, want %q", saved.CurrentApp, "default")
+	}
+	if saved.PreviousApp != "default" {
+		t.Fatalf("PreviousApp = %q, want %q", saved.PreviousApp, "default")
+	}
+	if len(saved.Apps) != 1 || saved.Apps[0].ProfileName() != "default" {
+		t.Fatalf("remaining apps = %#v, want only default", saved.Apps)
+	}
+}
+
+func TestProfileRenameRun_UpdatesCurrentAndPreviousReferences(t *testing.T) {
+	setupProfileConfigDir(t)
+	multi := &core.MultiAppConfig{
+		CurrentApp:  "old",
+		PreviousApp: "old",
+		Apps: []core.AppConfig{{
+			Name:      "old",
+			AppId:     "app-old",
+			AppSecret: core.PlainSecret("secret-old"),
+			Brand:     core.BrandFeishu,
+		}},
+	}
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		t.Fatalf("SaveMultiAppConfig() error = %v", err)
+	}
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	if err := profileRenameRun(f, "old", "new"); err != nil {
+		t.Fatalf("profileRenameRun() error = %v", err)
+	}
+
+	saved, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatalf("LoadMultiAppConfig() error = %v", err)
+	}
+	if saved.CurrentApp != "new" {
+		t.Fatalf("CurrentApp = %q, want %q", saved.CurrentApp, "new")
+	}
+	if saved.PreviousApp != "new" {
+		t.Fatalf("PreviousApp = %q, want %q", saved.PreviousApp, "new")
+	}
+	if saved.Apps[0].ProfileName() != "new" {
+		t.Fatalf("ProfileName() = %q, want %q", saved.Apps[0].ProfileName(), "new")
+	}
+}
+
+func TestProfileRenameRun_AllowsRenameToOwnAppID(t *testing.T) {
+	setupProfileConfigDir(t)
+	multi := &core.MultiAppConfig{
+		CurrentApp:  "old",
+		PreviousApp: "old",
+		Apps: []core.AppConfig{{
+			Name:      "old",
+			AppId:     "app-old",
+			AppSecret: core.PlainSecret("secret-old"),
+			Brand:     core.BrandFeishu,
+		}},
+	}
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		t.Fatalf("SaveMultiAppConfig() error = %v", err)
+	}
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	if err := profileRenameRun(f, "old", "app-old"); err != nil {
+		t.Fatalf("profileRenameRun() error = %v", err)
+	}
+
+	saved, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatalf("LoadMultiAppConfig() error = %v", err)
+	}
+	if saved.CurrentApp != "app-old" {
+		t.Fatalf("CurrentApp = %q, want %q", saved.CurrentApp, "app-old")
+	}
+	if saved.PreviousApp != "app-old" {
+		t.Fatalf("PreviousApp = %q, want %q", saved.PreviousApp, "app-old")
+	}
+	if saved.Apps[0].Name != "app-old" {
+		t.Fatalf("Name = %q, want %q", saved.Apps[0].Name, "app-old")
+	}
+}
+
+func TestProfileUseRun_ToggleBackUsesPreviousProfile(t *testing.T) {
+	setupProfileConfigDir(t)
+	multi := &core.MultiAppConfig{
+		CurrentApp:  "default",
+		PreviousApp: "target",
+		Apps: []core.AppConfig{
+			{Name: "default", AppId: "app-default", AppSecret: core.PlainSecret("secret-default"), Brand: core.BrandFeishu},
+			{Name: "target", AppId: "app-target", AppSecret: core.PlainSecret("secret-target"), Brand: core.BrandLark},
+		},
+	}
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		t.Fatalf("SaveMultiAppConfig() error = %v", err)
+	}
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	if err := profileUseRun(f, "-"); err != nil {
+		t.Fatalf("profileUseRun() error = %v", err)
+	}
+
+	saved, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatalf("LoadMultiAppConfig() error = %v", err)
+	}
+	if saved.CurrentApp != "target" {
+		t.Fatalf("CurrentApp = %q, want %q", saved.CurrentApp, "target")
+	}
+	if saved.PreviousApp != "default" {
+		t.Fatalf("PreviousApp = %q, want %q", saved.PreviousApp, "default")
+	}
+}
+
+func TestProfileListRun_OutputsProfiles(t *testing.T) {
+	setupProfileConfigDir(t)
+	multi := &core.MultiAppConfig{
+		CurrentApp: "default",
+		Apps: []core.AppConfig{
+			{Name: "default", AppId: "app-default", AppSecret: core.PlainSecret("secret-default"), Brand: core.BrandFeishu},
+			{Name: "target", AppId: "app-target", AppSecret: core.PlainSecret("secret-target"), Brand: core.BrandLark},
+		},
+	}
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		t.Fatalf("SaveMultiAppConfig() error = %v", err)
+	}
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
+	if err := profileListRun(f); err != nil {
+		t.Fatalf("profileListRun() error = %v", err)
+	}
+
+	var got []profileListItem
+	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
+		t.Fatalf("Unmarshal() error = %v; output=%s", err, stdout.String())
+	}
+	if len(got) != 2 {
+		t.Fatalf("len(got) = %d, want 2", len(got))
+	}
+	if got[0].Name != "default" || !got[0].Active {
+		t.Fatalf("got[0] = %#v, want active default profile", got[0])
+	}
+	if got[1].Name != "target" || got[1].Active {
+		t.Fatalf("got[1] = %#v, want inactive target profile", got[1])
+	}
+}
+
+func TestProfileListRun_NotConfiguredReturnsEmptyList(t *testing.T) {
+	setupProfileConfigDir(t)
+
+	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
+	if err := profileListRun(f); err != nil {
+		t.Fatalf("profileListRun() error = %v", err)
+	}
+
+	var got []profileListItem
+	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
+		t.Fatalf("Unmarshal() error = %v; output=%s", err, stdout.String())
+	}
+	if len(got) != 0 {
+		t.Fatalf("len(got) = %d, want 0", len(got))
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr = %q, want empty", stderr.String())
+	}
+}
+
+func TestProfileRemoveRun_SaveFailureReturnsStructuredError(t *testing.T) {
+	setupProfileConfigDir(t)
+	multi := &core.MultiAppConfig{
+		CurrentApp: "target",
+		Apps: []core.AppConfig{
+			{Name: "default", AppId: "app-default", AppSecret: core.PlainSecret("secret-default"), Brand: core.BrandFeishu},
+			{Name: "target", AppId: "app-target", AppSecret: core.PlainSecret("secret-target"), Brand: core.BrandLark},
+		},
+	}
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		t.Fatalf("SaveMultiAppConfig() error = %v", err)
+	}
+
+	restoreFS := vfs.DefaultFS
+	vfs.DefaultFS = &failRenameFS{err: errors.New("rename boom")}
+	t.Cleanup(func() { vfs.DefaultFS = restoreFS })
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	err := profileRemoveRun(f, "target")
+	if err == nil {
+		t.Fatal("expected save error")
+	}
+	assertInternalExitError(t, err, "failed to save config")
+}
+
+func TestProfileRenameRun_SaveFailureReturnsStructuredError(t *testing.T) {
+	setupProfileConfigDir(t)
+	multi := &core.MultiAppConfig{
+		CurrentApp: "old",
+		Apps: []core.AppConfig{{
+			Name:      "old",
+			AppId:     "app-old",
+			AppSecret: core.PlainSecret("secret-old"),
+			Brand:     core.BrandFeishu,
+		}},
+	}
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		t.Fatalf("SaveMultiAppConfig() error = %v", err)
+	}
+
+	restoreFS := vfs.DefaultFS
+	vfs.DefaultFS = &failRenameFS{err: errors.New("rename boom")}
+	t.Cleanup(func() { vfs.DefaultFS = restoreFS })
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	err := profileRenameRun(f, "old", "new")
+	if err == nil {
+		t.Fatal("expected save error")
+	}
+	assertInternalExitError(t, err, "failed to save config")
+}
+
+func TestProfileUseRun_SaveFailureReturnsStructuredError(t *testing.T) {
+	setupProfileConfigDir(t)
+	multi := &core.MultiAppConfig{
+		CurrentApp: "default",
+		Apps: []core.AppConfig{
+			{Name: "default", AppId: "app-default", AppSecret: core.PlainSecret("secret-default"), Brand: core.BrandFeishu},
+			{Name: "target", AppId: "app-target", AppSecret: core.PlainSecret("secret-target"), Brand: core.BrandLark},
+		},
+	}
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		t.Fatalf("SaveMultiAppConfig() error = %v", err)
+	}
+
+	restoreFS := vfs.DefaultFS
+	vfs.DefaultFS = &failRenameFS{err: errors.New("rename boom")}
+	t.Cleanup(func() { vfs.DefaultFS = restoreFS })
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	err := profileUseRun(f, "target")
+	if err == nil {
+		t.Fatal("expected save error")
+	}
+	assertInternalExitError(t, err, "failed to save config")
+}
+
+func assertInternalExitError(t *testing.T, err error, wantMsg string) {
+	t.Helper()
+
+	var internalErr *errs.InternalError
+	if !errors.As(err, &internalErr) {
+		t.Fatalf("error type = %T, want *errs.InternalError; err=%v", err, err)
+	}
+	if internalErr.Subtype != errs.SubtypeStorage {
+		t.Fatalf("subtype = %q, want %q", internalErr.Subtype, errs.SubtypeStorage)
+	}
+	if internalErr.Cause == nil {
+		t.Fatalf("cause = nil, want wrapped underlying error")
+	}
+	if !strings.Contains(internalErr.Message, wantMsg) {
+		t.Fatalf("message = %q, want contains %q", internalErr.Message, wantMsg)
+	}
+	if code := output.ExitCodeOf(err); code != output.ExitInternal {
+		t.Fatalf("exit code = %d, want %d (ExitInternal)", code, output.ExitInternal)
+	}
+}
+
+// assertValidationError asserts err is a typed *errs.ValidationError with the
+// given subtype, message fragment, and exit code 2.
+func assertValidationError(t *testing.T, err error, wantSubtype errs.Subtype, wantMsg string) *errs.ValidationError {
+	t.Helper()
+
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	var valErr *errs.ValidationError
+	if !errors.As(err, &valErr) {
+		t.Fatalf("error type = %T, want *errs.ValidationError; err=%v", err, err)
+	}
+	if valErr.Subtype != wantSubtype {
+		t.Fatalf("subtype = %q, want %q", valErr.Subtype, wantSubtype)
+	}
+	if !strings.Contains(valErr.Message, wantMsg) {
+		t.Fatalf("message = %q, want contains %q", valErr.Message, wantMsg)
+	}
+	if code := output.ExitCodeOf(err); code != output.ExitValidation {
+		t.Fatalf("exit code = %d, want %d (ExitValidation)", code, output.ExitValidation)
+	}
+	return valErr
+}
+
+func saveTwoProfiles(t *testing.T) {
+	t.Helper()
+	multi := &core.MultiAppConfig{
+		CurrentApp: "default",
+		Apps: []core.AppConfig{
+			{Name: "default", AppId: "app-default", AppSecret: core.PlainSecret("secret-default"), Brand: core.BrandFeishu},
+			{Name: "target", AppId: "app-target", AppSecret: core.PlainSecret("secret-target"), Brand: core.BrandLark},
+		},
+	}
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		t.Fatalf("SaveMultiAppConfig() error = %v", err)
+	}
+}
+
+func TestProfileAddRun_ValidationErrors(t *testing.T) {
+	t.Run("invalid profile name", func(t *testing.T) {
+		setupProfileConfigDir(t)
+		f, _, _, _ := cmdutil.TestFactory(t, nil)
+		f.IOStreams.In = strings.NewReader("secret\n")
+		err := profileAddRun(f, "bad name!", "app-x", true, "feishu", "", false)
+		valErr := assertValidationError(t, err, errs.SubtypeInvalidArgument, "")
+		if valErr.Param != "--name" {
+			t.Fatalf("param = %q, want %q", valErr.Param, "--name")
+		}
+		if valErr.Cause == nil {
+			t.Fatal("cause = nil, want wrapped validation error")
+		}
+	})
+
+	t.Run("missing app-secret-stdin flag", func(t *testing.T) {
+		setupProfileConfigDir(t)
+		f, _, _, _ := cmdutil.TestFactory(t, nil)
+		err := profileAddRun(f, "p", "app-x", false, "feishu", "", false)
+		valErr := assertValidationError(t, err, errs.SubtypeInvalidArgument, "app secret must be provided via stdin")
+		if valErr.Param != "--app-secret-stdin" {
+			t.Fatalf("param = %q, want %q", valErr.Param, "--app-secret-stdin")
+		}
+		if valErr.Hint == "" {
+			t.Fatal("hint is empty, want actionable hint")
+		}
+	})
+
+	t.Run("empty stdin", func(t *testing.T) {
+		setupProfileConfigDir(t)
+		f, _, _, _ := cmdutil.TestFactory(t, nil)
+		f.IOStreams.In = strings.NewReader("")
+		err := profileAddRun(f, "p", "app-x", true, "feishu", "", false)
+		valErr := assertValidationError(t, err, errs.SubtypeInvalidArgument, "stdin is empty")
+		if valErr.Param != "--app-secret-stdin" {
+			t.Fatalf("param = %q, want %q", valErr.Param, "--app-secret-stdin")
+		}
+	})
+
+	t.Run("blank secret on stdin", func(t *testing.T) {
+		setupProfileConfigDir(t)
+		f, _, _, _ := cmdutil.TestFactory(t, nil)
+		f.IOStreams.In = strings.NewReader("   \n")
+		err := profileAddRun(f, "p", "app-x", true, "feishu", "", false)
+		assertValidationError(t, err, errs.SubtypeInvalidArgument, "app secret read from stdin is empty")
+	})
+
+	t.Run("duplicate profile name", func(t *testing.T) {
+		setupProfileConfigDir(t)
+		saveTwoProfiles(t)
+		f, _, _, _ := cmdutil.TestFactory(t, nil)
+		f.IOStreams.In = strings.NewReader("secret\n")
+		err := profileAddRun(f, "default", "app-new", true, "feishu", "", false)
+		valErr := assertValidationError(t, err, errs.SubtypeFailedPrecondition, `profile "default" already exists`)
+		if valErr.Param != "--name" {
+			t.Fatalf("param = %q, want %q", valErr.Param, "--name")
+		}
+	})
+
+	t.Run("duplicate app-id", func(t *testing.T) {
+		setupProfileConfigDir(t)
+		saveTwoProfiles(t)
+		f, _, _, _ := cmdutil.TestFactory(t, nil)
+		f.IOStreams.In = strings.NewReader("secret\n")
+		err := profileAddRun(f, "fresh", "app-default", true, "feishu", "", false)
+		valErr := assertValidationError(t, err, errs.SubtypeFailedPrecondition, "already used by profile")
+		if valErr.Param != "--app-id" {
+			t.Fatalf("param = %q, want %q", valErr.Param, "--app-id")
+		}
+	})
+}
+
+func TestProfileUseRun_ValidationErrors(t *testing.T) {
+	t.Run("no previous profile for toggle", func(t *testing.T) {
+		setupProfileConfigDir(t)
+		saveTwoProfiles(t)
+		f, _, _, _ := cmdutil.TestFactory(t, nil)
+		err := profileUseRun(f, "-")
+		valErr := assertValidationError(t, err, errs.SubtypeFailedPrecondition, "no previous profile to switch back to")
+		if valErr.Hint == "" {
+			t.Fatal("hint is empty, want actionable hint")
+		}
+	})
+
+	t.Run("profile not found", func(t *testing.T) {
+		setupProfileConfigDir(t)
+		saveTwoProfiles(t)
+		f, _, _, _ := cmdutil.TestFactory(t, nil)
+		err := profileUseRun(f, "ghost")
+		assertValidationError(t, err, errs.SubtypeInvalidArgument, `profile "ghost" not found`)
+	})
+}
+
+func TestProfileRenameRun_ValidationErrors(t *testing.T) {
+	t.Run("invalid new name", func(t *testing.T) {
+		setupProfileConfigDir(t)
+		saveTwoProfiles(t)
+		f, _, _, _ := cmdutil.TestFactory(t, nil)
+		err := profileRenameRun(f, "default", "bad name!")
+		valErr := assertValidationError(t, err, errs.SubtypeInvalidArgument, "")
+		if valErr.Cause == nil {
+			t.Fatal("cause = nil, want wrapped validation error")
+		}
+	})
+
+	t.Run("old profile not found", func(t *testing.T) {
+		setupProfileConfigDir(t)
+		saveTwoProfiles(t)
+		f, _, _, _ := cmdutil.TestFactory(t, nil)
+		err := profileRenameRun(f, "ghost", "fresh")
+		assertValidationError(t, err, errs.SubtypeInvalidArgument, `profile "ghost" not found`)
+	})
+
+	t.Run("new name already exists", func(t *testing.T) {
+		setupProfileConfigDir(t)
+		saveTwoProfiles(t)
+		f, _, _, _ := cmdutil.TestFactory(t, nil)
+		err := profileRenameRun(f, "default", "target")
+		valErr := assertValidationError(t, err, errs.SubtypeFailedPrecondition, `profile "target" already exists`)
+		if valErr.Hint == "" {
+			t.Fatal("hint is empty, want actionable hint")
+		}
+	})
+}
+
+func TestProfileRemoveRun_ValidationErrors(t *testing.T) {
+	t.Run("profile not found", func(t *testing.T) {
+		setupProfileConfigDir(t)
+		saveTwoProfiles(t)
+		f, _, _, _ := cmdutil.TestFactory(t, nil)
+		err := profileRemoveRun(f, "ghost")
+		assertValidationError(t, err, errs.SubtypeInvalidArgument, `profile "ghost" not found`)
+	})
+
+	t.Run("cannot remove the only profile", func(t *testing.T) {
+		setupProfileConfigDir(t)
+		multi := &core.MultiAppConfig{
+			CurrentApp: "solo",
+			Apps: []core.AppConfig{
+				{Name: "solo", AppId: "app-solo", AppSecret: core.PlainSecret("secret-solo"), Brand: core.BrandFeishu},
+			},
+		}
+		if err := core.SaveMultiAppConfig(multi); err != nil {
+			t.Fatalf("SaveMultiAppConfig() error = %v", err)
+		}
+		f, _, _, _ := cmdutil.TestFactory(t, nil)
+		err := profileRemoveRun(f, "solo")
+		valErr := assertValidationError(t, err, errs.SubtypeFailedPrecondition, "cannot remove the only profile")
+		if valErr.Hint == "" {
+			t.Fatal("hint is empty, want actionable hint")
+		}
+	})
+}
+
+func TestProfileListRun_InvalidConfigReturnsValidationError(t *testing.T) {
+	dir := setupProfileConfigDir(t)
+	if err := os.WriteFile(filepath.Join(dir, "config.json"), []byte("{invalid json"), 0600); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	err := profileListRun(f)
+	valErr := assertValidationError(t, err, errs.SubtypeFailedPrecondition, "failed to load config")
+	if valErr.Cause == nil {
+		t.Fatal("cause = nil, want wrapped load error")
+	}
+}

cmd/profile/remove.go

@@ -0,0 +1,81 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package profile
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/errs"
+	larkauth "github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
+)
+
+// NewCmdProfileRemove creates the profile remove subcommand.
+func NewCmdProfileRemove(f *cmdutil.Factory) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "remove <name>",
+		Short: "Remove a profile",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return profileRemoveRun(f, args[0])
+		},
+	}
+	cmdutil.SetTips(cmd, []string{
+		"AI agents: Do NOT remove profiles unless the user explicitly asks. This is destructive and clears all associated credentials.",
+	})
+	cmdutil.SetRisk(cmd, "write")
+	return cmd
+}
+
+func profileRemoveRun(f *cmdutil.Factory, name string) error {
+	multi, err := core.LoadOrNotConfigured()
+	if err != nil {
+		return err
+	}
+
+	idx := multi.FindAppIndex(name)
+	if idx < 0 {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "profile %q not found, available profiles: %s", name, strings.Join(multi.ProfileNames(), ", "))
+	}
+
+	if len(multi.Apps) == 1 {
+		return errs.NewValidationError(errs.SubtypeFailedPrecondition, "cannot remove the only profile").
+			WithHint("add another profile first: lark-cli profile add")
+	}
+
+	app := &multi.Apps[idx]
+	removedName := app.ProfileName()
+	appId := app.AppId
+	appSecret := app.AppSecret
+	users := app.Users
+
+	// Remove from slice
+	multi.Apps = append(multi.Apps[:idx], multi.Apps[idx+1:]...)
+
+	// Fix currentApp / previousApp references
+	if multi.CurrentApp == removedName {
+		multi.CurrentApp = multi.Apps[0].ProfileName()
+	}
+	if multi.PreviousApp == removedName {
+		multi.PreviousApp = ""
+	}
+
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+	}
+
+	// Best-effort credential cleanup after config commit
+	core.RemoveSecretStore(appSecret, f.Keychain)
+	for _, user := range users {
+		larkauth.RemoveStoredToken(appId, user.UserOpenId)
+	}
+
+	output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("Profile %q removed", removedName))
+	return nil
+}

cmd/profile/rename.go

@@ -0,0 +1,76 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package profile
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
+)
+
+// NewCmdProfileRename creates the profile rename subcommand.
+func NewCmdProfileRename(f *cmdutil.Factory) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "rename <old> <new>",
+		Short: "Rename a profile",
+		Args:  cobra.ExactArgs(2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return profileRenameRun(f, args[0], args[1])
+		},
+	}
+	cmdutil.SetRisk(cmd, "write")
+	return cmd
+}
+
+func profileRenameRun(f *cmdutil.Factory, oldName, newName string) error {
+	if err := core.ValidateProfileName(newName); err != nil {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "%v", err).WithCause(err)
+	}
+
+	multi, err := core.LoadOrNotConfigured()
+	if err != nil {
+		return err
+	}
+
+	idx := multi.FindAppIndex(oldName)
+	if idx < 0 {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "profile %q not found, available profiles: %s", oldName, strings.Join(multi.ProfileNames(), ", "))
+	}
+
+	// Check new name uniqueness across other profiles, allowing renames to this
+	// profile's own appId or current name.
+	for i := range multi.Apps {
+		if i == idx {
+			continue
+		}
+		if multi.Apps[i].Name == newName || multi.Apps[i].AppId == newName {
+			return errs.NewValidationError(errs.SubtypeFailedPrecondition, "profile %q already exists", newName).
+				WithHint("choose a different name")
+		}
+	}
+
+	oldProfileName := multi.Apps[idx].ProfileName()
+	multi.Apps[idx].Name = newName
+
+	// Update currentApp / previousApp references
+	if multi.CurrentApp == oldProfileName {
+		multi.CurrentApp = newName
+	}
+	if multi.PreviousApp == oldProfileName {
+		multi.PreviousApp = newName
+	}
+
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+	}
+
+	output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("Profile renamed: %q -> %q", oldProfileName, newName))
+	return nil
+}

cmd/profile/use.go

@@ -0,0 +1,76 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package profile
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
+)
+
+// NewCmdProfileUse creates the profile use subcommand.
+func NewCmdProfileUse(f *cmdutil.Factory) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "use <name>",
+		Short: "Switch to a profile (use '-' to toggle back)",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return profileUseRun(f, args[0])
+		},
+	}
+	cmdutil.SetTips(cmd, []string{
+		"AI agents: Do NOT switch profiles unless the user explicitly asks.",
+	})
+	cmdutil.SetRisk(cmd, "write")
+	return cmd
+}
+
+func profileUseRun(f *cmdutil.Factory, name string) error {
+	multi, err := core.LoadOrNotConfigured()
+	if err != nil {
+		return err
+	}
+
+	// Handle "-" for toggle-back
+	if name == "-" {
+		if multi.PreviousApp == "" {
+			return errs.NewValidationError(errs.SubtypeFailedPrecondition, "no previous profile to switch back to").
+				WithHint("switch to a profile by name first: lark-cli profile use <name>")
+		}
+		name = multi.PreviousApp
+	}
+
+	app := multi.FindApp(name)
+	if app == nil {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "profile %q not found, available profiles: %s", name, strings.Join(multi.ProfileNames(), ", "))
+	}
+
+	targetName := app.ProfileName()
+
+	// Short-circuit if already on the target profile
+	currentApp := multi.CurrentAppConfig("")
+	if currentApp != nil && currentApp.ProfileName() == targetName {
+		fmt.Fprintf(f.IOStreams.ErrOut, "Already on profile %q\n", targetName)
+		return nil
+	}
+
+	// Update previous and current
+	if currentApp != nil {
+		multi.PreviousApp = currentApp.ProfileName()
+	}
+	multi.CurrentApp = targetName
+
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		return errs.NewInternalError(errs.SubtypeStorage, "failed to save config: %v", err).WithCause(err)
+	}
+
+	output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("Switched to profile %q (%s, %s)", targetName, app.AppId, app.Brand))
+	return nil
+}