cli doc improvements

docs/cli/auth.mdx

@@ -1,75 +1,69 @@
 ---
-title: Authentication Commands
-description: Commands for managing Xata authentication
+title: Auth Command
+description: Commands for authenticating with Xata
 ---
 
-The `auth` commands help you manage your Xata authentication state, including logging in, switching accounts, and managing tokens.
+The `auth` command helps you manage authentication and account profiles for the Xata CLI.
 
-## login
+## Subcommands
 
-Log in to your Xata account.
+### login
+Log in to a Xata account.
 
 ```bash
-xata auth login
+xata auth login [--env dev|staging|prod] [--profile <name>] [-f|--force] [-h|--help]
 ```
+- `--env`: Environment to log in to (`dev|staging|prod`, default: `prod`)
+- `--profile`: Profile to log in to (default: `default`)
+- `-f, --force`: Force login even if already logged in
+- `-h, --help`: Print help information and exit
 
-This command will open your default web browser to authenticate with Xata. After successful authentication, your credentials will be stored locally.
-
-## logout
-
+### logout
 Log out of the current account.
 
 ```bash
-xata auth logout
+xata auth logout [--profile <name>] [--yes] [-h|--help]
 ```
+- `--profile`: Profile to log out of (default: `default`)
+- `--yes`: Do not ask for confirmation, assume yes
+- `-h, --help`: Print help information and exit
 
-This command removes the stored credentials for the current account.
-
-## status
-
+### status
 Display active account and authentication state.
 
 ```bash
-xata auth status
+xata auth status [--profile <name>] [-h|--help]
 ```
+- `--profile`: Profile to log in to (default: `default`)
+- `-h, --help`: Print help information and exit
 
-Shows information about your current authentication state, including:
-- Currently logged-in account
-- Authentication status
-- Token expiration (if applicable)
-
-## switch
-
+### switch
 Switch to a different Xata account profile.
 
 ```bash
 xata auth switch <profile>
+xata auth switch --help
 ```
+- `<profile>`: The profile to switch to
+- `-h, --help`: Print help information and exit
 
-Arguments:
-- `profile` - The name of the profile to switch to
-
-This command allows you to quickly switch between different Xata accounts that you've previously logged into.
-
-## access-token
-
+### access-token
 Print the current access token.
 
 ```bash
-xata auth access-token
+xata auth access-token [--profile <name>] [-h|--help]
 ```
+- `--profile`: Profile to log in to (default: `default`)
+- `-h, --help`: Print help information and exit
 
-This command outputs your current access token, which can be used for API authentication.
-
-## refresh-token
-
+### refresh-token
 Print the current refresh token.
 
 ```bash
-xata auth refresh-token
+xata auth refresh-token [--profile <name>] [-h|--help]
 ```
-
-This command outputs your current refresh token, which can be used to obtain new access tokens.
+- `--profile`: Profile to log in to (default: `default`)
+- `-h, --help`: Print help information and exit
 
 ## Global Flags
 

docs/cli/branch.mdx

@@ -1,115 +1,135 @@
 ---
-title: Branch Commands
+title: Branch Command
 description: Commands for managing Xata database branches
 ---
 
-The `branch` commands help you manage your Xata database branches, including creating, switching, and managing branch configurations.
+The `branch` command helps you create, list, describe, and manage branches in Xata.
 
-## list
+## Subcommands
 
-List all branches in the current project.
+### list
+List all branches.
 
 ```bash
-xata branch list
+xata branch list [--organization <id>] [--project <id>] [--branch <id>] [--json] [-h|--help]
 ```
+- Aliases: `ls`
+- `--organization`: Organization ID (default: "")
+- `--project`: Project ID (default: "")
+- `--branch`: Branch ID (default: "")
+- `--json`: Output in JSON format (default: false)
+- `-h, --help`: Print help information and exit
 
-This command displays all branches in your project, including:
-- Branch name
-- Parent branch
-- Creation date
-- Status
-
-## describe
-
-Describe a branch in detail.
+### describe
+Describe a branch.
 
 ```bash
-xata branch describe
+xata branch describe [--organization <id>] [--project <id>] [--branch <id>] [--json] [-h|--help] <branch name>
 ```
-
-This command shows detailed information about the current branch, including:
-- Branch configuration
-- Schema version
-- Migration status
-- Connection details
-
-## create
-
+- Aliases: `view`, `show`
+- `--organization`: Organization ID (default: "")
+- `--project`: Project ID (default: "")
+- `--branch`: Branch ID (default: "")
+- `--json`: Output in JSON format (default: false)
+- `-h, --help`: Print help information and exit
+- `branch name`: The branch to describe
+
+### create
 Create a new branch.
 
 ```bash
-xata branch create
+xata branch create [--organization <id>] [--project <id>] [--parent-branch <id>] [--name <name>] [--instance-type <type>] [--replicas <n>] [--region <region>] [--json] [-h|--help]
 ```
-
-This command creates a new branch from the current branch, allowing you to make isolated changes to your database schema.
-
-## delete
-
+- `--organization`: Organization ID (default: "")
+- `--project`: Project ID (default: "")
+- `--parent-branch`: Parent branch ID. Pass "None" to create a branch without a parent. (default: "")
+- `--name`: Branch name (default: "")
+- `--instance-type`: Type of instance for this branch (default: "")
+- `--replicas`: Number of replicas for the branch (0-4, default: "")
+- `--region`: Region for the branch (default: "")
+- `--json`: Output in JSON format (default: false)
+- `-h, --help`: Print help information and exit
+
+### delete
 Delete a branch.
 
 ```bash
-xata branch delete
+xata branch delete [--organization <id>] [--project <id>] [--branch <id>] [--yes] [--json] [-h|--help] <branch name>
 ```
+- `--organization`: Organization ID (default: "")
+- `--project`: Project ID (default: "")
+- `--branch`: Branch ID (default: "")
+- `--yes`: Do not ask for confirmation, assume yes (default: false)
+- `--json`: Output in JSON format (default: false)
+- `-h, --help`: Print help information and exit
+- `branch name`: The branch to switch to
 
-This command permanently deletes the current branch and all its data. This action cannot be undone.
-
-## url
-
-Print the connection URL for a branch.
+### url
+Print URL (connection string) for a branch.
 
 ```bash
-xata branch url
+xata branch url [--organization <id>] [--project <id>] [--branch <id>] [--database <name>] [-h|--help] <branch name>
 ```
+- Aliases: `connection-string`
+- `--organization`: Organization ID (default: "")
+- `--project`: Project ID (default: "")
+- `--branch`: Branch ID (default: "")
+- `--database`: Database name (default: "")
+- `-h, --help`: Print help information and exit
+- `branch name`: The branch to get URL for
 
-This command outputs the connection string (DSN) for the current branch, which can be used to connect your application to the database.
-
-## checkout
-
-Switch to a different branch.
+### checkout
+Checkout a branch.
 
 ```bash
-xata branch checkout <branch>
+xata branch checkout [--organization <id>] [--project <id>] [--branch <id>] [--database <name>] [--json] [-h|--help] <branch name>
 ```
-
-Arguments:
-- `branch` - The name of the branch to switch to
-
-This command switches your working context to the specified branch.
-
-## tree
-
+- `--organization`: Organization ID (default: "")
+- `--project`: Project ID (default: "")
+- `--branch`: Branch ID (default: "")
+- `--database`: Database name (default: "")
+- `--json`: Output in JSON format (default: false)
+- `-h, --help`: Print help information and exit
+- `branch name`: The branch to switch to
+
+### tree
 List all branches as a tree.
 
 ```bash
-xata branch tree
+xata branch tree [--organization <id>] [--project <id>] [--branch <id>] [--show-id] [-h|--help]
 ```
-
-This command displays the branch hierarchy in a tree format, showing the relationships between branches.
-
-## get
-
+- Aliases: `topology`
+- `--organization`: Organization ID (default: "")
+- `--project`: Project ID (default: "")
+- `--branch`: Branch ID (default: "")
+- `--show-id`: Project ID (default: false)
+- `-h, --help`: Print help information and exit
+
+### get
 Get a field from a branch description.
 
 ```bash
-xata branch get <field>
+xata branch get [--organization <id>] [--project <id>] [--branch <id>] [-h|--help] <field>
 ```
+- `--organization`: Organization ID (default: "")
+- `--project`: Project ID (default: "")
+- `--branch`: Branch ID (default: "")
+- `-h, --help`: Print help information and exit
+- `field`: The field to get (default: `.catalog`)
 
-Arguments:
-- `field` - The field to retrieve from the branch description
-
-This command retrieves specific information about the current branch.
-
-## wait-ready
-
+### wait-ready
 Wait for a branch to be ready.
 
 ```bash
-xata branch wait-ready
+xata branch wait-ready [--organization <id>] [--project <id>] [--branch <id>] [--json] [-h|--help] <branch name>
 ```
-
-This command waits until the current branch is fully provisioned and ready to accept connections.
+- `--organization`: Organization ID (default: "")
+- `--project`: Project ID (default: "")
+- `--branch`: Branch ID (default: "")
+- `--json`: Output in JSON format (default: false)
+- `-h, --help`: Print help information and exit
+- `branch name`: The branch to switch to
 
 ## Global Flags
 
-- `-h, --help` - Print help information and exit
-- `--json` - Output in JSON format 
+- `-h, --help`