CLI Reference

CLI Reference

BitForge exposes a Click-based CLI installed as the bitforge command.

bitforge --help

Global

Usage: bitforge [OPTIONS] COMMAND [ARGS]...

  BitForge CLI: Forge smaller, run faster, measure honestly.

Options:
  --help  Show this message and exit.

Commands:
  evaluate  Evaluate a model's performance (perplexity, throughput, memory).
  quantize  Quantize an LLM using GPTQ, AWQ, or basic PTQ/bitsandbytes.

bitforge quantize

Quantize a Hugging Face model and save artifacts to disk.

bitforge quantize --help

Usage: bitforge quantize [OPTIONS]

  Quantize an LLM using GPTQ, AWQ, or basic PTQ/bitsandbytes.

Options:
  --model-id TEXT      Hugging Face Model ID (e.g. meta-llama/Llama-2-7b-hf)  [required]
  --bits [2|4|8]       Target quantization bit width  [default: 4]
  --method [ptq|gptq|awq|bitsandbytes]
                       Quantization method  [default: gptq]
  --output-path TEXT   Path to save the quantized model  [required]
  --help               Show this message and exit.

Examples

GPTQ 4-bit (default):

bitforge quantize \
  --model-id mistralai/Mistral-7B-v0.1 \
  --bits 4 \
  --method gptq \
  --output-path ./out/mistral-7b-gptq

AWQ 4-bit:

bitforge quantize \
  --model-id mistralai/Mistral-7B-v0.1 \
  --method awq \
  --output-path ./out/mistral-7b-awq

bitsandbytes runtime quant (no separate artifact):

bitforge quantize \
  --model-id meta-llama/Llama-2-7b-hf \
  --method bitsandbytes \
  --bits 4 \
  --output-path ./out/llama-2-7b-bnb

Method selection

Method	Best for	Export format
gptq	GPU PTQ, Hugging Face ecosystem	Safetensors + quant config
awq	Fast calibration, 4-bit LLMs	AWQ-compatible checkpoint
ptq	Baseline / teaching	BitForge native scales
bitsandbytes	QLoRA training, in-memory 4-bit	HF + bnb config

See Runtime Integration for which format your inference stack expects.

bitforge evaluate

Measure model quality and performance on a calibration/eval dataset.

bitforge evaluate --help

Usage: bitforge evaluate [OPTIONS]

  Evaluate a model's performance (perplexity, throughput, memory).

Options:
  --model-id TEXT   Local path or Hugging Face Model ID  [required]
  --dataset TEXT    Dataset for perplexity (wikitext2, c4, etc.)  [default: wikitext2]
  --device TEXT     Execution device (cuda, cpu, mps)  [default: cuda]
  --help            Show this message and exit.

Examples

bitforge evaluate \
  --model-id ./out/mistral-7b-gptq \
  --dataset wikitext2 \
  --device cuda

bitforge evaluate \
  --model-id meta-llama/Llama-2-7b-hf \
  --dataset c4 \
  --device mps

Reported metrics

Metric	Description
perplexity	Cross-entropy perplexity on eval set
avg_latency_ms	Mean token generation latency
peak_vram_gb	Peak GPU memory during eval

Programmatic API

Prefer Python for custom pipelines:

from bitforge.core.quantizers import WeightQuantizer, QuantizationConfig
from bitforge.evaluation.metrics import perplexity, latency, memory_footprint
from bitforge.evaluation.benchmarks import QuantizationBenchmarkSuite

See Architecture for module-level detail.

Logging

The CLI uses Python logging at INFO level:

2026-05-24 12:00:00 - INFO - Starting quantization for model '...' ...

Set BITFORGE_LOG_LEVEL=DEBUG (future) or configure logging in scripts for verbose output.