@appkit/llamacpp-cli 1.0.0

package/dist/utils/process-utils.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.execAsync = void 0;
+exports.execCommand = execCommand;
+exports.execCommandFull = execCommandFull;
+exports.commandExists = commandExists;
+exports.isProcessRunning = isProcessRunning;
+exports.isPortInUse = isPortInUse;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+exports.execAsync = (0, util_1.promisify)(child_process_1.exec);
+/**
+ * Execute a command and return stdout
+ * Throws on non-zero exit code
+ */
+async function execCommand(command) {
+    const { stdout } = await (0, exports.execAsync)(command);
+    return stdout.trim();
+}
+/**
+ * Execute a command and return both stdout and stderr
+ */
+async function execCommandFull(command) {
+    const { stdout, stderr } = await (0, exports.execAsync)(command);
+    return {
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+    };
+}
+/**
+ * Check if a command exists in PATH
+ */
+async function commandExists(command) {
+    try {
+        await (0, exports.execAsync)(`which ${command}`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a process is running by PID
+ */
+async function isProcessRunning(pid) {
+    try {
+        await (0, exports.execAsync)(`ps -p ${pid}`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a port is in use
+ */
+async function isPortInUse(port) {
+    try {
+        await (0, exports.execAsync)(`lsof -iTCP:${port} -sTCP:LISTEN -t`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=process-utils.js.map

package/dist/utils/process-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-utils.js","sourceRoot":"","sources":["../../src/utils/process-utils.ts"],"names":[],"mappings":";;;AASA,kCAGC;AAKD,0CAMC;AAKD,sCAOC;AAKD,4CAOC;AAKD,kCAOC;AA3DD,iDAAqC;AACrC,+BAAiC;AAEpB,QAAA,SAAS,GAAG,IAAA,gBAAS,EAAC,oBAAI,CAAC,CAAC;AAEzC;;;GAGG;AACI,KAAK,UAAU,WAAW,CAAC,OAAe;IAC/C,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,IAAA,iBAAS,EAAC,OAAO,CAAC,CAAC;IAC5C,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;AACvB,CAAC;AAED;;GAEG;AACI,KAAK,UAAU,eAAe,CAAC,OAAe;IACnD,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,IAAA,iBAAS,EAAC,OAAO,CAAC,CAAC;IACpD,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE;QACrB,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE;KACtB,CAAC;AACJ,CAAC;AAED;;GAEG;AACI,KAAK,UAAU,aAAa,CAAC,OAAe;IACjD,IAAI,CAAC;QACH,MAAM,IAAA,iBAAS,EAAC,SAAS,OAAO,EAAE,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;GAEG;AACI,KAAK,UAAU,gBAAgB,CAAC,GAAW;IAChD,IAAI,CAAC;QACH,MAAM,IAAA,iBAAS,EAAC,SAAS,GAAG,EAAE,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;GAEG;AACI,KAAK,UAAU,WAAW,CAAC,IAAY;IAC5C,IAAI,CAAC;QACH,MAAM,IAAA,iBAAS,EAAC,cAAc,IAAI,kBAAkB,CAAC,CAAC;QACtD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@appkit/llamacpp-cli",
+  "version": "1.0.0",
+  "description": "CLI tool to manage local llama.cpp servers on macOS",
+  "main": "dist/cli.js",
+  "bin": {
+    "llamacpp": "./bin/llamacpp"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build",
+    "release": "commit-and-tag-version",
+    "release:minor": "commit-and-tag-version --release-as minor",
+    "release:major": "commit-and-tag-version --release-as major",
+    "release:patch": "commit-and-tag-version --release-as patch",
+    "release:first": "commit-and-tag-version --first-release",
+    "postrelease": "git push --follow-tags origin main && npm publish --access public"
+  },
+  "keywords": [
+    "llama",
+    "llama.cpp",
+    "llm",
+    "cli",
+    "server-management",
+    "gguf",
+    "macos",
+    "launchctl"
+  ],
+  "author": "Appkit Studio",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/appkitstudio/llamacpp-cli.git"
+  },
+  "homepage": "https://github.com/appkitstudio/llamacpp-cli#readme",
+  "bugs": {
+    "url": "https://github.com/appkitstudio/llamacpp-cli/issues"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^13.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.7",
+    "commit-and-tag-version": "^12.6.1",
+    "tsx": "^4.7.2",
+    "typescript": "^5.4.5"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { listCommand } from './commands/list';
+import { psCommand } from './commands/ps';
+import { startCommand } from './commands/start';
+import { runCommand } from './commands/run';
+import { stopCommand } from './commands/stop';
+import { deleteCommand } from './commands/delete';
+import { pullCommand } from './commands/pull';
+import { rmCommand } from './commands/rm';
+import { logsCommand } from './commands/logs';
+import { searchCommand } from './commands/search';
+import { showCommand } from './commands/show';
+
+const program = new Command();
+
+program
+  .name('llamacpp')
+  .description('CLI tool to manage local llama.cpp servers on macOS')
+  .version('1.0.0');
+
+// List models
+program
+  .command('ls')
+  .description('List available GGUF models in ~/models')
+  .action(async () => {
+    try {
+      await listCommand();
+    } catch (error) {
+      console.error(chalk.red('❌ Error:'), (error as Error).message);
+      process.exit(1);
+    }
+  });
+
+// List running servers
+program
+  .command('ps')
+  .description('List all servers with status')
+  .action(async () => {
+    try {
+      await psCommand();
+    } catch (error) {
+      console.error(chalk.red('❌ Error:'), (error as Error).message);
+      process.exit(1);
+    }
+  });
+
+// Search for models
+program
+  .command('search')
+  .description('Search Hugging Face for GGUF models')
+  .argument('<query>', 'Search query (e.g., "llama 3b" or "qwen")')
+  .option('-l, --limit <number>', 'Max results to show (default: 20)', parseInt)
+  .option('--files [number]', 'Show available files for result number (e.g., --files 1)', (val) => {
+    return val ? parseInt(val) : true;
+  })
+  .action(async (query: string, options) => {
+    try {
+      await searchCommand(query, options);
+    } catch (error) {
+      console.error(chalk.red('❌ Error:'), (error as Error).message);
+      process.exit(1);
+    }
+  });
+
+// Show model details
+program
+  .command('show')
+  .description('Show details about a model or file')
+  .argument('<identifier>', 'HuggingFace repo/file (e.g., owner/repo or owner/repo/file.gguf)')
+  .option('-f, --file <filename>', 'Specific GGUF file to show details for')
+  .action(async (identifier: string, options) => {
+    try {
+      await showCommand(identifier, options);
+    } catch (error) {
+      console.error(chalk.red('❌ Error:'), (error as Error).message);
+      process.exit(1);
+    }
+  });
+
+// Download a model
+program
+  .command('pull')
+  .description('Download a GGUF model from Hugging Face')
+  .argument('<identifier>', 'HuggingFace repo/file (e.g., owner/repo/file.gguf or owner/repo)')
+  .option('-f, --file <filename>', 'Specific GGUF file (alternative to path in identifier)')
+  .action(async (identifier: string, options) => {
+    try {
+      await pullCommand(identifier, options);
+    } catch (error) {
+      console.error(chalk.red('❌ Error:'), (error as Error).message);
+      process.exit(1);
+    }
+  });
+
+// Delete a model
+program
+  .command('rm')
+  .description('Delete a model file (and any associated servers)')
+  .argument('<model>', 'Model filename or partial name')
+  .action(async (model: string) => {
+    try {
+      await rmCommand(model);
+    } catch (error) {
+      console.error(chalk.red('❌ Error:'), (error as Error).message);
+      process.exit(1);
+    }
+  });
+
+// Server management commands
+const server = program
+  .command('server')
+  .description('Manage llama-server instances');
+
+// Start a server
+server
+  .command('start')
+  .description('Start a llama-server instance')
+  .argument('<model>', 'Model filename or path')
+  .option('-p, --port <number>', 'Port number (default: auto-assign)', parseInt)
+  .option('-t, --threads <number>', 'Thread count (default: auto)', parseInt)
+  .option('-c, --ctx-size <number>', 'Context size (default: auto)', parseInt)
+  .option('-g, --gpu-layers <number>', 'GPU layers (default: 60)', parseInt)
+  .action(async (model: string, options) => {
+    try {
+      await startCommand(model, options);
+    } catch (error) {
+      console.error(chalk.red('❌ Error:'), (error as Error).message);
+      process.exit(1);
+    }
+  });
+
+// Run interactive chat with a model
+server
+  .command('run')
+  .description('Run an interactive chat session with a model')
+  .argument('<model>', 'Model identifier: port (9000), server ID (llama-3-2-3b), partial name, or model filename')
+  .action(async (model: string) => {
+    try {
+      await runCommand(model);
+    } catch (error) {
+      console.error(chalk.red('❌ Error:'), (error as Error).message);
+      process.exit(1);
+    }
+  });
+
+// Stop a server
+server
+  .command('stop')
+  .description('Stop a running server')
+  .argument('<identifier>', 'Server identifier: port (9000), server ID (llama-3-2-3b), or partial model name')
+  .action(async (identifier: string) => {
+    try {
+      await stopCommand(identifier);
+    } catch (error) {
+      console.error(chalk.red('❌ Error:'), (error as Error).message);
+      process.exit(1);
+    }
+  });
+
+// Delete a server
+server
+  .command('rm')
+  .description('Remove a server configuration and launchctl service (preserves model file)')
+  .argument('<identifier>', 'Server identifier: port (9000), server ID (llama-3-2-3b), or partial model name')
+  .action(async (identifier: string) => {
+    try {
+      await deleteCommand(identifier);
+    } catch (error) {
+      console.error(chalk.red('❌ Error:'), (error as Error).message);
+      process.exit(1);
+    }
+  });
+
+// View logs
+server
+  .command('logs')
+  .description('View server logs')
+  .argument('<identifier>', 'Server identifier: port (9000), server ID (llama-3-2-3b), or partial model name')
+  .option('-f, --follow', 'Follow log output in real-time')
+  .option('-n, --lines <number>', 'Number of lines to show (default: 50)', parseInt)
+  .option('--errors', 'Show stderr instead of stdout')
+  .action(async (identifier: string, options) => {
+    try {
+      await logsCommand(identifier, options);
+    } catch (error) {
+      console.error(chalk.red('❌ Error:'), (error as Error).message);
+      process.exit(1);
+    }
+  });
+
+// Parse arguments
+program.parse();

package/src/commands/delete.ts

@@ -0,0 +1,74 @@
+import chalk from 'chalk';
+import * as readline from 'readline';
+import { stateManager } from '../lib/state-manager';
+import { launchctlManager } from '../lib/launchctl-manager';
+
+export async function deleteCommand(identifier: string): Promise<void> {
+  // Find server
+  const server = await stateManager.findServer(identifier);
+  if (!server) {
+    throw new Error(`Server not found: ${identifier}\n\nUse: llamacpp ps`);
+  }
+
+  // Confirm deletion
+  console.log(chalk.yellow(`⚠️  Delete server configuration for ${server.modelName}?`));
+  console.log(chalk.dim('   This will remove the launchd service but keep the model file.'));
+  console.log();
+
+  const confirmed = await confirmDeletion();
+  if (!confirmed) {
+    console.log(chalk.dim('Cancelled'));
+    return;
+  }
+
+  console.log();
+  console.log(chalk.blue(`🗑️  Deleting server ${server.modelName}...`));
+
+  // Stop server if running
+  if (server.status === 'running') {
+    console.log(chalk.dim('Stopping server...'));
+    try {
+      await launchctlManager.stopService(server.label);
+      await launchctlManager.waitForServiceStop(server.label, 5000);
+    } catch (error) {
+      console.log(chalk.yellow('⚠️  Failed to stop server gracefully'));
+    }
+  }
+
+  // Unload service
+  console.log(chalk.dim('Unloading launchctl service...'));
+  await launchctlManager.unloadService(server.plistPath);
+
+  // Delete plist
+  console.log(chalk.dim('Deleting plist file...'));
+  await launchctlManager.deletePlist(server.plistPath);
+
+  // Delete server config
+  console.log(chalk.dim('Deleting server configuration...'));
+  await stateManager.deleteServerConfig(server.id);
+
+  // Success
+  console.log();
+  console.log(chalk.green('✅ Server deleted'));
+  console.log(chalk.dim(`   Plist removed: ${server.plistPath}`));
+  console.log(chalk.dim(`   Config removed`));
+  console.log();
+  console.log(chalk.dim(`   Model file preserved at: ${server.modelPath}`));
+}
+
+/**
+ * Prompt user for confirmation
+ */
+function confirmDeletion(): Promise<boolean> {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    rl.question(chalk.yellow("   Type 'yes' to confirm: "), (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'yes');
+    });
+  });
+}

package/src/commands/list.ts

@@ -0,0 +1,37 @@
+import chalk from 'chalk';
+import Table from 'cli-table3';
+import { modelScanner } from '../lib/model-scanner';
+import { formatBytes, formatDateShort } from '../utils/format-utils';
+import { getModelsDir } from '../utils/file-utils';
+
+export async function listCommand(): Promise<void> {
+  const modelsDir = getModelsDir();
+  console.log(chalk.blue(`📦 Available models in ${modelsDir}\n`));
+
+  const models = await modelScanner.scanModels();
+
+  if (models.length === 0) {
+    console.log(chalk.yellow('No GGUF models found.'));
+    console.log(chalk.dim(`\nDownload models with: llamacpp pull <repo> --file <filename>`));
+    return;
+  }
+
+  const table = new Table({
+    head: ['MODEL', 'SIZE', 'MODIFIED'],
+    colWidths: [50, 12, 15],
+  });
+
+  for (const model of models) {
+    table.push([
+      model.filename,
+      model.sizeFormatted,
+      formatDateShort(model.modified),
+    ]);
+  }
+
+  console.log(table.toString());
+
+  const totalSize = models.reduce((sum, m) => sum + m.size, 0);
+  console.log(chalk.dim(`\nTotal: ${models.length} models (${formatBytes(totalSize)})`));
+  console.log(chalk.dim(`\nStart a server: llamacpp start <model-filename>`));
+}

package/src/commands/logs.ts

@@ -0,0 +1,61 @@
+import chalk from 'chalk';
+import { spawn } from 'child_process';
+import { stateManager } from '../lib/state-manager';
+import { fileExists } from '../utils/file-utils';
+import { execCommand } from '../utils/process-utils';
+
+interface LogsOptions {
+  follow?: boolean;
+  lines?: number;
+  errors?: boolean;
+}
+
+export async function logsCommand(identifier: string, options: LogsOptions): Promise<void> {
+  // Find server
+  const server = await stateManager.findServer(identifier);
+  if (!server) {
+    throw new Error(`Server not found: ${identifier}\n\nUse: llamacpp ps`);
+  }
+
+  // Determine log file
+  const logPath = options.errors ? server.stderrPath : server.stdoutPath;
+  const logType = options.errors ? 'errors' : 'logs';
+
+  // Check if log file exists
+  if (!(await fileExists(logPath))) {
+    console.log(chalk.yellow(`⚠️  No ${logType} found for ${server.modelName}`));
+    console.log(chalk.dim(`   Log file does not exist: ${logPath}`));
+    return;
+  }
+
+  console.log(chalk.blue(`📋 ${options.errors ? 'Errors' : 'Logs'} for ${server.modelName}`));
+  console.log(chalk.dim(`   ${logPath}\n`));
+
+  if (options.follow) {
+    // Follow logs in real-time
+    const tail = spawn('tail', ['-f', logPath], {
+      stdio: 'inherit',
+    });
+
+    // Handle Ctrl+C gracefully
+    process.on('SIGINT', () => {
+      tail.kill();
+      console.log();
+      process.exit(0);
+    });
+
+    // Wait for tail to exit
+    tail.on('exit', () => {
+      process.exit(0);
+    });
+  } else {
+    // Show last N lines
+    const lines = options.lines || 50;
+    try {
+      const output = await execCommand(`tail -n ${lines} "${logPath}"`);
+      console.log(output);
+    } catch (error) {
+      throw new Error(`Failed to read logs: ${(error as Error).message}`);
+    }
+  }
+}

package/src/commands/ps.ts

@@ -0,0 +1,79 @@
+import chalk from 'chalk';
+import Table from 'cli-table3';
+import { stateManager } from '../lib/state-manager';
+import { statusChecker } from '../lib/status-checker';
+import { formatUptime } from '../utils/format-utils';
+
+export async function psCommand(): Promise<void> {
+  const servers = await stateManager.getAllServers();
+
+  if (servers.length === 0) {
+    console.log(chalk.yellow('No servers configured.'));
+    console.log(chalk.dim('\nStart a server: llamacpp server start <model-filename>'));
+    return;
+  }
+
+  // Update all server statuses
+  console.log(chalk.dim('Checking server statuses...\n'));
+  const updated = await statusChecker.updateAllServerStatuses();
+
+  const table = new Table({
+    head: ['SERVER ID', 'MODEL', 'PORT', 'STATUS', 'PID', 'UPTIME'],
+  });
+
+  let runningCount = 0;
+  let stoppedCount = 0;
+  let crashedCount = 0;
+
+  for (const server of updated) {
+    let statusText: string;
+    let statusColor: (text: string) => string;
+
+    switch (server.status) {
+      case 'running':
+        statusText = '✅ RUNNING';
+        statusColor = chalk.green;
+        runningCount++;
+        break;
+      case 'crashed':
+        statusText = '❌ CRASHED';
+        statusColor = chalk.red;
+        crashedCount++;
+        break;
+      default:
+        statusText = '⚠️  STOPPED';
+        statusColor = chalk.yellow;
+        stoppedCount++;
+    }
+
+    const uptime =
+      server.status === 'running' && server.lastStarted
+        ? formatUptime(server.lastStarted)
+        : '-';
+
+    table.push([
+      server.id,
+      server.modelName,
+      server.port.toString(),
+      statusColor(statusText),
+      server.pid?.toString() || '-',
+      uptime,
+    ]);
+  }
+
+  console.log(table.toString());
+
+  const summary = [
+    chalk.green(`${runningCount} running`),
+    chalk.yellow(`${stoppedCount} stopped`),
+  ];
+  if (crashedCount > 0) {
+    summary.push(chalk.red(`${crashedCount} crashed`));
+  }
+
+  console.log(chalk.dim(`\nTotal: ${servers.length} servers (${summary.join(', ')})`));
+
+  if (crashedCount > 0) {
+    console.log(chalk.red('\n⚠️  Some servers have crashed. Check logs with: llamacpp server logs <id> --errors'));
+  }
+}

package/src/commands/pull.ts

@@ -0,0 +1,40 @@
+import chalk from 'chalk';
+import { modelDownloader } from '../lib/model-downloader';
+
+interface PullOptions {
+  file?: string;
+}
+
+export async function pullCommand(identifier: string, options: PullOptions): Promise<void> {
+  // Parse repository identifier
+  const parsed = modelDownloader.parseHFIdentifier(identifier);
+
+  // Determine filename - from --file flag or from identifier path
+  let filename = options.file || parsed.file;
+
+  if (!filename) {
+    throw new Error(
+      'Please specify a file to download:\n\n' +
+      'Option 1: llamacpp pull owner/repo/filename.gguf\n' +
+      'Option 2: llamacpp pull owner/repo --file filename.gguf'
+    );
+  }
+
+  // Ensure filename ends with .gguf
+  if (!filename.toLowerCase().endsWith('.gguf')) {
+    filename += '.gguf';
+  }
+
+  // Download the model
+  try {
+    const modelPath = await modelDownloader.downloadModel(parsed.repo, filename);
+
+    console.log();
+    console.log(chalk.dim(`Start server: llamacpp start ${filename}`));
+  } catch (error) {
+    if ((error as Error).message.includes('interrupted')) {
+      console.log(chalk.dim('\nDownload was interrupted. Run the same command again to retry.'));
+    }
+    throw error;
+  }
+}