Deprecate pscale workflow in favor of move-tables

AGENTS.md

@@ -23,7 +23,7 @@ PlanetScale is a serverless database platform for **MySQL** (via Vitess), **Post
 
 On Vitess/MySQL, schema changes ship via **deploy requests**: online, non-blocking migrations you review and then deploy.
 
-Many commands are engine-specific, and some operations use different commands per engine. Schema changes: Vitess/MySQL uses `deploy-request`; Postgres and Neki branches apply DDL directly. Access: Vitess/MySQL uses `password`; Postgres and Neki use `role`. Resize: Vitess/MySQL uses `keyspace resize`; Postgres uses `branch resize`; Neki uses `branch config-profile`, `router`, and `shard`. Vitess/MySQL-only: `deploy-request`, `keyspace` (including `keyspace create-external`), `branch vtctld move-tables`, `connect`, `password`. `pscale workflow` will be deprecated soon; use `pscale branch vtctld move-tables` to move tables. Postgres-only: `traffic-control`, branch `switchover`/`parameters`, and `import d1`. Postgres and Neki: `role`, branch `maintenance`. Neki-only: `branch shard`, `config-profile`, `router`, `sidecar`, `admin`, `data-topology`, `changes`. The rest (`database`, `branch`, `sql`, `shell`, `insights`, `metrics`, `backup`, `org`, `auth`, `api`) work on all three.
+Many commands are engine-specific, and some operations use different commands per engine. Schema changes: Vitess/MySQL uses `deploy-request`; Postgres and Neki branches apply DDL directly. Access: Vitess/MySQL uses `password`; Postgres and Neki use `role`. Resize: Vitess/MySQL uses `keyspace resize`; Postgres uses `branch resize`; Neki uses `branch config-profile`, `router`, and `shard`. Vitess/MySQL-only: `deploy-request`, `keyspace` (including `keyspace create-external`), `branch vtctld move-tables`, `connect`, `password`. `pscale workflow` is deprecated; use `pscale branch vtctld move-tables` to move tables. Postgres-only: `traffic-control`, branch `switchover`/`parameters`, and `import d1`. Postgres and Neki: `role`, branch `maintenance`. Neki-only: `branch shard`, `config-profile`, `router`, `sidecar`, `admin`, `data-topology`, `changes`. The rest (`database`, `branch`, `sql`, `shell`, `insights`, `metrics`, `backup`, `org`, `auth`, `api`) work on all three.
 
 When a database is "weird" (slow, erroring, locked, bloated):
 
@@ -479,7 +479,7 @@ External create required flags: `--host`, `--source-database`, `--username`, `--
 
 ## Vitess MoveTables
 
-Copy tables between keyspaces with `pscale branch vtctld move-tables`. `pscale workflow` will be deprecated soon; prefer `move-tables` for new work. JSON output includes `next_steps` — follow those commands. Typical order: create the target keyspace (`keyspace create` or `keyspace create-external`), create the workflow, poll `status`, switch replica traffic, then primary traffic (ask the user first), then `complete --dry-run` and `complete` after approval. Create with `--auto-start=false` to leave streams stopped, then `start` when you are ready.
+Copy tables between keyspaces with `pscale branch vtctld move-tables`. `pscale workflow` is deprecated; use `move-tables` instead. JSON output includes `next_steps` — follow those commands. Typical order: create the target keyspace (`keyspace create` or `keyspace create-external`), create the workflow, poll `status`, switch replica traffic, then primary traffic (ask the user first), then `complete --dry-run` and `complete` after approval. Create with `--auto-start=false` to leave streams stopped, then `start` when you are ready.
 
 `--workflow` is the workflow name you choose. `--source-keyspace` and `--target-keyspace` are required on create. Pass `--tables t1,t2` or `--all-tables` (mutually exclusive). `list` without `--target-keyspace` returns workflows in every keyspace on the branch.
 

internal/cmd/branch/vtctld/list_tablets.go

@@ -17,9 +17,10 @@ func ListTabletsCmd(ch *cmdutil.Helper) *cobra.Command {
 	}
 
 	cmd := &cobra.Command{
-		Use:   "list-tablets <database> <branch>",
-		Short: "List tablets for a branch, grouped by keyspace and shard",
-		Args:  cmdutil.RequiredArgs("database", "branch"),
+		Use:    "list-tablets <database> <branch>",
+		Hidden: true,
+		Short:  "List tablets for a branch, grouped by keyspace and shard",
+		Args:   cmdutil.RequiredArgs("database", "branch"),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
 			database, branch := args[0], args[1]

internal/cmd/branch/vtctld/lookup_vindex.go

@@ -11,8 +11,9 @@ import (
 
 func LookupVindexCmd(ch *cmdutil.Helper) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "lookup-vindex <command>",
-		Short: "Manage Lookup Vindex operations",
+		Use:    "lookup-vindex <command>",
+		Short:  "Manage Lookup Vindex operations",
+		Hidden: true,
 	}
 
 	cmd.AddCommand(LookupVindexCreateCmd(ch))

internal/cmd/branch/vtctld/materialize.go

@@ -12,8 +12,9 @@ import (
 
 func MaterializeCmd(ch *cmdutil.Helper) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "materialize <command>",
-		Short: "Manage Materialize workflows",
+		Use:    "materialize <command>",
+		Short:  "Manage Materialize workflows",
+		Hidden: true,
 	}
 
 	cmd.AddCommand(MaterializeCreateCmd(ch))

internal/cmd/branch/vtctld/planned_reparent.go

@@ -27,8 +27,9 @@ func PlannedReparentShardCmd(ch *cmdutil.Helper) *cobra.Command {
 	}
 
 	cmd := &cobra.Command{
-		Use:   "planned-reparent-shard <database> <branch>",
-		Short: "Reparent a shard to a new primary",
+		Use:    "planned-reparent-shard <database> <branch>",
+		Hidden: true,
+		Short:  "Reparent a shard to a new primary",
 		Long: `Reparent a shard to a new primary using Vitess PlannedReparentShard.
 Both the old and new primaries must be up and running.
 

internal/cmd/branch/vtctld/vtctld.go

@@ -11,7 +11,6 @@ func VtctldCmd(ch *cmdutil.Helper) *cobra.Command {
 		Aliases: []string{"vtctld"},
 		Short:   "Run vtctl commands against a branch",
 		Long:    "Run vtctl commands against a branch. This command is only supported for Vitess databases.",
-		Hidden:  true,
 	}
 
 	cmd.AddCommand(MaterializeCmd(ch))

internal/cmd/dataimports/dataimports.go

@@ -5,14 +5,16 @@ import (
 	"github.com/spf13/cobra"
 )
 
+const deprecation = "import MySQL databases with \"pscale keyspace create-external\" and \"pscale branch vtctl move-tables\" instead. See https://planetscale.com/docs/vitess/imports/database-imports for more information."
+
 // DataImportsCmd handles data imports into PlanetScale.
 func DataImportsCmd(ch *cmdutil.Helper) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:               "data-imports <command>",
 		Short:             "Create, list, and delete branch data imports",
 		Long:              "Create, list, and delete branch data imports.\n\nThis command is only supported for Vitess databases.",
-		Deprecated:        "Vitess workflows are now available in the PlanetScale dashboard. See https://planetscale.com/docs/vitess/imports/database-imports for more information.",
-		PersistentPreRunE: cmdutil.CheckAuthentication(ch.Config),
+		Deprecated:        deprecation,
+		PersistentPreRunE: cmdutil.WarnDeprecated("data-imports", deprecation, cmdutil.CheckAuthentication(ch.Config)),
 	}
 
 	cmd.PersistentFlags().StringVar(&ch.Config.Organization, "org", ch.Config.Organization, "The organization for the current user")

internal/cmd/workflow/workflow.go

@@ -5,12 +5,15 @@ import (
 	"github.com/spf13/cobra"
 )
 
+const deprecation = "use \"pscale branch vtctl move-tables\" instead. See https://planetscale.com/docs/cli/move-tables for more information."
+
 func WorkflowCmd(ch *cmdutil.Helper) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:               "workflow <command>",
 		Short:             "Manage the workflows for PlanetScale databases",
+		Deprecated:        deprecation,
 		Long:              "Manage the workflows for PlanetScale databases.\n\nThis command is only supported for Vitess databases.",
-		PersistentPreRunE: cmdutil.CheckAuthentication(ch.Config),
+		PersistentPreRunE: cmdutil.WarnDeprecated("workflow", deprecation, cmdutil.CheckAuthentication(ch.Config)),
 	}
 
 	cmd.PersistentFlags().StringVar(&ch.Config.Organization, "org", ch.Config.Organization,

internal/cmdutil/cmdutil.go

@@ -154,6 +154,14 @@ func ExactArgs(reqArgs ...string) cobra.PositionalArgs {
 	}
 }
 
+// Cobra only prints Deprecated for the command being run, so subcommands of a deprecated group need this.
+func WarnDeprecated(name, message string, next func(cmd *cobra.Command, args []string) error) func(cmd *cobra.Command, args []string) error {
+	return func(cmd *cobra.Command, args []string) error {
+		fmt.Fprintf(cmd.ErrOrStderr(), "Command %q is deprecated, %s\n", name, message)
+		return next(cmd, args)
+	}
+}
+
 // CheckAuthentication checks whether the user is authenticated and returns a
 // actionable error message.
 func CheckAuthentication(cfg *config.Config) func(cmd *cobra.Command, args []string) error {