@mlx-node/cli 0.0.0 → 0.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mlx-node/cli",
-  "version": "0.0.0",
+  "version": "0.0.2",
   "homepage": "https://github.com/mlx-node/mlx-node",
   "bugs": {
     "url": "https://github.com/mlx-node/mlx-node/issues"
@@ -24,7 +24,7 @@
   "dependencies": {
     "@huggingface/hub": "^2.10.7",
     "@inquirer/prompts": "^8.3.0",
-    "@mlx-node/core": "workspace:*",
+    "@mlx-node/core": "0.0.2",
     "@napi-rs/keyring": "^1.2.0"
   }
-}
+}

package/dist/cli.d.ts

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-export {};
-//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -1,80 +0,0 @@
-#!/usr/bin/env node
-import pkgJson from '../package.json' with { type: 'json' };
-const args = process.argv.slice(2);
-const command = args[0];
-const subcommand = args[1];
-function printHelp() {
-    console.log(`
-mlx - MLX-Node CLI v${pkgJson.version}
-
-Usage:
-  mlx <command> [options]
-
-Commands:
-  download model     Download a model from HuggingFace
-  download dataset   Download a dataset from HuggingFace
-  convert            Convert model weights to MLX format
-
-Options:
-  -h, --help         Show this help message
-  -v, --version      Show version number
-
-Examples:
-  mlx download model -m Qwen/Qwen3-0.6B
-  mlx download dataset -d openai/gsm8k
-  mlx convert -i .cache/models/qwen3-0.6b -o .cache/models/qwen3-0.6b-mlx -d bf16
-`);
-}
-async function main() {
-    if (!command || command === '--help' || command === '-h') {
-        printHelp();
-        return;
-    }
-    if (command === '--version' || command === '-v') {
-        console.log(pkgJson.version);
-        return;
-    }
-    switch (command) {
-        case 'download': {
-            if (!subcommand || subcommand === '--help' || subcommand === '-h') {
-                console.log(`
-Usage:
-  mlx download model     Download a model from HuggingFace
-  mlx download dataset   Download a dataset from HuggingFace
-
-Run mlx download <subcommand> --help for more information.
-`);
-                return;
-            }
-            const rest = args.slice(2);
-            if (subcommand === 'model') {
-                const { run } = await import('./commands/download-model.js');
-                await run(rest);
-            }
-            else if (subcommand === 'dataset') {
-                const { run } = await import('./commands/download-dataset.js');
-                await run(rest);
-            }
-            else {
-                console.error(`Unknown download subcommand: ${subcommand}`);
-                console.error('Available: model, dataset');
-                process.exit(1);
-            }
-            break;
-        }
-        case 'convert': {
-            const rest = args.slice(1);
-            const { run } = await import('./commands/convert.js');
-            await run(rest);
-            break;
-        }
-        default:
-            console.error(`Unknown command: ${command}`);
-            printHelp();
-            process.exit(1);
-    }
-}
-main().catch((error) => {
-    console.error(error);
-    process.exit(1);
-});

package/dist/commands/convert.d.ts

@@ -1,2 +0,0 @@
-export declare function run(argv: string[]): Promise<void>;
-//# sourceMappingURL=convert.d.ts.map

package/dist/commands/convert.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../../src/commands/convert.ts"],"names":[],"mappings":"AAiEA,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,iBAqRvC"}

package/dist/commands/convert.js

@@ -1,316 +0,0 @@
-import { parseArgs } from 'node:util';
-import { resolve } from 'node:path';
-import { readFileSync, existsSync } from 'node:fs';
-import { convertModel, convertForeignWeights, convertGgufToSafetensors } from '@mlx-node/core';
-function printHelp() {
-    console.log(`
-Convert Model Weights to MLX Format
-
-Usage:
-  mlx convert --input <path> --output <dir> [options]
-
-Required Arguments:
-  --input, -i <path>    Input model directory or .gguf file
-  --output, -o <dir>    Output directory for converted model
-
-Optional Arguments:
-  --dtype, -d <type>    Target dtype (default: bfloat16)
-                        Options: float32, float16, bfloat16
-  --model-type, -m      Model type (auto-detected if not specified)
-                        Options: paddleocr-vl, pp-lcnet-ori, uvdoc, qwen3_5, qwen3_5_moe
-  --verbose, -v         Enable verbose logging
-  --help, -h            Show this help message
-
-Vision Arguments:
-  --mmproj <path>       Path to mmproj GGUF file (vision encoder weights)
-                        Converts and merges vision weights into output directory
-
-Quantization Arguments:
-  --quantize, -q        Enable quantization of converted weights
-  --q-bits <int>        Quantization bits (default: 4 for affine, 8 for mxfp8)
-  --q-group-size <int>  Group size (default: 64 for affine, 32 for mxfp8)
-  --q-mode <string>     Mode: "affine" (default) or "mxfp8"
-  --q-recipe <string>   Per-layer mixed-bit quantization recipe
-                        Options: mixed_2_6, mixed_3_4, mixed_3_6, mixed_4_6, qwen3_5, unsloth
-  --imatrix-path <path> imatrix GGUF file for AWQ-style pre-scaling
-                        Improves quantization quality using calibration data
-
-Model Types:
-  (default)             SafeTensors dtype conversion (HuggingFace models)
-  paddleocr-vl          PaddleOCR-VL weight sanitization
-  qwen3_5               Qwen3.5 dense model (FP8 dequant, key remapping)
-  qwen3_5_moe           Qwen3.5 MoE model (FP8 dequant, expert stacking)
-  pp-lcnet-ori          PP-LCNet orientation classifier (Paddle -> SafeTensors)
-  uvdoc                 UVDoc unwarping model (Paddle/PyTorch -> SafeTensors)
-
-GGUF Support:
-  When --input points to a .gguf file, the converter automatically parses the
-  GGUF binary format and converts tensors to SafeTensors. Supports BF16, F16,
-  F32, Q4_0, Q4_1, and Q8_0 tensor types. Tokenizer files are copied from
-  alongside the GGUF file if present.
-
-Examples:
-  mlx convert -i .cache/models/qwen3-0.6b -o .cache/models/qwen3-0.6b-mlx
-  mlx convert -i .cache/models/Qwen3.5-35B-A3B-FP8 -o .cache/models/Qwen3.5-35B-A3B-4bit -m qwen3_5_moe -q --q-bits 4
-  mlx convert -m pp-lcnet-ori -i .cache/models/PP-LCNet -o ./models/PP-LCNet_x1_0_doc_ori/
-  mlx convert -i model.gguf -o ./models/converted-mlx
-  mlx convert -i model-BF16.gguf -o ./models/converted-4bit -q --q-bits 4
-  mlx convert -i model-BF16.gguf -o ./models/mixed-4-6 -q --q-recipe mixed_4_6
-  mlx convert -i .cache/models/qwen3.5-9b -o ./models/qwen35-recipe -q --q-recipe qwen3_5 -m qwen3_5
-  mlx convert -i model-BF16.gguf -o ./models/awq-4bit -q --q-recipe unsloth --imatrix-path imatrix.gguf
-  mlx convert -i .cache/models/Qwen3.5-27B -o ./models/qwen3.5-unsloth -q --q-recipe unsloth --mmproj mmproj-BF16.gguf
-`);
-}
-export async function run(argv) {
-    const { values: args } = parseArgs({
-        args: argv,
-        options: {
-            input: { type: 'string', short: 'i' },
-            output: { type: 'string', short: 'o' },
-            dtype: { type: 'string', short: 'd' },
-            'model-type': { type: 'string', short: 'm' },
-            verbose: { type: 'boolean', short: 'v', default: false },
-            quantize: { type: 'boolean', short: 'q', default: false },
-            'q-bits': { type: 'string' },
-            'q-group-size': { type: 'string' },
-            'q-mode': { type: 'string' },
-            'q-recipe': { type: 'string' },
-            'imatrix-path': { type: 'string' },
-            mmproj: { type: 'string' },
-            help: { type: 'boolean', short: 'h', default: false },
-        },
-    });
-    if (args.help) {
-        printHelp();
-        return;
-    }
-    if (!args.input || !args.output) {
-        console.error('Error: Both --input and --output are required\n');
-        console.error('Use --help for usage information');
-        process.exit(1);
-    }
-    const inputPath = resolve(args.input);
-    const outputDir = resolve(args.output);
-    const verbose = args.verbose;
-    const parsePositiveInt = (flag, raw) => {
-        if (raw === undefined)
-            return undefined;
-        if (!/^[1-9]\d*$/.test(raw)) {
-            console.error(`Error: ${flag} requires a positive integer value`);
-            process.exit(1);
-        }
-        return Number(raw);
-    };
-    const quantBits = parsePositiveInt('--q-bits', args['q-bits']);
-    const quantGroupSize = parsePositiveInt('--q-group-size', args['q-group-size']);
-    const quantMode = args['q-mode'];
-    if (quantMode !== undefined && quantMode !== 'affine' && quantMode !== 'mxfp8') {
-        console.error('Error: --q-mode must be "affine" or "mxfp8"');
-        process.exit(1);
-    }
-    const quantRecipe = args['q-recipe'];
-    const validRecipes = ['mixed_2_6', 'mixed_3_4', 'mixed_3_6', 'mixed_4_6', 'qwen3_5', 'unsloth'];
-    if (quantRecipe !== undefined) {
-        if (!args.quantize) {
-            console.error('Error: --q-recipe requires --quantize (-q) to be enabled');
-            process.exit(1);
-        }
-        if (quantMode === 'mxfp8') {
-            console.error('Error: --q-recipe is incompatible with --q-mode mxfp8');
-            process.exit(1);
-        }
-        if (!validRecipes.includes(quantRecipe)) {
-            console.error(`Error: Unknown recipe "${quantRecipe}". Available: ${validRecipes.join(', ')}`);
-            process.exit(1);
-        }
-    }
-    const mmprojPath = args.mmproj ? resolve(args.mmproj) : undefined;
-    if (mmprojPath !== undefined) {
-        if (!existsSync(mmprojPath)) {
-            console.error(`Error: mmproj file not found: ${mmprojPath}`);
-            process.exit(1);
-        }
-        if (!mmprojPath.endsWith('.gguf')) {
-            console.error('Error: --mmproj must point to a .gguf file');
-            process.exit(1);
-        }
-    }
-    const imatrixPath = args['imatrix-path'] ? resolve(args['imatrix-path']) : undefined;
-    if (imatrixPath !== undefined) {
-        if (!existsSync(imatrixPath)) {
-            console.error(`Error: imatrix file not found: ${imatrixPath}`);
-            process.exit(1);
-        }
-        if (!imatrixPath.endsWith('.gguf')) {
-            console.error('Error: --imatrix-path must point to a .gguf file');
-            process.exit(1);
-        }
-    }
-    const startTime = Date.now();
-    // GGUF file detection
-    if (inputPath.endsWith('.gguf')) {
-        if (!existsSync(inputPath)) {
-            console.error(`Error: GGUF file not found: ${inputPath}`);
-            process.exit(1);
-        }
-        const dtype = args.dtype || 'bfloat16';
-        console.log(`Converting GGUF to SafeTensors`);
-        console.log(`Input:      ${inputPath}`);
-        console.log(`Output:     ${outputDir}`);
-        console.log(`Dtype:      ${dtype}`);
-        if (args.quantize) {
-            const qMode = quantMode || 'affine';
-            const qBits = quantBits || (qMode === 'mxfp8' ? 8 : 4);
-            const qGs = quantGroupSize || (qMode === 'mxfp8' ? 32 : 64);
-            console.log(`Quantize:   ${qBits}-bit ${qMode} (group_size=${qGs})${quantRecipe ? `, recipe=${quantRecipe}` : ''}`);
-        }
-        if (imatrixPath) {
-            console.log(`imatrix:    ${imatrixPath}`);
-        }
-        if (mmprojPath) {
-            console.log(`mmproj:     ${mmprojPath}`);
-        }
-        console.log('');
-        try {
-            const result = await convertGgufToSafetensors({
-                inputPath,
-                outputDir,
-                dtype,
-                verbose,
-                quantize: args.quantize,
-                quantBits,
-                quantGroupSize,
-                quantMode,
-                quantRecipe,
-                imatrixPath,
-                vlmKeyPrefix: !!mmprojPath,
-            });
-            const duration = ((Date.now() - startTime) / 1000).toFixed(2);
-            console.log(`\n✓ Converted ${result.numTensors} tensors (source: ${result.sourceFormat})`);
-            console.log(`✓ Total parameters: ${result.numParameters.toLocaleString()}`);
-            console.log(`✓ Output directory: ${result.outputPath}`);
-            console.log(`✓ Duration: ${duration}s`);
-            if (verbose) {
-                console.log('\nConverted tensors:');
-                for (const name of result.tensorNames) {
-                    console.log(`  - ${name}`);
-                }
-            }
-            // Convert mmproj (vision encoder) if provided
-            if (mmprojPath) {
-                console.log('\nConverting mmproj (vision encoder)...');
-                const visionResult = await convertGgufToSafetensors({
-                    inputPath: mmprojPath,
-                    outputDir,
-                    dtype: 'bfloat16',
-                    verbose,
-                    quantize: false,
-                    outputFilename: 'vision.safetensors',
-                });
-                console.log(`✓ Converted ${visionResult.numTensors} vision tensors`);
-            }
-        }
-        catch (error) {
-            console.error('\nGGUF conversion failed:', error.message);
-            if (error.stack && verbose) {
-                console.error('\nStack trace:', error.stack);
-            }
-            process.exit(1);
-        }
-        return;
-    }
-    // Auto-detect model type from config.json if not specified
-    let modelType = args['model-type'];
-    if (!modelType) {
-        try {
-            const configPath = resolve(inputPath, 'config.json');
-            const config = JSON.parse(readFileSync(configPath, 'utf-8'));
-            if (config.model_type === 'paddleocr_vl') {
-                modelType = 'paddleocr-vl';
-                console.log(`Auto-detected model type: ${modelType} (from config.json)`);
-            }
-            else if (config.model_type === 'qwen3_5_moe' || config.model_type === 'qwen3_5') {
-                modelType = config.model_type;
-                console.log(`Auto-detected model type: ${modelType} (from config.json)`);
-            }
-        }
-        catch {
-            // config.json not found or invalid
-        }
-    }
-    // Foreign weight formats (Paddle .pdparams/.pdiparams, PyTorch .pkl)
-    if (modelType === 'pp-lcnet-ori' || modelType === 'uvdoc') {
-        if (!existsSync(inputPath)) {
-            console.error(`Error: Input path not found: ${inputPath}`);
-            process.exit(1);
-        }
-        const label = modelType === 'pp-lcnet-ori'
-            ? 'PP-LCNet Orientation Classifier (Paddle -> SafeTensors)'
-            : 'UVDoc Unwarping Model (-> SafeTensors)';
-        console.log(`Converting: ${label}`);
-        console.log(`Input:  ${inputPath}`);
-        console.log(`Output: ${outputDir}\n`);
-        const result = convertForeignWeights({
-            inputPath,
-            outputDir,
-            modelType,
-            verbose,
-        });
-        const duration = ((Date.now() - startTime) / 1000).toFixed(2);
-        console.log(`\n✓ Converted ${result.numTensors} tensors`);
-        console.log(`✓ Output directory: ${result.outputPath}`);
-        console.log(`✓ Duration: ${duration}s`);
-        return;
-    }
-    // Default: SafeTensors dtype conversion
-    const dtype = args.dtype || 'bfloat16';
-    console.log(`Input:      ${inputPath}`);
-    console.log(`Output:     ${outputDir}`);
-    console.log(`Dtype:      ${dtype}`);
-    if (modelType) {
-        console.log(`Model Type: ${modelType}`);
-    }
-    if (args.quantize) {
-        const qMode = quantMode || 'affine';
-        const qBits = quantBits || (qMode === 'mxfp8' ? 8 : 4);
-        const qGs = quantGroupSize || (qMode === 'mxfp8' ? 32 : 64);
-        console.log(`Quantize:   ${qBits}-bit ${qMode} (group_size=${qGs})${quantRecipe ? `, recipe=${quantRecipe}` : ''}`);
-    }
-    if (imatrixPath) {
-        console.log(`imatrix:    ${imatrixPath}`);
-    }
-    console.log('');
-    try {
-        const result = await convertModel({
-            inputDir: inputPath,
-            outputDir,
-            dtype,
-            verbose,
-            modelType,
-            quantize: args.quantize,
-            quantBits,
-            quantGroupSize,
-            quantMode,
-            quantRecipe,
-            imatrixPath,
-        });
-        const duration = ((Date.now() - startTime) / 1000).toFixed(2);
-        console.log(`\n✓ Converted ${result.numTensors} tensors`);
-        console.log(`✓ Total parameters: ${result.numParameters.toLocaleString()}`);
-        console.log(`✓ Output directory: ${result.outputPath}`);
-        console.log(`✓ Duration: ${duration}s`);
-        if (verbose) {
-            console.log('\nConverted tensors:');
-            for (const name of result.tensorNames) {
-                console.log(`  - ${name}`);
-            }
-        }
-    }
-    catch (error) {
-        console.error('\nConversion failed:', error.message);
-        if (error.stack && verbose) {
-            console.error('\nStack trace:', error.stack);
-        }
-        process.exit(1);
-    }
-}

package/dist/commands/download-dataset.d.ts

@@ -1,2 +0,0 @@
-export declare function run(argv: string[]): Promise<void>;
-//# sourceMappingURL=download-dataset.d.ts.map

package/dist/commands/download-dataset.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"download-dataset.d.ts","sourceRoot":"","sources":["../../src/commands/download-dataset.ts"],"names":[],"mappings":"AA+DA,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,iBAmFvC"}

package/dist/commands/download-dataset.js

@@ -1,121 +0,0 @@
-import { readdir, stat, copyFile } from 'node:fs/promises';
-import { parseArgs } from 'node:util';
-import { homedir } from 'node:os';
-import { join, dirname, resolve } from 'node:path';
-import { snapshotDownload } from '@huggingface/hub';
-import { convertParquetToJsonl } from '@mlx-node/core';
-import { ensureDir } from '../utils.js';
-const DEFAULT_DATASET = 'openai/gsm8k';
-const DEFAULT_REVISION = 'main';
-const DEFAULT_CACHE_DIR = join(homedir(), '.cache', 'huggingface');
-const FILE_SPECS = [
-    { output: 'train.jsonl', parquetPrefix: 'train-' },
-    { output: 'test.jsonl', parquetPrefix: 'test-' },
-];
-function datasetSlug(name) {
-    return name.replace(/\//g, '-').toLowerCase();
-}
-function printHelp() {
-    console.log(`
-Download a dataset from HuggingFace
-
-Usage:
-  mlx download dataset [options]
-
-Options:
-  -d, --dataset <name>      HuggingFace dataset name (default: ${DEFAULT_DATASET})
-  -r, --revision <rev>      Dataset revision (default: ${DEFAULT_REVISION})
-  -o, --output <dir>        Output directory (default: data/<dataset-slug>)
-  --cache-dir <dir>         HuggingFace cache directory (default: ~/.cache/huggingface)
-  -h, --help                Show this help message
-
-Examples:
-  mlx download dataset
-  mlx download dataset --dataset openai/gsm8k
-  mlx download dataset --dataset tatsu-lab/alpaca --output data/alpaca
-`);
-}
-async function findFirstMatch(root, predicate) {
-    const entries = await readdir(root, { withFileTypes: true });
-    for (const entry of entries) {
-        const fullPath = join(root, entry.name);
-        if ((entry.isFile() || entry.isSymbolicLink()) && predicate(entry.name, fullPath)) {
-            return fullPath;
-        }
-    }
-    for (const entry of entries) {
-        if (!entry.isDirectory())
-            continue;
-        const fullPath = join(root, entry.name);
-        const found = await findFirstMatch(fullPath, predicate);
-        if (found)
-            return found;
-    }
-    return null;
-}
-export async function run(argv) {
-    const { values: args } = parseArgs({
-        args: argv,
-        options: {
-            dataset: {
-                type: 'string',
-                short: 'd',
-                default: process.env.MLX_DATASET ?? DEFAULT_DATASET,
-            },
-            revision: {
-                type: 'string',
-                short: 'r',
-                default: process.env.MLX_DATASET_REVISION ?? DEFAULT_REVISION,
-            },
-            output: {
-                type: 'string',
-                short: 'o',
-            },
-            'cache-dir': {
-                type: 'string',
-            },
-            help: {
-                type: 'boolean',
-                short: 'h',
-                default: false,
-            },
-        },
-    });
-    if (args.help) {
-        printHelp();
-        return;
-    }
-    const dataset = args.dataset;
-    const revision = args.revision;
-    const outputDir = resolve(args.output ?? process.env.MLX_DATASET_OUTPUT ?? join('data', datasetSlug(dataset)));
-    console.log(`Downloading ${dataset}@${revision} snapshot from Hugging Face…`);
-    const cacheDir = args['cache-dir'] ? resolve(args['cache-dir']) : DEFAULT_CACHE_DIR;
-    const snapshotPath = await snapshotDownload({
-        repo: { type: 'dataset', name: dataset },
-        revision,
-        cacheDir,
-    });
-    console.log(`Snapshot available at ${snapshotPath}`);
-    await ensureDir(outputDir);
-    for (const spec of FILE_SPECS) {
-        const destinationPath = join(outputDir, spec.output);
-        await ensureDir(dirname(destinationPath));
-        const original = await findFirstMatch(snapshotPath, (name) => name === spec.output);
-        if (original) {
-            await copyFile(original, destinationPath);
-            const stats = await stat(destinationPath);
-            console.log(`Copied ${spec.output} (${Math.round(stats.size / 1024)} KiB) → ${destinationPath}`);
-            continue;
-        }
-        const parquetSource = await findFirstMatch(snapshotPath, (name) => name.endsWith('.parquet') && name.startsWith(spec.parquetPrefix));
-        if (!parquetSource) {
-            throw new Error(`Could not locate ${spec.output} or matching Parquet file (prefix ${spec.parquetPrefix}) inside snapshot ${snapshotPath}`);
-        }
-        console.log(`Converting ${parquetSource} → ${destinationPath}`);
-        convertParquetToJsonl(parquetSource, destinationPath);
-        const stats = await stat(destinationPath);
-        console.log(`Saved ${spec.output} (${Math.round(stats.size / 1024)} KiB) → ${destinationPath}`);
-    }
-    console.log('Done.');
-    console.log(`Dataset files stored under ${outputDir}`);
-}

package/dist/commands/download-model.d.ts

@@ -1,2 +0,0 @@
-export declare function run(argv: string[]): Promise<void>;
-//# sourceMappingURL=download-model.d.ts.map

package/dist/commands/download-model.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"download-model.d.ts","sourceRoot":"","sources":["../../src/commands/download-model.ts"],"names":[],"mappings":"AAmLA,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,iBAmLvC"}

package/dist/commands/download-model.js

@@ -1,327 +0,0 @@
-import { readdir, copyFile } from 'node:fs/promises';
-import { parseArgs } from 'node:util';
-import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join, resolve, dirname } from 'node:path';
-import { listFiles, whoAmI, downloadFileToCacheDir } from '@huggingface/hub';
-import { AsyncEntry } from '@napi-rs/keyring';
-import { input } from '@inquirer/prompts';
-import { ensureDir, formatBytes } from '../utils.js';
-const DEFAULT_CACHE_DIR = join(homedir(), '.cache', 'huggingface');
-const DEFAULT_MODEL = 'Qwen/Qwen3-0.6B';
-const keyringEntry = new AsyncEntry('mlx-node', 'huggingface-token');
-function printHelp() {
-    console.log(`
-Download a model from HuggingFace
-
-Usage:
-  mlx download model [options]
-
-Options:
-  -m, --model <name>      HuggingFace model name (default: ${DEFAULT_MODEL})
-  -o, --output <dir>      Output directory (default: .cache/models/<model-slug>)
-  -g, --glob <pattern>    Filter files by glob pattern (can be repeated)
-  --cache-dir <dir>       HuggingFace cache directory (default: ~/.cache/huggingface)
-  -h, --help              Show this help message
-  --set-token             Set HuggingFace token
-
-Glob Filtering:
-  Use --glob to download only specific files from a repo. This is especially
-  useful for GGUF repos that contain many quantization variants. Patterns use
-  simple wildcard matching (* matches any characters).
-
-  Multiple --glob flags can be combined; a file is included if it matches ANY
-  of the patterns.
-
-Examples:
-  mlx download model
-  mlx download model --model Qwen/Qwen3-1.7B --output .cache/models/qwen3-1.7b
-
-  # Download only the BF16 GGUF variant
-  mlx download model -m unsloth/Qwen3.5-9B-GGUF -g "*BF16*"
-
-  # Download only Q4_K_M and Q8_0 variants
-  mlx download model -m unsloth/Qwen3.5-9B-GGUF -g "*Q4_K_M*" -g "*Q8_0*"
-
-  # Download all .gguf files (skip everything else)
-  mlx download model -m unsloth/Qwen3.5-9B-GGUF -g "*.gguf"
-`);
-}
-async function setToken() {
-    const token = await input({
-        message: 'Enter your HuggingFace token:',
-        required: true,
-        theme: {
-            validationFailureMode: 'clear',
-        },
-        validate: async (value) => {
-            if (!value) {
-                return 'Token is required';
-            }
-            if (!value.startsWith('hf_')) {
-                return 'HuggingFace token must start with "hf_"';
-            }
-            try {
-                const { auth } = await whoAmI({ accessToken: value });
-                if (!auth) {
-                    return 'Invalid token';
-                }
-                return true;
-            }
-            catch {
-                return 'Invalid token';
-            }
-        },
-    });
-    if (token) {
-        await keyringEntry.setPassword(token);
-    }
-}
-const CORE_FILES = [
-    'config.json',
-    'tokenizer.json',
-    'tokenizer_config.json',
-    'special_tokens_map.json',
-    'vocab.json',
-    'merges.txt',
-];
-/** Convert a simple glob pattern (with * wildcards) to a RegExp */
-function globToRegex(pattern) {
-    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
-    return new RegExp(`^${escaped}$`, 'i');
-}
-/** Check if a filename matches any of the glob patterns */
-function matchesAnyGlob(filename, patterns) {
-    return patterns.some((re) => re.test(filename));
-}
-async function getModelFiles(modelName, accessToken, globPatterns) {
-    let totalSize = 0;
-    const filesToDownload = [];
-    const allFiles = [];
-    // Compile glob patterns if provided
-    const globs = globPatterns?.map(globToRegex);
-    for await (const file of listFiles({ repo: { type: 'model', name: modelName }, accessToken })) {
-        allFiles.push(file);
-        if (globs) {
-            // When glob patterns are active, include files that match the pattern
-            // OR are essential metadata files (config, tokenizer)
-            const basename = file.path.split('/').pop() || file.path;
-            if (matchesAnyGlob(basename, globs) || matchesAnyGlob(file.path, globs)) {
-                filesToDownload.push(file);
-                if (file.size)
-                    totalSize += file.size;
-            }
-            else if (CORE_FILES.includes(basename)) {
-                // Always include core config/tokenizer files
-                filesToDownload.push(file);
-                if (file.size)
-                    totalSize += file.size;
-            }
-        }
-        else {
-            // Default behavior: download model files
-            if (CORE_FILES.includes(file.path) ||
-                file.path.endsWith('.safetensors') ||
-                file.path.endsWith('.json') ||
-                file.path.endsWith('.pdiparams') ||
-                file.path.endsWith('.yml')) {
-                filesToDownload.push(file);
-                if (file.size) {
-                    totalSize += file.size;
-                }
-            }
-        }
-    }
-    return { totalSize, filesToDownload, allFiles };
-}
-async function verifyDownload(outputDir, weightFiles) {
-    console.log('\nVerifying download...');
-    let allPresent = true;
-    const configPath = join(outputDir, 'config.json');
-    if (!existsSync(configPath)) {
-        console.error('  ✗ Missing required file: config.json');
-        allPresent = false;
-    }
-    else {
-        console.log('  ✓ config.json');
-    }
-    if (weightFiles.length === 0) {
-        console.error('  ✗ No weight files found');
-        allPresent = false;
-    }
-    for (const file of weightFiles) {
-        const path = join(outputDir, file);
-        if (!existsSync(path)) {
-            console.error(`  ✗ Missing weight file: ${file}`);
-            allPresent = false;
-        }
-        else {
-            console.log(`  ✓ ${file}`);
-        }
-    }
-    return allPresent;
-}
-export async function run(argv) {
-    const { values: args } = parseArgs({
-        args: argv,
-        options: {
-            model: {
-                type: 'string',
-                short: 'm',
-                default: DEFAULT_MODEL,
-            },
-            output: {
-                type: 'string',
-                short: 'o',
-            },
-            glob: {
-                type: 'string',
-                short: 'g',
-                multiple: true,
-            },
-            help: {
-                type: 'boolean',
-                short: 'h',
-                default: false,
-            },
-            'set-token': {
-                type: 'boolean',
-                default: false,
-            },
-            'cache-dir': {
-                type: 'string',
-            },
-        },
-    });
-    if (args.help) {
-        printHelp();
-        return;
-    }
-    if (args['set-token']) {
-        await setToken();
-        return;
-    }
-    const modelName = args.model;
-    const globPatterns = args.glob;
-    const modelSlug = modelName.split('/').pop().toLowerCase();
-    const outputDir = resolve(args.output ?? join('.cache', 'models', modelSlug));
-    const HUGGINGFACE_TOKEN = (await keyringEntry.getPassword()) ?? undefined;
-    if (!HUGGINGFACE_TOKEN) {
-        console.warn('No HuggingFace token found, the model will download with anonymous access');
-    }
-    const title = `${modelName} Model Download from HuggingFace`;
-    const boxWidth = Math.max(title.length + 6, 58);
-    const padding = Math.floor((boxWidth - title.length - 2) / 2);
-    const rightPadding = boxWidth - title.length - padding;
-    console.log('╔' + '═'.repeat(boxWidth) + '╗');
-    console.log('║' + ' '.repeat(padding) + title + ' '.repeat(rightPadding) + '║');
-    console.log('╚' + '═'.repeat(boxWidth) + '╝\n');
-    console.log(`Model: ${modelName}`);
-    if (globPatterns?.length) {
-        console.log(`Filter: ${globPatterns.join(', ')}`);
-    }
-    console.log(`Output: ${outputDir}\n`);
-    // Check if already downloaded
-    if (existsSync(outputDir)) {
-        const files = await readdir(outputDir);
-        const hasConfig = files.includes('config.json');
-        const hasSingleModel = files.includes('model.safetensors');
-        const hasShardedModel = files.includes('model.safetensors.index.json');
-        const hasPaddleModel = files.includes('inference.pdiparams');
-        const hasGguf = files.some((f) => f.endsWith('.gguf'));
-        if (hasConfig && (hasSingleModel || hasShardedModel || hasPaddleModel)) {
-            console.log('Model already downloaded!\n');
-            console.log('To re-download, delete the output directory first:');
-            console.log(`   rm -rf ${outputDir}\n`);
-            return;
-        }
-        if (hasGguf && !globPatterns?.length) {
-            console.log('GGUF file(s) already downloaded!\n');
-            console.log('To re-download, delete the output directory first:');
-            console.log(`   rm -rf ${outputDir}\n`);
-            return;
-        }
-        // For glob downloads, check if all glob-matched files are present
-        if (hasGguf && globPatterns?.length) {
-            const globs = globPatterns.map(globToRegex);
-            const matchedExisting = files.filter((f) => matchesAnyGlob(f, globs) || CORE_FILES.includes(f));
-            if (matchedExisting.length > 1) {
-                console.log('Matched files already downloaded!\n');
-                console.log('To re-download, delete the output directory first:');
-                console.log(`   rm -rf ${outputDir}\n`);
-                return;
-            }
-        }
-    }
-    await ensureDir(outputDir);
-    console.log('Fetching file list from HuggingFace...\n');
-    const { totalSize, filesToDownload, allFiles } = await getModelFiles(modelName, HUGGINGFACE_TOKEN, globPatterns);
-    if (filesToDownload.length === 0) {
-        console.error('No files matched the given criteria.\n');
-        if (globPatterns?.length) {
-            const ggufFiles = allFiles.filter((f) => f.path.endsWith('.gguf'));
-            if (ggufFiles.length > 0) {
-                console.log('Available GGUF files in this repo:');
-                for (const f of ggufFiles) {
-                    console.log(`  ${f.path} (${formatBytes(f.size)})`);
-                }
-                console.log(`\nTry: mlx download model -m ${modelName} -g "<pattern>"`);
-            }
-        }
-        process.exit(1);
-    }
-    // Show what will be downloaded
-    if (globPatterns?.length) {
-        console.log(`Matched ${filesToDownload.length} file(s):`);
-        for (const f of filesToDownload) {
-            console.log(`  ${f.path} (${formatBytes(f.size)})`);
-        }
-        console.log('');
-    }
-    const sizeStr = formatBytes(totalSize);
-    console.log(`Downloading ${filesToDownload.length} file(s) (~${sizeStr})...\n`);
-    const cacheDir = args['cache-dir'] ? resolve(args['cache-dir']) : DEFAULT_CACHE_DIR;
-    const weightFiles = [];
-    const total = filesToDownload.length;
-    for (let i = 0; i < total; i++) {
-        const file = filesToDownload[i];
-        const fileSizeStr = file.size ? formatBytes(file.size) : '';
-        console.log(`  [${i + 1}/${total}] ${file.path}${fileSizeStr ? ` (${fileSizeStr})` : ''}...`);
-        const snapshotPath = await downloadFileToCacheDir({
-            repo: { type: 'model', name: modelName },
-            path: file.path,
-            cacheDir,
-            accessToken: HUGGINGFACE_TOKEN,
-        });
-        const destPath = join(outputDir, file.path);
-        await ensureDir(dirname(destPath));
-        await copyFile(snapshotPath, destPath);
-        if (file.path.endsWith('.safetensors') || file.path.endsWith('.pdiparams') || file.path.endsWith('.gguf')) {
-            weightFiles.push(file.path);
-        }
-    }
-    // For GGUF downloads, skip strict verification (no config.json required in GGUF repos)
-    const hasGgufFiles = weightFiles.some((f) => f.endsWith('.gguf'));
-    if (hasGgufFiles) {
-        console.log(`\nDownload complete! ${weightFiles.length} file(s) saved to ${outputDir}\n`);
-        console.log('To convert GGUF to MLX SafeTensors format:');
-        for (const wf of weightFiles) {
-            const ggufPath = join(outputDir, wf);
-            console.log(`  mlx convert -i ${ggufPath} -o ${outputDir}-mlx`);
-        }
-        console.log('');
-    }
-    else {
-        console.log(`Format: Base model (needs MLX conversion)`);
-        console.log('Note: After download, convert to MLX format:');
-        console.log(`    mlx convert --input ${outputDir} --output ${outputDir}-mlx-bf16\n`);
-        const success = await verifyDownload(outputDir, weightFiles);
-        if (success) {
-            console.log('\nModel downloaded successfully!\n');
-        }
-        else {
-            console.error('\nDownload incomplete. Please try again.\n');
-            process.exit(1);
-        }
-    }
-}

package/dist/utils.d.ts

@@ -1,3 +0,0 @@
-export declare function ensureDir(path: string): Promise<void>;
-export declare function formatBytes(bytes: number): string;
-//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAGA,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAI3D;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASjD"}

package/dist/utils.js

@@ -1,17 +0,0 @@
-import { mkdir } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-export async function ensureDir(path) {
-    if (!existsSync(path)) {
-        await mkdir(path, { recursive: true });
-    }
-}
-export function formatBytes(bytes) {
-    const units = ['B', 'KB', 'MB', 'GB'];
-    let size = bytes;
-    let unitIndex = 0;
-    while (size >= 1024 && unitIndex < units.length - 1) {
-        size /= 1024;
-        unitIndex++;
-    }
-    return `${size.toFixed(2)} ${units[unitIndex]}`;
-}