axinstall 1.1.0 → 1.3.0

package/README.md

@@ -6,24 +6,37 @@ Install AI CLI agents (Claude Code, Codex, Gemini, etc.) in any environment.
 
 ```bash
 # Install Claude Code globally
-npx axinstall claude
+npx -y axinstall "claude"
 
 # Install with a specific package manager
-npx axinstall claude --with npm
+npx -y axinstall "claude" --with "npm"
 
 # Preview what would be installed (dry run)
-npx axinstall claude --dry-run
+npx -y axinstall "claude" --dry-run
 
 # List supported agents
-npx axinstall --list-agents
+npx -y axinstall --list-agents
 
 # Check installed agents and available package managers
-npx axinstall --status
+npx -y axinstall --status
+
+# Enable verbose output
+npx -y axinstall "claude" --verbose
 ```
 
-## Requirements
+## Prerequisites
+
+- Node.js >=22.14.0
+- Use `pnpm dlx` (recommended) or `npx` (bundled with npm) for one-off runs
+- Examples assume a POSIX shell (sh/bash/zsh); adjust for PowerShell or CMD
+
+By default, `axinstall` installs agents using **npm**. This means `npm` must be
+available unless you explicitly override the installer:
+
+- `--with <installer>` (e.g., `--with "pnpm"`)
+- `AXINSTALL_WITH=<installer>`
 
-axinstall needs at least one supported package manager available:
+Supported installers:
 
 - npm
 - pnpm
@@ -31,6 +44,11 @@ axinstall needs at least one supported package manager available:
 - yarn
 - Homebrew (`brew`)
 
+## Conventions
+
+- Prefer long flags in scripts (`--verbose` instead of `-v`)
+- Examples include explicit quoting for flag values and arguments
+
 ### Custom Paths
 
 Override the default binary lookup by setting environment variables:
@@ -48,34 +66,54 @@ export AXINSTALL_BREW_PATH=/path/to/brew
 ### Install agents
 
 ```bash
-# Install using auto-detected package manager (pnpm > bun > yarn > npm > brew)
-axinstall claude
-axinstall codex
-axinstall gemini
+# Install using npm (default)
+npx -y axinstall "claude"
+npx -y axinstall "codex"
+npx -y axinstall "gemini"
 
 # Force a specific package manager
-axinstall claude --with npm
-axinstall opencode --with brew
+npx -y axinstall "claude" --with "npm"
+npx -y axinstall "opencode" --with "brew"
 
 # Install locally (not globally)
-axinstall claude --local
+npx -y axinstall "claude" --local
 ```
 
 ### Pipeline examples
 
 ```bash
 # Get list of agent CLI names
-axinstall --list-agents | tail -n +2 | cut -f1
+npx -y axinstall --list-agents | tail -n +2 | cut -f1
 
 # Find agents from a specific provider
-axinstall --list-agents | tail -n +2 | awk -F'\t' '$4 == "Anthropic" {print $1}'
+npx -y axinstall --list-agents | tail -n +2 | awk -F'\t' '$4 == "Anthropic" {print $1}'
 
 # Get available installers only
-axinstall --status --only installers | tail -n +2 | awk -F'\t' '$4 == "available" {print $2}'
+npx -y axinstall --status --only "installers" | tail -n +2 | awk -F'\t' '$4 == "available" {print $2}'
 
 # Count installed vs not found agents
-axinstall --status --only agents | tail -n +2 | cut -f4 | sort | uniq -c
+npx -y axinstall --status --only "agents" | tail -n +2 | cut -f4 | sort | uniq -c
+```
+
+## Output
+
+`--list-agents` prints a tab-separated header and rows with columns:
+
+```
+CLI	NAME	PACKAGE	PROVIDER
+```
+
+`--status` prints a tab-separated header and rows with columns:
+
 ```
+TYPE	ID	NAME	STATUS	VERSION	PROVIDER	PACKAGE
+```
+
+- `TYPE` values: `AGENT` | `INSTALLER`
+- `STATUS` values:
+  - for `AGENT`: `installed` | `not_found`
+  - for `INSTALLER`: `available` | `not_found`
+- `--only` values: `"all"` | `"agents"` | `"installers"`
 
 ## Agent Rule
 
@@ -86,9 +124,9 @@ Add to your `CLAUDE.md` or `AGENTS.md`:
 
 Run `npx -y axinstall --help` to learn available options.
 
-Use `axinstall` to install AI CLI agents in any environment. It auto-detects
-the best available package manager (pnpm, bun, yarn, npm, brew) and handles
-the installation with a single command.
+Use `axinstall` to install AI CLI agents in any environment. It uses the
+requested package manager (via `--with` / `AXINSTALL_WITH`) and uses npm
+by default.
 ```
 
 ## License

package/dist/cli.d.ts

@@ -3,6 +3,6 @@
  * axinstall - AI agent installation CLI.
  *
  * Installs CLI agents (Claude Code, Codex, Gemini, etc.) using
- * the best available package manager in the environment.
+ * npm by default (override via --with or AXINSTALL_WITH).
  */
 export {};

package/dist/cli.js

@@ -3,7 +3,7 @@
  * axinstall - AI agent installation CLI.
  *
  * Installs CLI agents (Claude Code, Codex, Gemini, etc.) using
- * the best available package manager in the environment.
+ * npm by default (override via --with or AXINSTALL_WITH).
  */
 import { Command } from "@commander-js/extra-typings";
 import { AGENT_CLIS } from "axshared";
@@ -31,20 +31,25 @@ const program = new Command()
     .showSuggestionAfterError()
     .option("--list-agents", "List supported agents")
     .option("--status", "Show installed agents and available package managers")
-    .option("--only <scope>", "Limit --status output (agents|installers). Default: all.")
+    .option("--only <scope>", "Limit --status output (all|agents|installers). Default: all.")
     .option("-v, --verbose", "Enable verbose output")
     .addHelpText("after", `
 Examples:
-  $ axinstall claude                              Install Claude Code
-  $ axinstall claude --with npm                   Use specific package manager
-  $ axinstall claude --dry-run                    Preview installation command
+  $ axinstall "claude"                              Install Claude Code globally
+  $ axinstall "claude" --local                      Install to node_modules/.bin
+  $ axinstall "claude" --with "npm"                 Use specific package manager
+  $ axinstall "claude" --dry-run                    Preview installation command
   $ axinstall --list-agents | tail -n +2 | cut -f1   List agent CLI names
-  $ axinstall --status --only installers | grep available  Show available installers
+  $ axinstall --status --only "installers" | grep available  Show available installers
 
 Environment:
-  AXINSTALL_WITH    Default package manager (${INSTALLER_NAMES})
+  AXINSTALL_WITH    Force package manager (${INSTALLER_NAMES})
 
-Requirements:
+Default:
+  npm (requires npm unless overridden)
+  To use pnpm/bun/yarn/brew, pass --with <installer> or set AXINSTALL_WITH=<installer>.
+
+Supported installers:
   ${INSTALLER_NAMES}
   Override paths: ${INSTALLER_ENV_VARS}`);
 // =============================================================================
@@ -53,6 +58,7 @@ Requirements:
 program
     .argument("[agent]", `Agent to install (${AGENT_CLIS.join(", ")})`)
     .option("--with <installer>", `Package manager to use (${INSTALLER_IDS.join(", ")})`)
+    .option("--local", "Install to node_modules/.bin (run via package runner)", false)
     .option("--dry-run", "Show command without executing", false)
     .action((agentCli, cliOptions) => {
     runCommand(agentCli, cliOptions);

package/dist/detect-agent.js

@@ -3,14 +3,14 @@
  *
  * Detects which AI agents are installed in the current environment.
  */
-import { execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import { getAllAgents } from "axshared";
 /**
  * Check if a single agent is installed by running `<cli> --version`.
  */
 function checkAgent(agent) {
     try {
-        const output = execSync(`${agent.cli} --version`, {
+        const output = execFileSync(agent.cli, ["--version"], {
             encoding: "utf8",
             stdio: ["pipe", "pipe", "pipe"],
         }).trim();

package/dist/detect-installer.d.ts

@@ -16,14 +16,14 @@ declare function checkAllInstallers(): InstallerCheckResult[];
  * Get all available installers.
  */
 declare function getAvailableInstallers(): Installer[];
-/**
- * Auto-detect the best available installer based on priority.
- *
- * Priority order: npm > pnpm > bun > yarn > brew
- */
-declare function detectBestInstaller(): Installer | undefined;
 /**
  * Check if a specific installer is available.
  */
 declare function isInstallerAvailable(id: InstallerId): boolean;
-export { checkInstaller, checkAllInstallers, getAvailableInstallers, detectBestInstaller, isInstallerAvailable, };
+/**
+ * Detect the best available installer based on `INSTALLER_PRIORITY`.
+ *
+ * Retained for library consumers; the CLI defaults to npm unless overridden.
+ */
+declare function detectBestInstaller(): Installer | undefined;
+export { checkInstaller, checkAllInstallers, getAvailableInstallers, isInstallerAvailable, detectBestInstaller, };

package/dist/detect-installer.js

@@ -46,24 +46,23 @@ function getAvailableInstallers() {
         .map((result) => result.installer);
 }
 /**
- * Auto-detect the best available installer based on priority.
+ * Check if a specific installer is available.
+ */
+function isInstallerAvailable(id) {
+    const installer = getInstaller(id);
+    return checkInstaller(installer).available;
+}
+/**
+ * Detect the best available installer based on `INSTALLER_PRIORITY`.
  *
- * Priority order: npm > pnpm > bun > yarn > brew
+ * Retained for library consumers; the CLI defaults to npm unless overridden.
  */
 function detectBestInstaller() {
-    const available = new Set(getAvailableInstallers().map((installer) => installer.id));
     for (const id of INSTALLER_PRIORITY) {
-        if (available.has(id)) {
-            return getInstaller(id);
-        }
+        if (!isInstallerAvailable(id))
+            continue;
+        return getInstaller(id);
     }
     return undefined;
 }
-/**
- * Check if a specific installer is available.
- */
-function isInstallerAvailable(id) {
-    const installer = getInstaller(id);
-    return checkInstaller(installer).available;
-}
-export { checkInstaller, checkAllInstallers, getAvailableInstallers, detectBestInstaller, isInstallerAvailable, };
+export { checkInstaller, checkAllInstallers, getAvailableInstallers, isInstallerAvailable, detectBestInstaller, };

package/dist/execute-install.d.ts

@@ -6,6 +6,8 @@ import type { Installer } from "./types.js";
 interface InstallOptions {
     agent: Agent;
     installer: Installer;
+    /** Install locally instead of globally. Defaults to false. */
+    local?: boolean;
     dryRun: boolean;
 }
 interface InstallResult {

package/dist/execute-install.js

@@ -5,13 +5,23 @@ import { execFileSync } from "node:child_process";
 import { resolveInstallerCommand } from "./resolve-installer-command.js";
 /**
  * Build the installation arguments for an agent.
+ *
+ * @throws {Error} If local install is requested but the installer doesn't support it.
  */
 function buildInstallArguments(options) {
-    const { agent, installer } = options;
+    const { agent, installer, local } = options;
     // For brew, use the CLI name as the package name (formula name)
     // For npm-based installers, use the npm package name
     const packageName = installer.id === "brew" ? agent.cli : agent.package;
-    return installer.installArgs.map((argument) => argument.replace("{package}", packageName));
+    // Reject local installs when the installer doesn't support them
+    if (local) {
+        if (!installer.localInstallArgs) {
+            throw new Error(`Installer '${installer.id}' does not support local installation`);
+        }
+        return installer.localInstallArgs.map((argument) => argument.replace("{package}", packageName));
+    }
+    const installArguments = installer.installArgs;
+    return installArguments.map((argument) => argument.replace("{package}", packageName));
 }
 function formatCommand(command, arguments_) {
     const parts = [command, ...arguments_];
@@ -29,7 +39,19 @@ function buildInstallCommand(options) {
  */
 function executeInstall(options) {
     const command = resolveInstallerCommand(options.installer);
-    const arguments_ = buildInstallArguments(options);
+    // Wrap argument building to catch validation errors and return InstallOutcome
+    let arguments_;
+    try {
+        arguments_ = buildInstallArguments(options);
+    }
+    catch (error) {
+        const localFlag = options.local ? " (local)" : "";
+        return {
+            ok: false,
+            command: `${options.installer.id}${localFlag}: ${command} ...`,
+            error: error instanceof Error ? error : new Error(String(error)),
+        };
+    }
     const displayCommand = formatCommand(command, arguments_);
     if (options.dryRun) {
         return { ok: true, command: displayCommand };

package/dist/handle-install.d.ts

@@ -3,6 +3,7 @@
  */
 interface InstallOptions {
     with?: string;
+    local: boolean;
     dryRun: boolean;
     verbose?: boolean;
 }

package/dist/handle-install.js

@@ -2,22 +2,24 @@
  * Agent installation handler.
  */
 import { AGENT_CLIS, getAgent, isValidAgentCli } from "axshared";
-import { detectBestInstaller, isInstallerAvailable, } from "./detect-installer.js";
+import { isInstallerAvailable } from "./detect-installer.js";
 import { executeInstall } from "./execute-install.js";
-import { getInstaller } from "./installer-data.js";
+import { getAllInstallers, getInstaller } from "./installer-data.js";
 import { resolveInstallerCommand } from "./resolve-installer-command.js";
 import { INSTALLER_IDS } from "./types.js";
 const INSTALLER_ID_SET = new Set(INSTALLER_IDS);
 const INSTALLER_NAMES = INSTALLER_IDS.join(", ");
-const INSTALLER_ENV_VARS = INSTALLER_IDS.map((id) => getInstaller(id).envVar).join(", ");
 function isInstallerId(value) {
     return INSTALLER_ID_SET.has(value);
 }
 function reportMissingInstaller(installer) {
     const command = resolveInstallerCommand(installer);
     console.error(`Error: Installer '${installer.id}' not available`);
-    console.error(`Looked for: ${command}`);
+    // Escape control characters/newlines from env-var-controlled paths without
+    // adding surrounding quotes.
+    console.error(`Looked for: ${JSON.stringify(command).slice(1, -1)}`);
     console.error(`Install ${installer.name} and try again.`);
+    console.error(`To use a different installer, pass --with <installer> (${INSTALLER_NAMES}) or set AXINSTALL_WITH=<installer>.`);
     console.error(`Override path: ${installer.envVar}=/path/to/${installer.command}`);
     console.error(`Run 'axinstall --status --only installers' to verify availability.`);
     process.exitCode = 1;
@@ -31,36 +33,35 @@ export function handleInstall(agentCli, options) {
         return;
     }
     const agent = getAgent(agentCli);
-    const requestedInstaller = options.with ?? process.env["AXINSTALL_WITH"];
-    let installer;
-    if (requestedInstaller) {
-        if (!isInstallerId(requestedInstaller)) {
-            console.error(`Error: Unknown installer '${requestedInstaller}'`);
-            console.error(`Available: ${INSTALLER_IDS.join(", ")}`);
-            console.error("Try 'axinstall --help' for usage information.");
-            process.exitCode = 1;
-            return;
-        }
-        installer = getInstaller(requestedInstaller);
-        if (!isInstallerAvailable(requestedInstaller)) {
-            reportMissingInstaller(installer);
-            return;
-        }
+    const rawInstallerInput = options.with ?? process.env["AXINSTALL_WITH"];
+    const requestedInstaller = rawInstallerInput?.trim() || "npm";
+    if (!isInstallerId(requestedInstaller)) {
+        console.error(`Error: Unknown installer '${requestedInstaller}'`);
+        console.error(`Available: ${INSTALLER_IDS.join(", ")}`);
+        console.error("Try 'axinstall --help' for usage information.");
+        process.exitCode = 1;
+        return;
     }
-    else {
-        installer = detectBestInstaller();
-        if (!installer) {
-            console.error("Error: No package manager found");
-            console.error(`Install ${INSTALLER_NAMES} and try again.`);
-            console.error(`Override paths: ${INSTALLER_ENV_VARS}`);
-            console.error("Run 'axinstall --status --only installers' to verify availability.");
-            process.exitCode = 1;
-            return;
-        }
+    const installer = getInstaller(requestedInstaller);
+    if (!isInstallerAvailable(requestedInstaller)) {
+        reportMissingInstaller(installer);
+        return;
+    }
+    // Validate local installation support
+    if (options.local && !installer.localInstallArgs) {
+        const localInstallers = getAllInstallers()
+            .filter((installer_) => installer_.localInstallArgs)
+            .map((installer_) => installer_.id)
+            .join(", ");
+        console.error(`Error: Installer '${installer.id}' does not support local installation`);
+        console.error(`Use a different installer: ${localInstallers}`);
+        process.exitCode = 1;
+        return;
     }
     const result = executeInstall({
         agent,
         installer,
+        local: options.local,
         dryRun: options.dryRun,
     });
     if (options.dryRun) {
@@ -70,11 +71,27 @@ export function handleInstall(agentCli, options) {
     if (result.ok) {
         if (options.verbose) {
             console.error(`Successfully installed ${agent.name}.`);
-            console.error(`Run '${agent.cli}' to get started.`);
+            if (options.local) {
+                // Suggest the appropriate runner for the installer used
+                const runnerCommands = {
+                    npm: `npx ${agent.cli}`,
+                    pnpm: `pnpm exec ${agent.cli}`,
+                    bun: `bunx ${agent.cli}`,
+                    yarn: `yarn run ${agent.cli}`,
+                    brew: agent.cli, // brew installs globally
+                };
+                console.error(`Run '${runnerCommands[installer.id]}' to get started.`);
+            }
+            else {
+                console.error(`Run '${agent.cli}' to get started.`);
+            }
         }
         return;
     }
     console.error(`Error: Failed to install ${agent.name}`);
     console.error(`Command: ${result.command}`);
+    if (result.error.message) {
+        console.error(`Details: ${result.error.message}`);
+    }
     process.exitCode = 1;
 }

package/dist/index.d.ts

@@ -5,8 +5,9 @@
  */
 export { INSTALLER_IDS } from "./types.js";
 export type { Installer, InstallerId, InstallerCheckResult } from "./types.js";
-export { getInstaller, getAllInstallers, INSTALLERS, INSTALLER_PRIORITY, } from "./installer-data.js";
-export { checkInstaller, checkAllInstallers, getAvailableInstallers, detectBestInstaller, isInstallerAvailable, } from "./detect-installer.js";
+export { getInstaller, getAllInstallers, INSTALLERS, } from "./installer-data.js";
+export { checkInstaller, checkAllInstallers, detectBestInstaller, getAvailableInstallers, isInstallerAvailable, } from "./detect-installer.js";
+export { INSTALLER_PRIORITY } from "./installer-data.js";
 export { checkAgent, checkAllAgents, getInstalledAgents, } from "./detect-agent.js";
 export type { AgentCheckResult } from "./detect-agent.js";
 export { buildInstallCommand, executeInstall } from "./execute-install.js";

package/dist/index.js

@@ -6,9 +6,10 @@
 // Types
 export { INSTALLER_IDS } from "./types.js";
 // Installer data
-export { getInstaller, getAllInstallers, INSTALLERS, INSTALLER_PRIORITY, } from "./installer-data.js";
+export { getInstaller, getAllInstallers, INSTALLERS, } from "./installer-data.js";
 // Installer detection
-export { checkInstaller, checkAllInstallers, getAvailableInstallers, detectBestInstaller, isInstallerAvailable, } from "./detect-installer.js";
+export { checkInstaller, checkAllInstallers, detectBestInstaller, getAvailableInstallers, isInstallerAvailable, } from "./detect-installer.js";
+export { INSTALLER_PRIORITY } from "./installer-data.js";
 // Agent detection
 export { checkAgent, checkAllAgents, getInstalledAgents, } from "./detect-agent.js";
 // Installation

package/dist/installer-data.d.ts

@@ -2,10 +2,19 @@
  * Installer definitions and metadata.
  */
 import type { Installer, InstallerId } from "./types.js";
+/**
+ * Installer preference order used by `detectBestInstaller()` (library API).
+ *
+ * The CLI defaults to npm by design; this list is retained for programmatic
+ * consumers who want auto-detection.
+ *
+ * Note: Keep this order stable unless intentionally making a behavior change
+ * for library consumers.
+ */
+declare const INSTALLER_PRIORITY: readonly InstallerId[];
 /** All installers indexed by ID */
 declare const INSTALLERS: Record<InstallerId, Installer>;
-/** Default priority order for auto-detection */
-declare const INSTALLER_PRIORITY: readonly InstallerId[];
 declare function getInstaller(id: InstallerId): Installer;
 declare function getAllInstallers(): Installer[];
-export { getInstaller, getAllInstallers, INSTALLERS, INSTALLER_PRIORITY };
+export { getInstaller, getAllInstallers, INSTALLERS };
+export { INSTALLER_PRIORITY };

package/dist/installer-data.js

@@ -1,6 +1,22 @@
 /**
  * Installer definitions and metadata.
  */
+/**
+ * Installer preference order used by `detectBestInstaller()` (library API).
+ *
+ * The CLI defaults to npm by design; this list is retained for programmatic
+ * consumers who want auto-detection.
+ *
+ * Note: Keep this order stable unless intentionally making a behavior change
+ * for library consumers.
+ */
+const INSTALLER_PRIORITY = [
+    "npm",
+    "pnpm",
+    "bun",
+    "yarn",
+    "brew",
+];
 const npm = {
     id: "npm",
     name: "npm",
@@ -8,6 +24,7 @@ const npm = {
     envVar: "AXINSTALL_NPM_PATH",
     checkArgs: ["--version"],
     installArgs: ["install", "-g", "{package}"],
+    localInstallArgs: ["install", "{package}"],
 };
 const pnpm = {
     id: "pnpm",
@@ -16,6 +33,7 @@ const pnpm = {
     envVar: "AXINSTALL_PNPM_PATH",
     checkArgs: ["--version"],
     installArgs: ["add", "-g", "{package}"],
+    localInstallArgs: ["add", "{package}"],
 };
 const bun = {
     id: "bun",
@@ -24,6 +42,7 @@ const bun = {
     envVar: "AXINSTALL_BUN_PATH",
     checkArgs: ["--version"],
     installArgs: ["add", "-g", "{package}"],
+    localInstallArgs: ["add", "{package}"],
 };
 const yarn = {
     id: "yarn",
@@ -32,6 +51,7 @@ const yarn = {
     envVar: "AXINSTALL_YARN_PATH",
     checkArgs: ["--version"],
     installArgs: ["global", "add", "{package}"],
+    localInstallArgs: ["add", "{package}"],
 };
 const brew = {
     id: "brew",
@@ -40,6 +60,7 @@ const brew = {
     envVar: "AXINSTALL_BREW_PATH",
     checkArgs: ["--version"],
     installArgs: ["install", "{package}"],
+    // No localInstallArgs - brew only installs globally
 };
 /** All installers indexed by ID */
 const INSTALLERS = {
@@ -49,18 +70,11 @@ const INSTALLERS = {
     yarn,
     brew,
 };
-/** Default priority order for auto-detection */
-const INSTALLER_PRIORITY = [
-    "npm",
-    "pnpm",
-    "bun",
-    "yarn",
-    "brew",
-];
 function getInstaller(id) {
     return INSTALLERS[id];
 }
 function getAllInstallers() {
     return Object.values(INSTALLERS);
 }
-export { getInstaller, getAllInstallers, INSTALLERS, INSTALLER_PRIORITY };
+export { getInstaller, getAllInstallers, INSTALLERS };
+export { INSTALLER_PRIORITY };

package/dist/resolve-installer-command.js

@@ -1,5 +1,6 @@
 function resolveInstallerCommand(installer) {
     const override = process.env[installer.envVar];
-    return override && override.length > 0 ? override : installer.command;
+    const trimmedOverride = override?.trim();
+    return trimmedOverride || installer.command;
 }
 export { resolveInstallerCommand };

package/dist/run-command.d.ts

@@ -7,6 +7,7 @@ export interface CliOptions {
     only?: string;
     verbose?: boolean;
     with?: string;
+    local: boolean;
     dryRun: boolean;
 }
 export declare function runCommand(agentCli: string | undefined, options: CliOptions): void;

package/dist/run-command.js

@@ -6,7 +6,7 @@ import { isStatusScope, printStatus, printSupportedAgents, } from "./print-statu
 import { validateOptions } from "./validate-cli-options.js";
 function reportUsageError(message) {
     console.error(`Error: ${message}`);
-    console.error("Usage: axinstall [options] <agent>");
+    console.error("Usage: axinstall [options] [agent]");
     console.error("       axinstall --list-agents");
     console.error("       axinstall --status [--only <scope>]");
     console.error("Try 'axinstall --help' for usage information.");
@@ -25,14 +25,14 @@ export function runCommand(agentCli, options) {
     if (options.status) {
         const scopeInput = options.only?.toLowerCase() ?? "all";
         if (!isStatusScope(scopeInput)) {
-            reportUsageError(`Invalid --only value '${options.only}'. Use agents or installers.`);
+            reportUsageError(`Invalid --only value '${options.only}'. Use all, agents, or installers.`);
             return;
         }
         printStatus(scopeInput);
         return;
     }
     if (!agentCli) {
-        reportUsageError("Missing required argument 'agent'.");
+        reportUsageError("Missing required argument 'agent' (or use --list-agents/--status).");
         return;
     }
     handleInstall(agentCli, options);

package/dist/types.d.ts

@@ -16,6 +16,8 @@ interface Installer {
     checkArgs: readonly string[];
     /** Args for global install. Use {package} as placeholder. */
     installArgs: readonly string[];
+    /** Args for local install. Use {package} as placeholder. Undefined if not supported. */
+    localInstallArgs?: readonly string[];
 }
 /** Result of checking installer availability */
 interface InstallerCheckResult {

package/dist/validate-cli-options.js

@@ -26,6 +26,12 @@ export function validateOptions(agentCli, options) {
             message: "--dry-run is only valid when installing an agent.",
         };
     }
+    if ((options.listAgents || options.status) && options.local) {
+        return {
+            valid: false,
+            message: "--local is only valid when installing an agent.",
+        };
+    }
     if (options.only && !options.status) {
         return { valid: false, message: "--only must be used with --status." };
     }

package/package.json

@@ -2,8 +2,8 @@
   "name": "axinstall",
   "author": "Łukasz Jerciński",
   "license": "MIT",
-  "version": "1.1.0",
-  "description": "Universal installer for AI CLI agents with automatic package manager detection",
+  "version": "1.3.0",
+  "description": "Universal installer for AI CLI agents (defaults to npm)",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Jercik/axinstall.git"
@@ -43,9 +43,9 @@
     "rebuild": "pnpm run clean && pnpm run build",
     "start": "pnpm -s run rebuild && node bin/axinstall",
     "test": "vitest run --exclude '**/*.integration.test.ts'",
+    "test:all": "vitest run --testTimeout=300000",
     "test:coverage": "vitest run --coverage --exclude '**/*.integration.test.ts'",
     "test:integration": "vitest run --testTimeout=300000 src/docker-install.integration.test.ts",
-    "test:all": "vitest run --testTimeout=300000",
     "test:watch": "vitest --exclude '**/*.integration.test.ts'",
     "typecheck": "tsc -b --noEmit"
   },
@@ -63,33 +63,27 @@
     "automation",
     "coding-assistant"
   ],
-  "packageManager": "pnpm@10.26.1",
+  "packageManager": "pnpm@10.28.1",
   "engines": {
     "node": ">=22.14.0"
   },
   "dependencies": {
     "@commander-js/extra-typings": "^14.0.0",
-    "axshared": "^1.8.0",
+    "axshared": "^4.0.0",
     "commander": "^14.0.2"
   },
   "devDependencies": {
-    "@eslint/compat": "^2.0.0",
-    "@eslint/js": "^9.39.2",
     "@total-typescript/ts-reset": "^0.6.1",
-    "@types/node": "^25.0.3",
-    "@vitest/coverage-v8": "^4.0.16",
-    "@vitest/eslint-plugin": "^1.6.5",
+    "@types/node": "^25.0.10",
+    "@vitest/coverage-v8": "^4.0.17",
     "eslint": "^9.39.2",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-unicorn": "^62.0.0",
+    "eslint-config-axkit": "^1.1.0",
     "fta-check": "^1.5.1",
     "fta-cli": "^3.0.0",
-    "globals": "^16.5.0",
-    "knip": "^5.80.0",
-    "prettier": "3.7.4",
+    "knip": "^5.82.1",
+    "prettier": "3.8.1",
     "semantic-release": "^25.0.2",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.52.0",
-    "vitest": "^4.0.16"
+    "vitest": "^4.0.17"
   }
 }