[CLI]: Fact check and complete the command help (#2901)

Synced from monorepo@d4d8591dd48b3dee1e3960d08b80199e73d3bb58

Author: SferaDev

.sync-commit

@@ -1 +1 @@
-211363ac9fc3e3ecd8ce98c6a2037923b28e7cf1
+d4d8591dd48b3dee1e3960d08b80199e73d3bb58

package.json

@@ -36,15 +36,15 @@
     "yaml": "2.9.0",
     "zod": "4.4.3",
     "zod-config": "1.4.0",
-    "@xata.io/lang": "0.0.4",
-    "@xata.io/pgroll": "0.9.1",
-    "@xata.io/config": "0.0.9",
-    "@xata.io/sql": "0.2.4",
     "@xata.io/ai": "0.1.1",
     "@xata.io/api": "0.1.8",
-    "@xata.io/tsconfig": "0.0.2",
+    "@xata.io/config": "0.0.9",
+    "@xata.io/lang": "0.0.4",
+    "@xata.io/pgroll": "0.9.1",
     "@xata.io/pgstream": "0.2.3",
-    "@xata.io/utils": "0.1.3"
+    "@xata.io/sql": "0.2.4",
+    "@xata.io/utils": "0.1.3",
+    "@xata.io/tsconfig": "0.0.2"
   },
   "scripts": {
     "dev": "bun src/bin/cli.ts",

pnpm-lock.yaml

@@ -113,7 +113,7 @@ export const AuthLoginCommand = buildCommand({
   docs: {
     brief: `Log in to a ${PRODUCT_NAME} account`,
     fullDescription:
-      'Opens the device flow in a browser, or stores an API key with --api-key for non-interactive use. The issuer, API URL and client flags point the CLI at a deployment other than production, which is what Enterprise customers running their own cloud need.',
+      'Prints a URL and a code to authorize this machine, or stores an API key with `--api-key` for non-interactive use. The issuer, API URL and client flags log in against a deployment other than production, which is how Enterprise customers connect the CLI to a custom deployment in their own cloud. Omit them and the CLI uses the default production values.',
     customUsage: [
       { input: '--api-key xau_...', brief: 'Log in from a script or CI' },
       { input: '--profile staging', brief: 'Log in as another profile' },

src/commands/auth/login.ts

@@ -403,7 +403,7 @@ export const BranchCreateCommand = buildCommand({
   docs: {
     brief: 'Create a new branch',
     fullDescription:
-      'A branch is a running Postgres database that starts as a copy of its parent. It takes a moment to come up, so `xata branch wait-ready` is what to run before connecting to it. Creating a branch in a folder linked to a project also checks it out.',
+      'A branch is a running Postgres database that starts as a copy of its parent. It takes a moment to come up, so `xata branch wait-ready` is what to run before connecting to it. It is checked out afterwards when this folder already has an organization, project and branch to work from.',
     customUsage: [
       { input: '--name my-branch', brief: 'Branch the current branch' },
       { input: '--name my-branch --parent-branch <branch-id>', brief: 'Branch another branch' },

src/commands/branch/create.ts

@@ -60,8 +60,10 @@ export async function implementation(this: LocalContext, flags: Flags, branchNam
 export const BranchDeleteCommand = buildCommand({
   docs: {
     brief: 'Delete a branch',
-    fullDescription:
-      'Deleting a branch destroys its database and cannot be undone. The branch checked out in this folder cannot be deleted, and outside an interactive terminal the confirmation has to come from `--yes`.',
+    fullDescription: [
+      'The branch checked out in this folder cannot be deleted, and outside an interactive terminal the confirmation has to come from `--yes`.',
+      'Warning: deleting a branch destroys its database and cannot be undone.'
+    ].join('\n'),
     customUsage: [
       { input: 'my-branch', brief: 'Delete a branch, asking for confirmation' },
       { input: 'my-branch --yes', brief: 'Delete a branch from a script' }

src/commands/branch/delete.ts

@@ -338,7 +338,7 @@ export const BranchLogsCommand = buildCommand({
   docs: {
     brief: 'Retrieve the PostgreSQL logs of a branch',
     fullDescription:
-      'Reads the logs of every instance of the branch, the primary and any replicas, which is where slow queries, connection issues and replication problems show up. Requires the `logs:read` scope on the API key. Of the output formats, `raw` prints `<timestamp> [<level> <instanceID> <process>] <message>` per line, `json` a single array, `ndjson` one object per line for streaming into another process, and `csv` the columns `timestamp,level,instanceID,process,message`. Follow mode polls every 2 seconds with a 5 second overlap and de-duplicates entries. Logs can contain connection strings and other credentials.',
+      'Reads the logs of every instance of the branch, the primary and any replicas, which is where slow queries, connection issues and replication problems show up. Requires the `logs:read` scope on the API key. Of the output formats, `raw` prints `<timestamp> [<level> <instanceID> <process>] <message>` per line, `json` a single array, `ndjson` one object per line for streaming into another process, and `csv` the columns `timestamp,level,instanceID,process,message`. Follow mode polls every 2 seconds with a 5 second overlap and de-duplicates entries. Logs can contain connection strings and other credentials, see https://xata.io/docs/platform/logs for what is redacted.',
     customUsage: [
       { input: 'my-branch --level error --start 15m', brief: 'Errors from the last 15 minutes' },
       {

src/commands/branch/logs.ts

@@ -108,7 +108,7 @@ export const QueryInsightsEnableCommand = buildCommand({
   docs: {
     brief: 'Enable pg_stat_statements for query insights on a branch',
     fullDescription:
-      'Creates the `pg_stat_statements` extension and adds it to the preloaded libraries, which needs a branch restart: wait for it with `xata branch wait-ready <branch> --wake`. Operations that rebuild a branch, such as a migration into it, can drop the extension, so run this again if query insights stop returning rows.'
+      'Adds `pg_stat_statements` to the preloaded libraries, which restarts the branch, and creates the extension. Run it, wait for the branch with `xata branch wait-ready <branch> --wake`, then run it again to create the extension. Operations that rebuild a branch, such as a migration into it, can drop the extension, so run this again if query insights stop returning rows. The same can be done from the console, by adding it to the preloaded libraries in the branch settings, see https://xata.io/docs/platform/extensions.'
   },
   parameters: {
     flags: {

src/commands/branch/query-insights/enable.ts

@@ -9,7 +9,7 @@ export const BranchQueryInsightsRoute = buildRouteMap({
   docs: {
     brief: 'Inspect query statistics and active queries for a branch',
     fullDescription:
-      'Which statements are slow, which are expensive, and what is running right now. Historical statistics come from `pg_stat_statements`, and the queries running at this moment from `pg_stat_activity`. Running `xata branch qi` without a subcommand is the same as `xata branch qi list`. Except for `active`, which reads `pg_stat_activity`, these commands need `pg_stat_statements` loaded: run `xata branch query-insights enable <branch>` and then wait for the restart with `xata branch wait-ready <branch> --wake`.'
+      'Which statements are slow, which are expensive, and what is running right now. Historical statistics come from `pg_stat_statements`, and the queries running at this moment from `pg_stat_activity`. Running `xata branch qi` without a subcommand is the same as `xata branch qi list`. Except for `active`, which reads `pg_stat_activity`, these commands need `pg_stat_statements` loaded: run `xata branch query-insights enable <branch>` and then wait for the restart with `xata branch wait-ready <branch> --wake`. Unlike `logs` and `metrics`, which go through the API, these commands open a direct PostgreSQL connection: they cannot run against a branch that is hibernated or still provisioning, and an API key needs the `credentials:read` scope. The console reads the same `pg_stat_statements` data, see https://xata.io/docs/platform/query-insights.'
   },
   routes: {
     list: QueryInsightsListCommand,

src/commands/branch/query-insights/index.ts

@@ -99,18 +99,14 @@ export async function implementation(this: LocalContext, flags: Flags, branchNam
 
 export const QueryInsightsListCommand = buildCommand({
   docs: {
-    brief: 'List historical query statistics for a branch, slowest first',
+    brief: 'List historical query statistics for a branch, by total execution time',
     fullDescription:
-      'In table output a leading `!` marks a row with a high mean execution time or a low cache hit rate, and the command prints the `show` command for each flagged query. Both `json` and `ndjson` emit `{ "total", "limit", "offset", "queries" }`, with the statements under `queries`.',
+      'In table output a leading `!` marks a row worth a look, a slow mean, spikes far above it, a low cache hit rate, heavy temporary file use or a very large row count, and the command prints the `show` command for each flagged query. Below the table it prints how many queries are being shown and, when more remain, the `list` command that fetches the next page. Both `json` and `ndjson` emit `{ "total", "limit", "offset", "queries" }`, with the statements under `queries`.',
     customUsage: [
       {
         input: 'my-branch --performance slow --sort mean-time',
         brief: 'The slowest statements by average execution time'
       },
-      {
-        input: 'xata branch qi my-branch --sort mean-time',
-        brief: 'Same thing, through the alias and default subcommand'
-      },
       {
         input: `my-branch --limit 100 --output ndjson | jq -r '.queries[].query'`,
         brief: 'Feed the top 100 statements to another process'