@mlx-node/cli 0.0.2 → 0.0.4

package/dist/cli.d.ts

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

package/dist/cli.d.ts.map

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

package/dist/cli.js

@@ -0,0 +1,80 @@
+#!/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

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

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

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

package/dist/commands/convert.js

@@ -0,0 +1,328 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+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
+                        "unsloth" defaults to 3-bit base (gate/up=3b, down=4b,
+                        embed=5b, lm_head=6b, attn/SSM=bf16)
+  --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);
+        }
+        // Unsloth recipe defaults to 3-bit base (MLP gate/up at 3-bit, down at 4-bit,
+        // embed_tokens at 5-bit, lm_head at 6-bit, attention/SSM kept bf16).
+        // Based on Unsloth's per-tensor KLD analysis showing ffn_up/gate are
+        // "generally ok to quantize to 3-bit" and IQ3_XXS is the "best compromise".
+        if (quantRecipe === 'unsloth' && !args['q-bits']) {
+            console.log('Note: unsloth recipe defaults to 3-bit base (override with --q-bits)');
+        }
+    }
+    // Apply recipe-specific defaults for bits when not explicitly set.
+    // Unsloth recipe: 3-bit base → MLP gate/up=3b, down=4b, embed=5b, lm_head=6b
+    const effectiveQuantBits = quantBits ?? (quantRecipe === 'unsloth' ? 3 : undefined);
+    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 = effectiveQuantBits || (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: effectiveQuantBits,
+                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 = effectiveQuantBits || (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: effectiveQuantBits,
+            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

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

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,121 @@
+import { readdir, stat, copyFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+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

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

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

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

package/dist/commands/download-model.js

@@ -0,0 +1,327 @@
+import { existsSync } from 'node:fs';
+import { readdir, copyFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { parseArgs } from 'node:util';
+import { listFiles, whoAmI, downloadFileToCacheDir } from '@huggingface/hub';
+import { input } from '@inquirer/prompts';
+import { AsyncEntry } from '@napi-rs/keyring';
+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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,17 @@
+import { existsSync } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+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]}`;
+}

package/package.json

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