axusage 2.2.0 → 3.0.0

package/README.md

@@ -12,15 +12,47 @@ npm install -g axusage
 claude
 codex
 gemini
-axusage auth setup github-copilot
+axusage --auth-setup github-copilot --interactive
 
 # Check authentication status
-axusage auth status
+axusage --auth-status
+# For CLI-auth services, this reports CLI availability; use the CLI to confirm login.
 
 # Fetch usage
 axusage
 ```
 
+## Requirements
+
+- `claude` CLI (Claude auth) — `npm install -g @anthropic-ai/claude-code`
+- `codex` CLI (ChatGPT auth) — `npm install -g @openai/codex`
+- `gemini` CLI (Gemini auth) — `npm install -g @google/gemini-cli`
+- Playwright Chromium for GitHub Copilot auth (see "Browser installation" below for global install steps)
+
+### Custom Paths
+
+If the CLIs are not on your `PATH`, override the binaries:
+
+```bash
+export AXUSAGE_CLAUDE_PATH=/path/to/claude
+export AXUSAGE_CODEX_PATH=/path/to/codex
+export AXUSAGE_GEMINI_PATH=/path/to/gemini
+
+# Optional: adjust CLI dependency check timeout (milliseconds)
+export AXUSAGE_CLI_TIMEOUT_MS=5000
+```
+
+For Playwright-managed browsers:
+
+```bash
+export PLAYWRIGHT_BROWSERS_PATH=/path/to/playwright-browsers
+```
+
+### Exit Codes
+
+- `0`: success
+- `1`: errors, including partial failures
+
 ## Authentication
 
 Claude, ChatGPT, and Gemini use their respective CLI OAuth sessions. GitHub
@@ -33,13 +65,16 @@ Copilot uses browser-based authentication for persistent, long-lived sessions.
 claude
 codex
 gemini
-axusage auth setup github-copilot
+axusage --auth-setup github-copilot --interactive
 
 # Check authentication status
-axusage auth status
+axusage --auth-status
 ```
 
-When you run `auth setup` for GitHub Copilot, a browser window will open.
+`--auth-status` reports browser-auth status for GitHub Copilot and CLI availability
+for Claude/ChatGPT/Gemini. Use `claude`, `codex`, or `gemini` to confirm CLI login.
+
+When you run `axusage --auth-setup github-copilot --interactive`, a browser window will open.
 Simply log in to GitHub as you normally would. Your authentication will be
 saved and automatically used for future requests.
 
@@ -62,9 +97,13 @@ Security notes:
 - To revoke access for GitHub Copilot, clear saved browser auth:
 
 ```bash
-axusage auth clear github-copilot
+axusage --auth-clear github-copilot --interactive
 ```
 
+This moves the saved browser files to your system Trash/Recycle Bin (recoverable).
+
+Use `--force` to skip confirmation in scripts.
+
 Browser installation:
 
 - Playwright Chromium is installed automatically on `pnpm install` via a postinstall script. If this fails in your environment, install manually:
@@ -111,6 +150,9 @@ axusage --service claude --format=json
 
 # TSV output (parseable with cut, awk, sort)
 axusage --format=tsv
+
+# Disable color output
+axusage --no-color
 ```
 
 ## Examples
@@ -169,16 +211,17 @@ Use `axusage` when you need a quick, scriptable snapshot of API usage across Cla
 
 - The CLI shows a countdown while waiting for login.
 - If you have completed login, press Enter in the terminal to continue.
-- If it still fails, run `axusage auth clear <service>` and retry.
+- If it still fails, run `axusage --auth-clear <service> --interactive` and retry.
 
 ### "No saved authentication" error
 
-- Check which services are authenticated: `axusage auth status`.
-- Set up the missing service: `axusage auth setup <service>`.
+- Check which services are authenticated: `axusage --auth-status`.
+- For GitHub Copilot, set up the missing service: `axusage --auth-setup <service> --interactive`.
+- For Claude/ChatGPT/Gemini, run the provider CLI to authenticate.
 
 ### Sessions expire
 
-- Browser sessions can expire based on provider policy. Re-run `auth setup` for the affected service when you see authentication errors.
+- Browser sessions can expire based on provider policy. Re-run `axusage --auth-setup <service> --interactive` for the affected service when you see authentication errors.
 
 ## Remote authentication and Prometheus export
 
@@ -195,15 +238,17 @@ You can perform the interactive login flow on a workstation (for example, a loca
    claude
    codex
    gemini
-   axusage auth setup github-copilot
+   axusage --auth-setup github-copilot --interactive
    ```
 
 2. Confirm the workstation has valid sessions:
 
    ```bash
-   axusage auth status
+   axusage --auth-status
    ```
 
+   For CLI-auth services, run `claude`, `codex`, or `gemini` to confirm login.
+
 3. Package the saved contexts so they can be transferred. Set `CONTEXT_DIR` to the path for your platform (see the table above):
 
    ```bash
@@ -211,7 +256,8 @@ You can perform the interactive login flow on a workstation (for example, a loca
    tar czf axusage-contexts.tgz -C "$(dirname "$CONTEXT_DIR")" "$(basename "$CONTEXT_DIR")"
    ```
 
-   Archive structure: `browser-contexts/claude/`, `browser-contexts/chatgpt/`, etc.
+   Archive structure: `browser-contexts/github-copilot-auth.json` plus matching
+   `github-copilot-auth.meta.json` (CLI-auth services do not use browser contexts).
 
 ### 2. Transfer the browser contexts to the Linux server
 
@@ -237,7 +283,7 @@ You can perform the interactive login flow on a workstation (for example, a loca
 3. Verify that the sessions are available on the server:
 
    ```bash
-   axusage auth status
+   axusage --auth-status
    ```
 
    If the server does not yet have the tool installed, run `npm install -g axusage` before checking the status.
@@ -245,7 +291,7 @@ You can perform the interactive login flow on a workstation (for example, a loca
 Notes:
 
 - Use `--service <name>` to restrict services.
-- Sessions may expire or become invalid if you change your password or log out of the service in another browser. Re-run `auth setup` as needed.
+- Sessions may expire or become invalid if you change your password or log out of the service in another browser. Re-run `axusage --auth-setup <service> --interactive` as needed.
 - If you transfer browser contexts between machines, ensure the target system is secure and permissions are restricted to the intended user.
 - The CLI stores authentication data in the platform-specific directories listed above; protect that directory to prevent unauthorized access.
 

package/dist/adapters/github-copilot.js

@@ -16,7 +16,8 @@ export const githubCopilotAdapter = {
             if (!manager.hasAuth("github-copilot")) {
                 return {
                     ok: false,
-                    error: new ApiError("No saved authentication for github-copilot. Run 'axusage auth setup github-copilot' first."),
+                    error: new ApiError("No saved authentication for github-copilot. " +
+                        "Run 'axusage --auth-setup github-copilot --interactive' first."),
                 };
             }
             const body = await manager.makeAuthenticatedRequest("github-copilot", API_URL);

package/dist/cli.js

@@ -1,13 +1,18 @@
 #!/usr/bin/env node
 import { Command, Option } from "@commander-js/extra-typings";
 import packageJson from "../package.json" with { type: "json" };
-import { usageCommand } from "./commands/usage-command.js";
+import { authClearCommand } from "./commands/auth-clear-command.js";
 import { authSetupCommand } from "./commands/auth-setup-command.js";
 import { authStatusCommand } from "./commands/auth-status-command.js";
-import { authClearCommand } from "./commands/auth-clear-command.js";
+import { usageCommand } from "./commands/usage-command.js";
+import { getBrowserContextsDirectory } from "./services/app-paths.js";
 import { getAvailableServices } from "./services/service-adapter-registry.js";
 import { installAuthManagerCleanup } from "./services/shared-browser-auth-manager.js";
-import { getBrowserContextsDirectory } from "./services/app-paths.js";
+import { configureColor } from "./utils/color.js";
+import { getRootOptionsError, } from "./utils/validate-root-options.js";
+// Parse --no-color early so help/error output is consistently uncolored.
+const shouldDisableColor = process.argv.includes("--no-color");
+configureColor({ enabled: shouldDisableColor ? false : undefined });
 const program = new Command()
     .name(packageJson.name)
     .description(packageJson.description)
@@ -15,49 +20,60 @@ const program = new Command()
     .showHelpAfterError("(add --help for additional information)")
     .showSuggestionAfterError()
     .helpCommand(false)
-    .addHelpText("after", `\nExamples:\n  # Fetch usage for all services\n  ${packageJson.name}\n\n  # JSON output for a single service\n  ${packageJson.name} --service claude --format=json\n\n  # TSV output for piping to cut, awk, sort\n  ${packageJson.name} --format=tsv | tail -n +2 | awk -F'\\t' '{print $1, $4"%"}'\n\n  # Filter Prometheus metrics with standard tools\n  ${packageJson.name} --format=prometheus | grep axusage_utilization_percent\n`);
-// Ensure browser resources are cleaned when process exits
-installAuthManagerCleanup();
-// Usage command (default)
-program
-    .command("usage", { isDefault: true })
-    .description("Fetch API usage statistics (defaults to all: Claude, ChatGPT, GitHub Copilot)")
+    .option("--no-color", "disable color output")
     .option("-s, --service <service>", `Service to query (${getAvailableServices().join(", ")}, all) - defaults to all`)
-    .option("-i, --interactive", "allow interactive re-authentication during usage fetch")
+    .option("-i, --interactive", "allow interactive authentication prompts (usage reauth, --auth-setup/--auth-clear; ignored with --auth-status)")
     .addOption(new Option("-o, --format <format>", "Output format")
     .choices(["text", "tsv", "json", "prometheus"])
     .default("text"))
-    .addHelpText("after", `\nExamples:\n  # Query all services (default)\n  ${packageJson.name}\n\n  # Query a single service\n  ${packageJson.name} --service claude\n\n  # TSV output for piping to Unix tools\n  ${packageJson.name} --format=tsv | tail -n +2 | cut -f1,4\n\n  # Filter Prometheus metrics\n  ${packageJson.name} --format=prometheus | grep claude\n`)
-    .action(async (options) => {
-    await usageCommand(options);
-});
-// Auth command group
-const auth = program
-    .command("auth")
-    .description("Manage authentication for services")
-    .helpCommand(false)
-    .addHelpText("after", `\nStorage: ${getBrowserContextsDirectory()}\n(respects XDG_DATA_HOME and platform defaults)`);
-auth
-    .command("setup")
-    .description("Set up browser-based authentication for a service")
-    .argument("<service>", "Service to authenticate (claude, chatgpt, github-copilot)")
-    .action(async (service) => {
-    await authSetupCommand({ service });
-});
-auth
-    .command("status")
-    .description("Check authentication status for services")
-    .option("-s, --service <service>", "Check status for specific service")
-    .action((options) => {
-    authStatusCommand(options);
-});
-auth
-    .command("clear")
-    .description("Clear saved browser authentication for a service")
-    .argument("<service>", "Service to clear (claude, chatgpt, github-copilot)")
-    .action(async (service) => {
-    await authClearCommand({ service });
+    .option("--auth-setup <service>", "set up authentication for a service (CLI or browser-based)")
+    .option("--auth-status [service]", "check authentication status for services")
+    .option("--auth-clear <service>", "clear saved browser authentication for a service (moves files to system Trash)")
+    .option("-f, --force", "skip confirmation for destructive actions")
+    .addHelpText("after", `\nExamples:\n  # Fetch usage for all services\n  ${packageJson.name}\n\n  # JSON output for a single service\n  ${packageJson.name} --service claude --format=json\n\n  # TSV output for piping to cut, awk, sort\n  ${packageJson.name} --format=tsv | tail -n +2 | awk -F'\\t' '{print $1, $4"%"}'\n\n  # Filter Prometheus metrics with standard tools\n  ${packageJson.name} --format=prometheus | grep axusage_utilization_percent\n\n  # Check authentication status for all services\n  ${packageJson.name} --auth-status\n\nStorage: ${getBrowserContextsDirectory()}\n(respects XDG_DATA_HOME and platform defaults)\n\nRequires: claude, codex (ChatGPT), gemini (CLI auth); Playwright Chromium (GitHub Copilot auth)\nOverride CLI paths: AXUSAGE_CLAUDE_PATH, AXUSAGE_CODEX_PATH, AXUSAGE_GEMINI_PATH\nPlaywright: PLAYWRIGHT_BROWSERS_PATH\n`);
+function fail(message) {
+    console.error(`Error: ${message}`);
+    console.error("Try 'axusage --help' for details.");
+    if (process.exitCode === undefined)
+        process.exitCode = 1;
+}
+program.action(async (options, command) => {
+    const errorMessage = getRootOptionsError(options, command.getOptionValueSource("format"));
+    if (errorMessage) {
+        fail(errorMessage);
+        return;
+    }
+    if (options.authSetup) {
+        await authSetupCommand({
+            service: options.authSetup,
+            interactive: options.interactive,
+        });
+        return;
+    }
+    if (options.authStatus !== undefined) {
+        const service = typeof options.authStatus === "string" && options.authStatus.length > 0
+            ? options.authStatus
+            : undefined;
+        authStatusCommand({ service });
+        return;
+    }
+    if (options.authClear) {
+        await authClearCommand({
+            service: options.authClear,
+            interactive: options.interactive,
+            force: options.force,
+        });
+        return;
+    }
+    const usageOptions = {
+        service: options.service,
+        format: options.format,
+        interactive: options.interactive,
+    };
+    await usageCommand(usageOptions);
 });
+// Ensure browser resources are cleaned when process exits
+installAuthManagerCleanup();
 try {
     await program.parseAsync();
 }

package/dist/commands/auth-clear-command.d.ts

@@ -1,5 +1,7 @@
 type AuthClearOptions = {
     readonly service?: string;
+    readonly interactive?: boolean;
+    readonly force?: boolean;
 };
 export declare function authClearCommand(options: AuthClearOptions): Promise<void>;
 export {};

package/dist/commands/auth-clear-command.js

@@ -1,20 +1,79 @@
-import chalk from "chalk";
-import { existsSync } from "node:fs";
+import { confirm } from "@inquirer/prompts";
+import { existsSync, readdirSync } from "node:fs";
+import path from "node:path";
 import trash from "trash";
 import { validateService } from "../services/supported-service.js";
 import { getAuthMetaPathFor, getStorageStatePathFor, } from "../services/auth-storage-path.js";
 import { getBrowserContextsDirectory } from "../services/app-paths.js";
+import { chalk } from "../utils/color.js";
+import { resolvePromptCapability } from "../utils/resolve-prompt-capability.js";
+function isPromptCancellation(error) {
+    return (error instanceof Error &&
+        (error.name === "AbortPromptError" ||
+            error.name === "CancelPromptError" ||
+            error.name === "ExitPromptError"));
+}
+function collectRelatedArtifacts(filePath) {
+    const directory = path.dirname(filePath);
+    const baseName = path.basename(filePath);
+    try {
+        return readdirSync(directory)
+            .filter((entry) => entry.startsWith(`${baseName}.`) &&
+            (entry.endsWith(".bak") || entry.endsWith(".tmp")))
+            .map((entry) => path.join(directory, entry));
+    }
+    catch {
+        return [];
+    }
+}
 export async function authClearCommand(options) {
     const service = validateService(options.service);
     const dataDirectory = getBrowserContextsDirectory();
     const storage = getStorageStatePathFor(dataDirectory, service);
     const meta = getAuthMetaPathFor(dataDirectory, service);
     try {
-        const targets = [storage, meta].filter((p) => existsSync(p));
+        const artifactTargets = [storage, meta].filter((p) => existsSync(p));
+        const backupTargets = [storage, meta].flatMap((filePath) => collectRelatedArtifacts(filePath));
+        const targets = [...new Set([...artifactTargets, ...backupTargets])];
         if (targets.length === 0) {
             console.error(chalk.gray(`\nNo saved authentication found for ${service}.`));
             return;
         }
+        if (!options.force) {
+            if (!options.interactive) {
+                console.error(chalk.red("Error: Clearing saved authentication requires confirmation."));
+                console.error(chalk.gray("Re-run with --interactive to confirm, or use --force to skip confirmation."));
+                console.error(chalk.gray("Try 'axusage --help' for details."));
+                process.exitCode = 1;
+                return;
+            }
+            if (!resolvePromptCapability()) {
+                console.error(chalk.red("Error: --interactive requires a TTY-enabled terminal."));
+                console.error(chalk.gray("Re-run in a terminal or pass --force instead."));
+                console.error(chalk.gray("Try 'axusage --help' for details."));
+                process.exitCode = 1;
+                return;
+            }
+            let confirmed = false;
+            try {
+                confirmed = await confirm({
+                    message: `Remove saved authentication for ${service}?`,
+                    default: false,
+                });
+            }
+            catch (error) {
+                if (isPromptCancellation(error)) {
+                    console.error(chalk.gray("Aborted."));
+                    process.exitCode = 1;
+                    return;
+                }
+                throw error;
+            }
+            if (!confirmed) {
+                console.error(chalk.gray("Aborted."));
+                return;
+            }
+        }
         await trash(targets, { glob: false });
         console.error(chalk.green(`\n✓ Cleared authentication for ${service}`));
     }

package/dist/commands/auth-setup-command.d.ts

@@ -3,6 +3,7 @@
  */
 type AuthSetupOptions = {
     readonly service?: string;
+    readonly interactive?: boolean;
 };
 /**
  * Set up authentication for a service

package/dist/commands/auth-setup-command.js

@@ -1,6 +1,8 @@
-import chalk from "chalk";
 import { BrowserAuthManager } from "../services/browser-auth-manager.js";
 import { validateService } from "../services/supported-service.js";
+import { resolveAuthCliDependencyOrReport } from "../utils/check-cli-dependency.js";
+import { chalk } from "../utils/color.js";
+import { resolvePromptCapability } from "../utils/resolve-prompt-capability.js";
 /**
  * Set up authentication for a service
  */
@@ -8,32 +10,61 @@ export async function authSetupCommand(options) {
     const service = validateService(options.service);
     // CLI-based auth - users should run the native CLI directly
     if (service === "gemini") {
+        const cliPath = resolveAuthCliDependencyOrReport("gemini", {
+            setExitCode: true,
+        });
+        if (!cliPath)
+            return;
         console.error(chalk.yellow("\nGemini uses CLI-based authentication managed by the Gemini CLI."));
         console.error(chalk.gray("\nTo authenticate, run:"));
-        console.error(chalk.cyan("  gemini"));
+        console.error(chalk.cyan(`  ${cliPath}`));
         console.error(chalk.gray("\nThe Gemini CLI will guide you through the OAuth login process.\n"));
         return;
     }
     if (service === "claude") {
+        const cliPath = resolveAuthCliDependencyOrReport("claude", {
+            setExitCode: true,
+        });
+        if (!cliPath)
+            return;
         console.error(chalk.yellow("\nClaude uses CLI-based authentication managed by Claude Code."));
         console.error(chalk.gray("\nTo authenticate, run:"));
-        console.error(chalk.cyan("  claude"));
+        console.error(chalk.cyan(`  ${cliPath}`));
         console.error(chalk.gray("\nClaude Code will guide you through authentication.\n"));
         return;
     }
     if (service === "chatgpt") {
+        const cliPath = resolveAuthCliDependencyOrReport("chatgpt", {
+            setExitCode: true,
+        });
+        if (!cliPath)
+            return;
         console.error(chalk.yellow("\nChatGPT uses CLI-based authentication managed by Codex."));
         console.error(chalk.gray("\nTo authenticate, run:"));
-        console.error(chalk.cyan("  codex"));
+        console.error(chalk.cyan(`  ${cliPath}`));
         console.error(chalk.gray("\nCodex will guide you through authentication.\n"));
         return;
     }
+    if (!options.interactive) {
+        console.error(chalk.red("Error: Authentication setup requires --interactive."));
+        console.error(chalk.gray("Re-run with --interactive in a TTY-enabled terminal to continue."));
+        console.error(chalk.gray("Try 'axusage --help' for details."));
+        process.exitCode = 1;
+        return;
+    }
+    if (!resolvePromptCapability()) {
+        console.error(chalk.red("Error: --interactive requires a TTY-enabled terminal."));
+        console.error(chalk.gray("Re-run in a terminal session to complete authentication."));
+        console.error(chalk.gray("Try 'axusage --help' for details."));
+        process.exitCode = 1;
+        return;
+    }
     const manager = new BrowserAuthManager({ headless: false });
     try {
         console.error(chalk.blue(`\nSetting up authentication for ${service}...\n`));
         await manager.setupAuth(service);
         console.error(chalk.green(`\n✓ Authentication for ${service} is complete!`));
-        console.error(chalk.gray(`\nYou can now run: ${chalk.cyan(`axusage usage --service ${service}`)}`));
+        console.error(chalk.gray(`\nYou can now run: ${chalk.cyan(`axusage --service ${service}`)}`));
     }
     catch (error) {
         console.error(chalk.red(`\n✗ Failed to set up authentication for ${service}: ${error instanceof Error ? error.message : String(error)}`));

package/dist/commands/auth-status-command.js

@@ -1,25 +1,57 @@
-import chalk from "chalk";
 import { existsSync } from "node:fs";
 import { SUPPORTED_SERVICES, validateService, } from "../services/supported-service.js";
 import { getStorageStatePathFor } from "../services/auth-storage-path.js";
 import { getBrowserContextsDirectory } from "../services/app-paths.js";
+import { AUTH_CLI_SERVICES, checkCliDependency, getAuthCliDependency, } from "../utils/check-cli-dependency.js";
+import { chalk } from "../utils/color.js";
 export function authStatusCommand(options) {
     const servicesToCheck = options.service
         ? [validateService(options.service)]
         : SUPPORTED_SERVICES;
+    const cliAuthServices = new Set(AUTH_CLI_SERVICES);
     const dataDirectory = getBrowserContextsDirectory();
+    let hasFailures = false;
     console.log(chalk.blue("\nAuthentication Status:\n"));
     for (const service of servicesToCheck) {
+        if (cliAuthServices.has(service)) {
+            const dependency = getAuthCliDependency(service);
+            const result = checkCliDependency(dependency);
+            const status = result.ok
+                ? chalk.green("↪ CLI-managed")
+                : chalk.red("✗ CLI missing");
+            if (!result.ok) {
+                hasFailures = true;
+            }
+            console.log(`${chalk.bold(service)}: ${status}`);
+            console.log(`  ${chalk.dim("CLI:")} ${chalk.dim(result.path)}`);
+            if (result.ok) {
+                console.log(`  ${chalk.dim("Auth:")} ${chalk.dim(`run ${result.path} to check/login`)}`);
+            }
+            else {
+                console.log(`  ${chalk.dim("Install:")} ${chalk.dim(dependency.installHint)}`);
+                console.log(`  ${chalk.dim("Override:")} ${chalk.dim(`${dependency.envVar}=/path/to/${dependency.command}`)}`);
+            }
+            continue;
+        }
         const storagePath = getStorageStatePathFor(dataDirectory, service);
         const hasAuth = existsSync(storagePath);
         const status = hasAuth
             ? chalk.green("✓ Authenticated")
             : chalk.gray("✗ Not authenticated");
+        if (!hasAuth) {
+            hasFailures = true;
+        }
         console.log(`${chalk.bold(service)}: ${status}`);
         console.log(`  ${chalk.dim("Storage:")} ${chalk.dim(storagePath)}`);
     }
-    const allAuthenticated = servicesToCheck.every((s) => existsSync(getStorageStatePathFor(dataDirectory, s)));
-    if (!allAuthenticated) {
-        console.error(chalk.gray(`\nTo set up authentication, run: ${chalk.cyan("axusage auth setup <service>")}`));
+    const browserServices = servicesToCheck.filter((service) => !cliAuthServices.has(service));
+    const copilotService = "github-copilot";
+    const needsCopilotSetup = browserServices.includes(copilotService) &&
+        !existsSync(getStorageStatePathFor(dataDirectory, copilotService));
+    if (needsCopilotSetup) {
+        console.error(chalk.gray(`\nTo set up authentication, run: ${chalk.cyan("axusage --auth-setup github-copilot --interactive")}`));
+    }
+    if (hasFailures) {
+        process.exitCode = 1;
     }
 }

package/dist/commands/fetch-service-usage-with-reauth.js

@@ -1,7 +1,7 @@
-import chalk from "chalk";
 import { fetchServiceUsage } from "./fetch-service-usage.js";
 import { isAuthFailure, runAuthSetup } from "./run-auth-setup.js";
 import { validateService } from "../services/supported-service.js";
+import { chalk } from "../utils/color.js";
 /**
  * Fetch usage for a service, with automatic re-authentication on auth errors.
  * Prompts the user to re-authenticate if the initial fetch fails with an auth error,
@@ -14,7 +14,7 @@ export async function fetchServiceUsageWithAutoReauth(serviceName, interactive)
     }
     // If auth error, try to re-authenticate and retry
     if (isAuthFailure(result)) {
-        console.error(chalk.yellow(`⚠ Authentication failed for ${serviceName}. Opening browser to re-authenticate...`));
+        console.error(chalk.yellow(`⚠ Authentication failed for ${serviceName}. Attempting to re-authenticate...`));
         try {
             const service = validateService(serviceName);
             const authSuccess = await runAuthSetup(service);

package/dist/commands/fetch-service-usage.js

@@ -1,5 +1,5 @@
 import { ApiError as ApiErrorClass } from "../types/domain.js";
-import { getServiceAdapter } from "../services/service-adapter-registry.js";
+import { getAvailableServices, getServiceAdapter, } from "../services/service-adapter-registry.js";
 const ALL_SERVICES = ["claude", "chatgpt", "github-copilot", "gemini"];
 export function selectServicesToQuery(service) {
     const normalized = service?.toLowerCase();
@@ -10,9 +10,11 @@ export function selectServicesToQuery(service) {
 export async function fetchServiceUsage(serviceName) {
     const adapter = getServiceAdapter(serviceName);
     if (!adapter) {
+        const available = getAvailableServices().join(", ");
         return {
             ok: false,
-            error: new ApiErrorClass(`Unknown service "${serviceName}"`),
+            error: new ApiErrorClass(`Unknown service "${serviceName}". Supported services: ${available}. ` +
+                "Run 'axusage --help' for usage."),
         };
     }
     return await adapter.fetchUsage();

package/dist/commands/run-auth-setup.js

@@ -1,5 +1,7 @@
-import chalk from "chalk";
 import { BrowserAuthManager } from "../services/browser-auth-manager.js";
+import { resolveAuthCliDependencyOrReport } from "../utils/check-cli-dependency.js";
+import { chalk } from "../utils/color.js";
+import { resolvePromptCapability } from "../utils/resolve-prompt-capability.js";
 /** Timeout for authentication setup (5 minutes) */
 const AUTH_SETUP_TIMEOUT_MS = 300_000;
 /**
@@ -46,31 +48,46 @@ export function isAuthFailure(result) {
 export async function runAuthSetup(service) {
     // CLI-based auth cannot use browser auth flow
     if (service === "gemini") {
+        const cliPath = resolveAuthCliDependencyOrReport("gemini");
+        if (!cliPath)
+            return false;
         console.error(chalk.yellow("\nGemini uses CLI-based authentication managed by the Gemini CLI."));
         console.error(chalk.gray("\nTo re-authenticate, run:"));
-        console.error(chalk.cyan("  gemini"));
+        console.error(chalk.cyan(`  ${cliPath}`));
         console.error(chalk.gray("\nThe Gemini CLI will guide you through the OAuth login process.\n"));
         return false;
     }
     if (service === "claude") {
+        const cliPath = resolveAuthCliDependencyOrReport("claude");
+        if (!cliPath)
+            return false;
         console.error(chalk.yellow("\nClaude uses CLI-based authentication managed by Claude Code."));
         console.error(chalk.gray("\nTo re-authenticate, run:"));
-        console.error(chalk.cyan("  claude"));
+        console.error(chalk.cyan(`  ${cliPath}`));
         console.error(chalk.gray("\nClaude Code will guide you through authentication.\n"));
         return false;
     }
     if (service === "chatgpt") {
+        const cliPath = resolveAuthCliDependencyOrReport("chatgpt");
+        if (!cliPath)
+            return false;
         console.error(chalk.yellow("\nChatGPT uses CLI-based authentication managed by Codex."));
         console.error(chalk.gray("\nTo re-authenticate, run:"));
-        console.error(chalk.cyan("  codex"));
+        console.error(chalk.cyan(`  ${cliPath}`));
         console.error(chalk.gray("\nCodex will guide you through authentication.\n"));
         return false;
     }
+    if (!resolvePromptCapability()) {
+        console.error(chalk.red("Error: Interactive authentication requires a TTY terminal."));
+        console.error(chalk.gray("Re-run in a TTY terminal (avoid piping stdin/stdout) with --interactive to complete authentication."));
+        return false;
+    }
     const manager = new BrowserAuthManager({ headless: false });
+    let setupPromise;
     let timeoutId;
     try {
         console.error(chalk.blue(`\nOpening browser for ${service} authentication...\n`));
-        const setupPromise = manager.setupAuth(service);
+        setupPromise = manager.setupAuth(service);
         const timeoutPromise = new Promise((_, reject) => {
             timeoutId = setTimeout(() => {
                 reject(new Error("Authentication setup timed out after 5 minutes"));
@@ -86,6 +103,10 @@ export async function runAuthSetup(service) {
     }
     finally {
         clearTimeout(timeoutId);
+        if (setupPromise) {
+            // Avoid unhandled rejections if the timeout wins the race.
+            void setupPromise.catch(() => { });
+        }
         await manager.close();
     }
 }