axinstall 1.2.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,21 +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 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 "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}`);
 // =============================================================================

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/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 { 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,32 +33,19 @@ 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) {

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",
@@ -54,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.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/package.json

@@ -2,8 +2,8 @@
   "name": "axinstall",
   "author": "Łukasz Jerciński",
   "license": "MIT",
-  "version": "1.2.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"
@@ -63,27 +63,27 @@
     "automation",
     "coding-assistant"
   ],
-  "packageManager": "pnpm@10.27.0",
+  "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": {
     "@total-typescript/ts-reset": "^0.6.1",
-    "@types/node": "^25.0.3",
-    "@vitest/coverage-v8": "^4.0.16",
+    "@types/node": "^25.0.10",
+    "@vitest/coverage-v8": "^4.0.17",
     "eslint": "^9.39.2",
-    "eslint-config-axkit": "^1.0.0",
+    "eslint-config-axkit": "^1.1.0",
     "fta-check": "^1.5.1",
     "fta-cli": "^3.0.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",
-    "vitest": "^4.0.16"
+    "vitest": "^4.0.17"
   }
 }