Clean up backup, restore, and collection commands

[austin-denoble]

Summary

This PR makes two categories of changes ahead of v1: a command structure reorganization to establish permanent homes for backup, restore, and collection resources, and a set of correctness fixes found during an audit of the CLI against the 2025-10 control plane API spec.

---

Command restructuring

pc backup, pc backup restore, and pc collection were top-level commands. All three have been relocated under pc index, which better reflects their ownership relationship with the index resource. The move ships without backwards-compatibility aliases, as the existing public preview signal covers this kind of breaking change before v1.

New command surface:

pc index backup create   --index-name <name> [--name <name>] [--description <desc>]
pc index backup list     [--index-name <name>] [--limit <n>] [--pagination-token <token>]
pc index backup describe --id <backup-id>
pc index backup delete   --id <backup-id>

pc index restore                  --id <backup-id> --name <new-index-name> [--tags k=v,...] [--deletion-protection enabled|disabled]
pc index restore list             [--limit <n>] [--pagination-token <token>]
pc index restore describe         --id <restore-job-id>

pc index collection create   --name <name> --source <index-name>
pc index collection list
pc index collection describe --name <name>
pc index collection delete   --name <name>

Restore is intentionally a peer of backup under pc index, not nested beneath it. Restore jobs are a distinct resource — they have their own IDs and lifecycle — and placing them at the same level avoids the pc index backup restore describe depth while keeping related commands discoverable together.

A new GROUP_INDEX_MANAGEMENT help group is registered on the index command so that backup, restore, and collection appear in their own labeled section in pc index --help, alongside the existing Index Data Commands and Index Namespace Commands groups.

Files moved:

• command/backup/ → command/index/backup/
• command/backup/restore/ → command/index/restore/
• command/collection/ → command/index/collection/

BackupService no longer includes CreateIndexFromBackup — that method now belongs exclusively to RestoreJobService in the restore package, matching the new ownership boundary.

---

Bug fixes and correctness improvements

pc index configure --name not marked required

configure was the only resource command that did not call cmd.MarkFlagRequired("name"). Running it without --name would silently pass an empty string to the API and return a confusing error. The flag is now required, consistent with every other command that takes a resource name.

--metric and --dimension silently ignored when creating an integrated index

CreateIndexForModelEmbed exposes both a Metric and Dimension field, but the indexTypeIntegrated branch in runCreateIndexCmd never populated them. Both flags were accepted by the CLI but dropped before reaching the SDK.

• Dimension is now forwarded via pointerOrNil(int(options.dimension)), producing nil when unset (zero value) and the user-supplied value otherwise.
• Metric requires special handling: the flag defaults to "cosine", so pointerOrNil alone would always forward a non-nil value and override the embedding model's own default. The fix uses cmd.Flags().Changed("metric") to only populate Embed.Metric when the flag was explicitly passed.

Two additions to create_test.go cover this:

• An assertion added to the existing Test_runCreateIndexWithService_Integrated_Args test confirms Embed.Metric and Embed.Dimension are nil when neither flag is explicitly set.
• A new Test_runCreateIndexWithService_Integrated_MetricAndDimension test verifies both fields are correctly populated when the flags are explicitly provided.

PrintBackupTable missing fields

pc index backup describe omitted three fields present in the Backup struct returned by the API:

• Description — a user can create a backup with --description but the value was not shown in describe output
• Source Index ID — the source index UUID, complementing the existing Source Index name field
• Dimension — the vector dimension of the backed-up index

All three are now rendered in the describe table.

---

Note

Medium Risk
Breaking command paths will break scripts and docs using pc backup / pc collection, and integrated index create now changes when metric/dimension reach the API—important for index provisioning but localized to CLI wiring.

Overview
Breaking CLI change: pc backup, pc backup restore, and top-level pc collection are removed from the root command tree. The same capabilities live under pc index backup, pc index restore (a sibling of backup, not nested under it), and pc index collection, grouped via new GROUP_INDEX_MANAGEMENT on pc index --help. Examples and help text are updated to the new paths; BackupService no longer includes CreateIndexFromBackup—that stays on RestoreJobService in the restore package.

Correctness fixes: pc index configure now marks --name as required. Integrated index creation forwards Embed.Dimension when set and only sends Embed.Metric when --metric was explicitly changed (avoiding the default cosine overriding the model). PrintBackupTable adds Description, Source Index ID, and Dimension.

Minor cleanup: mock/test service types exported with clearer names, backup describe gets a Long help, collection command gets examples and the same management group.

^{Reviewed by Cursor Bugbot for commit 9be361b. Bugbot is set up for automated code reviews on this repo. Configure here.}