@xano/cli 0.0.95 → 1.0.0

package/README.md

@@ -25,7 +25,7 @@ npm install -g @xano/cli
 
 3. Pull a workspace to local files:
    ```bash
-   xano workspace pull ./my-workspace
+   xano workspace pull
    ```
 
 ## Commands
@@ -92,70 +92,76 @@ xano profile delete myprofile --force
 xano workspace list
 
 # Get workspace details
-xano workspace get <workspace_id>
+xano workspace get -w <workspace_id>
 
 # Create a workspace
 xano workspace create my-workspace
 xano workspace create my-workspace -d "My application workspace"
 
 # Edit a workspace
-xano workspace edit <workspace_id> --name "new-name" -d "Updated description"
-xano workspace edit <workspace_id> --swagger             # Enable swagger docs
-xano workspace edit <workspace_id> --no-swagger          # Disable swagger docs
-xano workspace edit <workspace_id> --require-token       # Require token for docs
+xano workspace edit -w <workspace_id> --name "new-name" -d "Updated description"
+xano workspace edit -w <workspace_id> --swagger          # Enable swagger docs
+xano workspace edit -w <workspace_id> --no-swagger       # Disable swagger docs
+xano workspace edit -w <workspace_id> --require-token    # Require token for docs
 
 # Delete a workspace (confirmation required)
-xano workspace delete <workspace_id>
-xano workspace delete <workspace_id> --force
-
-# Pull workspace to local files
-xano workspace pull ./my-workspace
-xano workspace pull ./my-workspace -b dev              # Specific branch
-xano workspace pull ./my-workspace --env --records      # Include env vars and table records
-xano workspace pull ./my-workspace --draft              # Include draft changes
-
-# Push local files to workspace (only changed files by default)
-xano workspace push ./my-workspace
-xano workspace push ./my-workspace -b dev
-xano workspace push ./my-workspace --sync                # Full push — send all files, not just changed ones
-xano workspace push ./my-workspace --sync --delete       # Full push + delete remote objects not included
-xano workspace push ./my-workspace --dry-run             # Preview changes without pushing
-xano workspace push ./my-workspace --records             # Include table records
-xano workspace push ./my-workspace --env                 # Include environment variables
-xano workspace push ./my-workspace --truncate            # Truncate tables before import
-xano workspace push ./my-workspace --no-transaction      # Disable database transaction wrapping
-xano workspace push ./my-workspace --no-guids            # Skip writing GUIDs back to local files
-xano workspace push ./my-workspace --force               # Skip preview and confirmation (for CI/CD)
-xano workspace push ./my-workspace -i "function/*"       # Push only matching files
-xano workspace push ./my-workspace -e "table/*"          # Push all files except tables
-xano workspace push ./my-workspace -i "function/*" -e "**/test*"  # Include functions, exclude tests
-
-# Pull from a git repository to local files
-xano workspace git pull ./output -r https://github.com/owner/repo
-xano workspace git pull ./output -r https://github.com/owner/repo -b main
-xano workspace git pull ./output -r https://github.com/owner/repo/tree/main/path/to/dir
-xano workspace git pull ./output -r https://github.com/owner/repo/blob/main/file.xs
-xano workspace git pull ./output -r git@github.com:owner/repo.git
-xano workspace git pull ./output -r https://gitlab.com/owner/repo/-/tree/master/path
-xano workspace git pull ./output -r https://github.com/owner/private-repo -t ghp_xxx
-xano workspace git pull ./output -r https://github.com/owner/repo --path subdir
+xano workspace delete -w <workspace_id>
+xano workspace delete -w <workspace_id> --force
+
+# Pull workspace to local files (defaults to current directory)
+xano workspace pull
+xano workspace pull -d ./my-workspace                    # Specify output directory
+xano workspace pull -b dev                               # Specific branch
+xano workspace pull --env --records                      # Include env vars and table records
+xano workspace pull --draft                              # Include draft changes
+
+# Push local files to workspace (defaults to current directory, only changed files)
+xano workspace push
+xano workspace push -d ./my-workspace                    # Push from a specific directory
+xano workspace push -b dev
+xano workspace push --sync                               # Full push — send all files, not just changed ones
+xano workspace push --sync --delete                      # Full push + delete remote objects not included
+xano workspace push --dry-run                            # Preview changes without pushing
+xano workspace push --records                            # Include table records
+xano workspace push --env                                # Include environment variables
+xano workspace push --truncate                           # Truncate tables before import
+xano workspace push --no-transaction                     # Disable database transaction wrapping
+xano workspace push --no-guids                           # Skip writing GUIDs back to local files
+xano workspace push --force                              # Skip preview and confirmation (for CI/CD)
+xano workspace push -i "function/*"                      # Push only matching files
+xano workspace push -e "table/*"                         # Push all files except tables
+xano workspace push -i "function/*" -e "**/test*"        # Include functions, exclude tests
+
+# Pull from a git repository to local files (defaults to current directory)
+xano workspace git pull -r https://github.com/owner/repo
+xano workspace git pull -d ./output -r https://github.com/owner/repo
+xano workspace git pull -r https://github.com/owner/repo -b main
+xano workspace git pull -r https://github.com/owner/repo/tree/main/path/to/dir
+xano workspace git pull -r https://github.com/owner/repo/blob/main/file.xs
+xano workspace git pull -r git@github.com:owner/repo.git
+xano workspace git pull -r https://gitlab.com/owner/repo/-/tree/master/path
+xano workspace git pull -r https://github.com/owner/private-repo -t ghp_xxx
+xano workspace git pull -r https://github.com/owner/repo --path subdir
 ```
 
 ### Branches
 
 All branch commands use **branch labels** (e.g., `v1`, `dev`), not IDs.
 
+The `v1` branch is the default branch and always exists. It cannot be created, edited, or deleted.
+
 ```bash
 # List branches
 xano branch list
+xano branch list -w <workspace_id>
 
 # Get branch details
 xano branch get <branch_label>
 
 # Create a branch
-xano branch create --label dev
-xano branch create -l feature-auth -s dev -d "Auth feature"
-xano branch create -l staging --color "#ebc346"
+xano branch create dev
+xano branch create feature-auth -s dev -d "Auth feature"
+xano branch create staging --color "#ebc346"
 
 # Edit a branch
 xano branch edit <branch_label> --label "new-label"
@@ -209,9 +215,9 @@ xano release list
 xano release get <release_name>
 
 # Create a release
-xano release create --name "v1.0" --branch main
-xano release create --name "v1.1-hotfix" --branch main --hotfix
-xano release create --name "v1.0" --branch main --table-ids 1,2,3
+xano release create "v1.0" --branch main
+xano release create "v1.1-hotfix" --branch main --hotfix
+xano release create "v1.0" --branch main --table-ids 1,2,3
 
 # Edit a release
 xano release edit <release_name> --name "v1.0-final" -d "Updated description"
@@ -227,14 +233,22 @@ xano release import --file ./my-release.tar.gz
 xano release delete <release_name>
 xano release delete <release_name> --force
 
-# Pull release to local files
-xano release pull ./my-release -r v1.0
-xano release pull ./my-release -r v1.0 --env --records
-
-# Push local files as a new release
-xano release push ./my-release -n "v2.0"
-xano release push ./my-release -n "v2.0" --hotfix -d "Critical fix"
-xano release push ./my-release -n "v2.0" --no-records --no-env
+# Pull release to local files (defaults to current directory)
+xano release pull -r v1.0
+xano release pull -d ./my-release -r v1.0
+xano release pull -r v1.0 --env --records
+
+# Push local files as a new release (defaults to current directory)
+xano release push -n "v2.0"
+xano release push -d ./my-release -n "v2.0"
+xano release push -n "v2.0" --hotfix --description "Critical fix"
+xano release push -n "v2.0" --no-records --no-env
+
+# Deploy a release to its workspace as a new branch (confirmation required)
+xano release deploy "v1.0"
+xano release deploy "v1.0" --force
+xano release deploy "v1.0" --branch "restore-v1" --no-set_live
+xano release deploy "v1.0" -w 40 -o json --force
 ```
 
 ### Platforms
@@ -329,17 +343,19 @@ xano tenant impersonate <tenant_name> -o json
 #### Pull / Push
 
 ```bash
-# Pull tenant to local files
-xano tenant pull ./my-tenant -t <tenant_name>
-xano tenant pull ./my-tenant -t <tenant_name> --env --records
-xano tenant pull ./my-tenant -t <tenant_name> --draft
-
-# Push local files to tenant
-xano tenant push ./my-tenant -t <tenant_name>
-xano tenant push ./my-tenant -t <tenant_name> --records        # Include table records
-xano tenant push ./my-tenant -t <tenant_name> --env            # Include environment variables
-xano tenant push ./my-tenant -t <tenant_name> --truncate
-xano tenant push ./my-tenant -t <tenant_name> --no-transaction # Disable transaction wrapping
+# Pull tenant to local files (defaults to current directory)
+xano tenant pull -t <tenant_name>
+xano tenant pull -d ./my-tenant -t <tenant_name>
+xano tenant pull -t <tenant_name> --env --records
+xano tenant pull -t <tenant_name> --draft
+
+# Push local files to tenant (defaults to current directory)
+xano tenant push -t <tenant_name>
+xano tenant push -d ./my-tenant -t <tenant_name>
+xano tenant push -t <tenant_name> --records                    # Include table records
+xano tenant push -t <tenant_name> --env                        # Include environment variables
+xano tenant push -t <tenant_name> --truncate
+xano tenant push -t <tenant_name> --no-transaction             # Disable transaction wrapping
 ```
 
 #### Deployments
@@ -441,6 +457,45 @@ xano tenant cluster license set <cluster_id>
 xano tenant cluster license set <cluster_id> --file ./kubeconfig.yaml
 ```
 
+### Sandbox
+
+Manage your sandbox tenant. Each user has a single sandbox tenant that is auto-provisioned on first use.
+
+```bash
+# Get your sandbox tenant (creates if needed)
+xano sandbox get
+xano sandbox get -o json
+
+# Pull sandbox to local files (defaults to current directory)
+xano sandbox pull
+xano sandbox pull -d ./my-sandbox
+xano sandbox pull --env --records
+
+# Push local files to sandbox (defaults to current directory, only changed files)
+xano sandbox push
+xano sandbox push -d ./my-workspace                      # Push from a specific directory
+xano sandbox push --sync                                 # Full push — send all files
+xano sandbox push --sync --delete                        # Full push + delete remote objects not included
+xano sandbox push --dry-run                              # Preview changes without pushing
+xano sandbox push --records --env                        # Include records and environment variables
+xano sandbox push --truncate                             # Truncate tables before import
+xano sandbox push --no-guids                             # Skip writing GUIDs back to local files
+xano sandbox push --force                                # Skip preview and confirmation
+xano sandbox push -i "function/*"                        # Push only matching files
+xano sandbox push -e "table/*"                           # Push all files except tables
+xano sandbox push --review                               # Push and open sandbox review in the browser
+
+# Review (open in browser)
+xano sandbox review
+
+# Impersonate (open in browser)
+xano sandbox impersonate
+
+# Reset all workspace data
+xano sandbox reset
+xano sandbox reset --force
+```
+
 ### Static Hosts
 
 ```bash
@@ -463,6 +518,7 @@ All commands support these options:
 
 | Flag | Description |
 |------|-------------|
+| `-c, --config` | Path to credentials file (or set `XANO_CONFIG` env var). Default: `~/.xano/credentials.yaml` |
 | `-p, --profile` | Profile to use (or set `XANO_PROFILE` env var) |
 | `-w, --workspace` | Workspace ID (overrides profile default) |
 | `-o, --output` | Output format: `summary` (default) or `json` |
@@ -483,7 +539,18 @@ This will show:
 
 ## Configuration
 
-Profiles are stored in `~/.xano/credentials.yaml`:
+Profiles are stored in `~/.xano/credentials.yaml` by default. You can use a different credentials file with:
+
+```bash
+# Via flag
+xano profile list -c /path/to/other-credentials.yaml
+
+# Via environment variable
+export XANO_CONFIG=/path/to/other-credentials.yaml
+xano workspace list
+```
+
+### Credentials File Format
 
 ```yaml
 profiles:

package/dist/base-command.d.ts

@@ -14,12 +14,30 @@ export interface CredentialsFile {
     };
 }
 export declare function buildUserAgent(version: string): string;
+export interface SandboxTenant {
+    created_at?: string;
+    description?: string;
+    display?: string;
+    ephemeral?: boolean;
+    id: number;
+    name: string;
+    sandbox_expires_at?: string | number;
+    state?: string;
+    xano_domain?: string;
+}
+/**
+ * Resolve the credentials file path from flag, env var, or default.
+ * Checks (in order): explicit configPath arg, XANO_CONFIG env var, ~/.xano/credentials.yaml
+ */
+export declare function resolveCredentialsPath(configPath?: string): string;
 export default abstract class BaseCommand extends Command {
     static baseFlags: {
+        config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static flags: {
+        config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
@@ -35,9 +53,31 @@ export default abstract class BaseCommand extends Command {
     protected getDefaultProfile(): string;
     protected getProfile(): string | undefined;
     /**
-     * Load and parse the credentials file. Returns null if the file doesn't exist.
+     * Get the resolved credentials file path, respecting --config flag and XANO_CONFIG env var.
+     * Reads -c/--config from process.argv directly because oclif doesn't set this.flags
+     * from parsed results — the static flags property is the flag definition, not parsed values.
      */
+    protected getCredentialsPath(): string;
     protected loadCredentialsFile(): CredentialsFile | null;
+    /**
+     * Get or create the singleton sandbox environment for the authenticated user.
+     * Returns the sandbox object (existing or newly created).
+     */
+    protected getOrCreateSandbox(profile: ProfileConfig, verbose: boolean): Promise<SandboxTenant>;
+    /**
+     * Resolve profile from flags, validating instance_origin and access_token exist.
+     */
+    protected resolveProfile(flags: {
+        profile?: string;
+    }): {
+        profile: ProfileConfig;
+        profileName: string;
+    };
+    /**
+     * Parse an API error response and return a clean error message.
+     * Extracts the message from JSON responses and adds context for common errors.
+     */
+    protected parseApiError(response: Response, fallbackPrefix: string): Promise<string>;
     /**
      * Make an HTTP request with optional verbose logging.
      * Use this for all Metadata API calls to support the --verbose flag.

package/dist/base-command.js

@@ -7,8 +7,25 @@ import { checkForUpdate } from './update-check.js';
 export function buildUserAgent(version) {
     return `xano-cli/${version} (${process.platform}; ${process.arch}) node/${process.version}`;
 }
+/**
+ * Resolve the credentials file path from flag, env var, or default.
+ * Checks (in order): explicit configPath arg, XANO_CONFIG env var, ~/.xano/credentials.yaml
+ */
+export function resolveCredentialsPath(configPath) {
+    const explicit = configPath || process.env.XANO_CONFIG;
+    if (explicit) {
+        return path.resolve(explicit);
+    }
+    return path.join(os.homedir(), '.xano', 'credentials.yaml');
+}
 export default class BaseCommand extends Command {
     static baseFlags = {
+        config: Flags.string({
+            char: 'c',
+            description: 'Path to credentials file (default: ~/.xano/credentials.yaml)',
+            env: 'XANO_CONFIG',
+            required: false,
+        }),
         profile: Flags.string({
             char: 'p',
             description: 'Profile to use (uses default profile if not specified)',
@@ -88,11 +105,22 @@ export default class BaseCommand extends Command {
         return this.flags?.profile;
     }
     /**
-     * Load and parse the credentials file. Returns null if the file doesn't exist.
+     * Get the resolved credentials file path, respecting --config flag and XANO_CONFIG env var.
+     * Reads -c/--config from process.argv directly because oclif doesn't set this.flags
+     * from parsed results — the static flags property is the flag definition, not parsed values.
      */
+    getCredentialsPath() {
+        const args = process.argv;
+        for (let i = 0; i < args.length; i++) {
+            if ((args[i] === '--config' || args[i] === '-c') && args[i + 1])
+                return resolveCredentialsPath(args[i + 1]);
+            if (args[i]?.startsWith('--config='))
+                return resolveCredentialsPath(args[i].slice('--config='.length));
+        }
+        return resolveCredentialsPath();
+    }
     loadCredentialsFile() {
-        const configDir = path.join(os.homedir(), '.xano');
-        const credentialsPath = path.join(configDir, 'credentials.yaml');
+        const credentialsPath = this.getCredentialsPath();
         if (!fs.existsSync(credentialsPath)) {
             return null;
         }
@@ -103,6 +131,67 @@ export default class BaseCommand extends Command {
         }
         return null;
     }
+    /**
+     * Get or create the singleton sandbox environment for the authenticated user.
+     * Returns the sandbox object (existing or newly created).
+     */
+    async getOrCreateSandbox(profile, verbose) {
+        const apiUrl = `${profile.instance_origin}/api:meta/sandbox/me`;
+        const response = await this.verboseFetch(apiUrl, {
+            headers: {
+                accept: 'application/json',
+                Authorization: `Bearer ${profile.access_token}`,
+            },
+            method: 'GET',
+        }, verbose, profile.access_token);
+        if (!response.ok) {
+            const message = await this.parseApiError(response, 'Failed to get sandbox environment');
+            this.error(message);
+        }
+        return (await response.json());
+    }
+    /**
+     * Resolve profile from flags, validating instance_origin and access_token exist.
+     */
+    resolveProfile(flags) {
+        const profileName = flags.profile || this.getDefaultProfile();
+        const credentials = this.loadCredentialsFile();
+        if (!credentials || !(profileName in credentials.profiles)) {
+            this.error(`Profile '${profileName}' not found.\n` + `Create a profile using 'xano profile create'`);
+        }
+        const profile = credentials.profiles[profileName];
+        if (!profile.instance_origin) {
+            this.error(`Profile '${profileName}' is missing instance_origin`);
+        }
+        if (!profile.access_token) {
+            this.error(`Profile '${profileName}' is missing access_token`);
+        }
+        return { profile, profileName };
+    }
+    /**
+     * Parse an API error response and return a clean error message.
+     * Extracts the message from JSON responses and adds context for common errors.
+     */
+    async parseApiError(response, fallbackPrefix) {
+        const errorText = await response.text();
+        let message = `${fallbackPrefix} (${response.status})`;
+        try {
+            const errorJson = JSON.parse(errorText);
+            if (errorJson.message) {
+                message = errorJson.message;
+            }
+        }
+        catch {
+            if (errorText) {
+                message += `\n${errorText}`;
+            }
+        }
+        // Provide guidance when sandbox access is denied (free plan restriction)
+        if (response.status === 500 && message === 'Access Denied.') {
+            message = 'Sandbox is not available on the Free plan. Upgrade your plan to use sandbox features.';
+        }
+        return message;
+    }
     /**
      * Make an HTTP request with optional verbose logging.
      * Use this for all Metadata API calls to support the --verbose flag.

package/dist/commands/auth/index.d.ts

@@ -3,6 +3,7 @@ export default class Auth extends Command {
     static description: string;
     static examples: string[];
     static flags: {
+        config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         insecure: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         origin: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
     };

package/dist/commands/auth/index.js

@@ -4,10 +4,9 @@ import inquirer from 'inquirer';
 import * as yaml from 'js-yaml';
 import * as fs from 'node:fs';
 import * as http from 'node:http';
-import * as os from 'node:os';
-import { join } from 'node:path';
+import { dirname } from 'node:path';
 import open from 'open';
-import { buildUserAgent } from '../../base-command.js';
+import { buildUserAgent, resolveCredentialsPath } from '../../base-command.js';
 const AUTH_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
 export default class Auth extends Command {
     static description = 'Authenticate with Xano via browser login';
@@ -23,6 +22,12 @@ Profile 'default' created successfully!`,
 Opening browser for Xano login at https://custom.xano.com...`,
     ];
     static flags = {
+        config: Flags.string({
+            char: 'c',
+            description: 'Path to credentials file (default: ~/.xano/credentials.yaml)',
+            env: 'XANO_CONFIG',
+            required: false,
+        }),
         insecure: Flags.boolean({
             char: 'k',
             default: false,
@@ -101,7 +106,7 @@ Opening browser for Xano login at https://custom.xano.com...`,
                 instance_origin: instance.origin,
                 name: profileName,
                 workspace: workspace?.id,
-            });
+            }, flags.config);
             this.log('');
             this.log(`Profile '${profileName}' created successfully!`);
             // Ensure clean exit (the open() call can keep the event loop alive)
@@ -206,12 +211,12 @@ Opening browser for Xano login at https://custom.xano.com...`,
         ]);
         return profileName.trim() || 'default';
     }
-    async saveProfile(profile) {
-        const configDir = join(os.homedir(), '.xano');
-        const credentialsPath = join(configDir, 'credentials.yaml');
-        // Ensure the .xano directory exists
-        if (!fs.existsSync(configDir)) {
-            fs.mkdirSync(configDir, { recursive: true });
+    async saveProfile(profile, configPath) {
+        const credentialsPath = resolveCredentialsPath(configPath);
+        const credDir = dirname(credentialsPath);
+        // Ensure the directory exists
+        if (!fs.existsSync(credDir)) {
+            fs.mkdirSync(credDir, { recursive: true });
         }
         // Read existing credentials file or create new structure
         let credentials = { profiles: {} };
@@ -283,7 +288,7 @@ Opening browser for Xano login at https://custom.xano.com...`,
                 choices: [
                     { name: '(Skip workspace)', value: '' },
                     ...workspaces.map((ws) => ({
-                        name: ws.name,
+                        name: `${ws.name} (${ws.id})`,
                         value: ws.id,
                     })),
                 ],

package/dist/commands/branch/create/index.d.ts

@@ -1,14 +1,17 @@
 import BaseCommand from '../../../base-command.js';
 export default class BranchCreate extends BaseCommand {
     static description: string;
+    static args: {
+        label: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
     static examples: string[];
     static flags: {
         color: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         description: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        label: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         source: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         workspace: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };

package/dist/commands/branch/create/index.js

@@ -1,22 +1,26 @@
-import { Flags } from '@oclif/core';
+import { Args, Flags } from '@oclif/core';
 import * as yaml from 'js-yaml';
 import * as fs from 'node:fs';
-import * as os from 'node:os';
-import * as path from 'node:path';
 import BaseCommand from '../../../base-command.js';
 export default class BranchCreate extends BaseCommand {
     static description = 'Create a new branch by cloning from an existing branch';
+    static args = {
+        label: Args.string({
+            description: 'Label for the new branch',
+            required: true,
+        }),
+    };
     static examples = [
-        `$ xano branch create --label dev
+        `$ xano branch create dev
 Created branch: dev
   Cloned from: v1
 `,
-        `$ xano branch create -l feature-auth -s dev -d "Authentication feature"
+        `$ xano branch create feature-auth -s dev -d "Authentication feature"
 Created branch: feature-auth
   Cloned from: dev
   Description: Authentication feature
 `,
-        `$ xano branch create --label staging --color "#ebc346" --output json
+        `$ xano branch create staging --color "#ebc346" --output json
 {
   "created_at": "2024-02-11T10:00:00Z",
   "label": "staging",
@@ -37,11 +41,6 @@ Created branch: feature-auth
             description: 'Description for the new branch',
             required: false,
         }),
-        label: Flags.string({
-            char: 'l',
-            description: 'Label for the new branch',
-            required: true,
-        }),
         output: Flags.string({
             char: 'o',
             default: 'summary',
@@ -62,7 +61,7 @@ Created branch: feature-auth
         }),
     };
     async run() {
-        const { flags } = await this.parse(BranchCreate);
+        const { args, flags } = await this.parse(BranchCreate);
         // Get profile name (default or from flag/env)
         const profileName = flags.profile || this.getDefaultProfile();
         // Load credentials
@@ -84,11 +83,15 @@ Created branch: feature-auth
         const workspaceId = flags.workspace || profile.workspace;
         if (!workspaceId) {
             this.error('No workspace ID provided. Either use --workspace flag or set one in your profile.\n' +
-                'Usage: xano branch create --label <label> [--workspace <workspace_id>]');
+                'Usage: xano branch create <label> [--workspace <workspace_id>]');
+        }
+        // Validate reserved branch names
+        if (args.label.toLowerCase() === 'v1') {
+            this.error("Cannot create a branch named 'v1'. This is the default branch and always exists.");
         }
         // Build request body
         const body = {
-            label: flags.label,
+            label: args.label,
             source_branch: flags.source,
         };
         if (flags.description) {
@@ -104,8 +107,8 @@ Created branch: feature-auth
             const response = await this.verboseFetch(apiUrl, {
                 body: JSON.stringify(body),
                 headers: {
-                    'accept': 'application/json',
-                    'Authorization': `Bearer ${profile.access_token}`,
+                    accept: 'application/json',
+                    Authorization: `Bearer ${profile.access_token}`,
                     'Content-Type': 'application/json',
                 },
                 method: 'POST',
@@ -114,7 +117,7 @@ Created branch: feature-auth
                 const errorText = await response.text();
                 this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
             }
-            const branch = await response.json();
+            const branch = (await response.json());
             // Output results
             if (flags.output === 'json') {
                 this.log(JSON.stringify(branch, null, 2));
@@ -141,12 +144,10 @@ Created branch: feature-auth
         }
     }
     loadCredentials() {
-        const configDir = path.join(os.homedir(), '.xano');
-        const credentialsPath = path.join(configDir, 'credentials.yaml');
+        const credentialsPath = this.getCredentialsPath();
         // Check if credentials file exists
         if (!fs.existsSync(credentialsPath)) {
-            this.error(`Credentials file not found at ${credentialsPath}\n` +
-                `Create a profile using 'xano profile create'`);
+            this.error(`Credentials file not found at ${credentialsPath}\n` + `Create a profile using 'xano profile create'`);
         }
         // Read credentials file
         try {