CLI Reference

CLI Reference

hk <command> [arguments]
hk help

hk is one executable. It needs no Python, no GPU toolkit and no configuration. Commands that take a model accept a .hk file or a Hub reference (owner/name[:quant]); a reference is pulled first if it is not cached yet.

Running models

hk run <model> [prompt | -p TEXT] [options]

Generates text. Text goes to standard output, statistics to standard error, so the output can be piped.

Option	Meaning	Default
-p, --prompt TEXT	text to continue (a bare argument works too; quote it)	none
--chat	wrap the prompt as one user message using the model's chat template	off
-n, --max-tokens N	most tokens to generate	128
--temp T	temperature; 0 takes the most likely token	0.8
--top-k N	keep the N most likely tokens, 0 for no limit	40
--top-p P	nucleus sampling, 1 disables	0.95
--min-p P	drop tokens below P times the best one	0.05
--repeat-penalty X	penalty for recent tokens, 1 disables	1.0
--seed N	random seed, 0 uses the clock	0
--threads N	compute threads	physical cores
-ngl, --gpu-layers N	run on a GPU (Vulkan) when N > 0; also HK_GPU=1	CPU

Every flag is checked before the model is opened, and an unknown or malformed one is an error, never a silent default. With --temp 0 the output is deterministic.

hk chat <model> [options]

An interactive session with the model's chat template and history kept across turns. Takes the sampling options of run (not -p or --chat) and -n (default 1024). An empty line ends the session.

hk serve <model> [options]

An OpenAI compatible HTTP server. See Inference and Serving.

Getting models

Command
hk pull <owner/name>[:quant] [--force] [--revision REF]	download and convert, see Downloading Models
hk search <query> [--limit N] [--all]	search the Hub
hk list	show cached models
hk rm <owner/name>	delete a cached model
hk convert-gguf <in.gguf> <out.hk>	convert a GGUF file; block formats are carried over byte for byte
hk convert-safetensors <in.safetensors> <out.hk> [f32|q4_0|q8_0]	convert one safetensors file, optionally quantizing
hk export -f gguf <in.hk> <out.gguf>	write a GGUF v3 file
hk export -f safetensors <in.hk> <out.safetensors>	write safetensors; float tensors keep their type, quantized ones are decoded and stored as F16

Tensor names are kept as they are in the container, so a model converted from GGUF exports with GGUF names.

Looking at a container

Command
hk inspect <file.hk>	header, metadata and the tensor table
hk dump <file.hk>	the header field by field, with offsets
hk verify <file.hk>	check the magic, version and the alignment of the payload
hk hash <file.hk>	SHA-256 of the container and of every tensor
hk eval <file.hk>	parameter count, value range, NaN and Inf count
hk tokenize <file.hk> "text"	token ids using the vocabulary stored in the file
hk detokenize <file.hk> <id> ...	text from token ids
hk metadata list <file.hk> / get / set <key> <value>	read or change metadata in place; the weights are not rewritten
hk hardware-profile	what the processor offers, which kernels are in use, whether a GPU is usable
hk benchmark <file.hk>	time to open the file, resolve tensors, touch every page, decode a tensor

Editing containers (research features)

Command
hk expand <in> <out> [--vocab N] [--width R]	grow the vocabulary and the MLP width of a float model; see Dynamic Architecture Growth
hk prune <in> <out> [ratio]	magnitude pruning
hk retile <in> <out> [tile_16x16|row_major]	change the layout of 2-D tensors
hk appendix <file.hk>	list the version history stored in the file
hk rollback <file.hk> [generation]	cut the version history back; this truncates the file
hk convert-endian <in> <out>	byte swap a container
hk gui [file.hk]	the Tk model editor (needs Python and Tk)

hk expand refuses quantized models, and says so when no tensor name matched (it looks for Hugging Face style names).

Environment

Variable	Effect
HK_HOME	model cache directory
HF_TOKEN, HF_ENDPOINT, HK_HTTP_BACKOFF_MS	downloads, see Downloading Models
HK_GPU=1	use the GPU when possible, without -ngl
HK_KERNELS=<level>	force an instruction set level (for example avx2 or generic); useful for testing and measuring
HK_THREADS=N	thread count for the developer tools
HK_API_KEY	API key for hk serve

Exit status

Zero on success, non-zero on any error. Messages for the user go to standard error.