hfo CLI reference — every flag with examples

Commands at a glance

Command	Description
`hfo`	Open the fullscreen TUI (Dashboard tab)
`hfo <repo>`	Open the TUI pre-filled on the Install tab
`hfo --view`	Print hardware profile, capacity score, tier, picks, HF search URLs
`hfo --list`	List installed models + orphan GGUFs on disk
`hfo --tune`	Persist the ~90% capacity Ollama env profile, restart the daemon
`hfo --backup <tag>`	Create a `.zip` backup of the model's folder
`hfo --restore <zip>`	Extract a backup, regenerate Modelfile if needed, re-register with Ollama
`hfo --delete <tag>`	Remove the tag from Ollama (shallow)
`hfo --delete <tag> --deep`	Remove the tag AND delete its on-disk folder
`hfo --launch <integration>`	Hand off to a coding agent with the chosen model
`hfo --launch-targets`	Print every launch target, its runner, and whether it is usable here
`hfo --bench <tag>`	Run the standard 4-prompt bench and print tok/s + TTFT per prompt
`hfo --bench <tag> --out <file>`	Also write an `hfo-bench-v1` JSON file for the community leaderboard
`hfo --tab <name>`	Open the TUI on `dashboard` · `models` · `install` · `tune` · `help` · `settings`
`hfo --help` · `-h`	Print the full flag reference
`hfo --version`	Print `hfo vX.Y.Z · MIT · <author>`

Flags

Flag	Purpose
`--dir` · `-d`	Base directory for the install file browser. Default: `settings.modelDir` → `process.cwd()`
`--token` · `-t`	Hugging Face token for gated/private repos. Falls back to `$HF_TOKEN`
`--code` · `-c`	Mark the install as code-specialized (SYSTEM prompt tweak)
`--ctx`	Force context size. Default: auto — 8192 if fits in VRAM, else 4096
`--model`	Model tag to pass to `--launch`. Ignored by agents that only serve their vendor's hosted models (`kiro`, `antigravity`)
`--deep`	Deep-delete (removes the tracked directory too) alongside `--delete`
`--out`	Destination file for the `--bench` submission JSON. Without it the bench only prints
`--no-fullscreen`	Disable the alt-screen buffer (helpful on legacy terminals)

Examples by task

Install a specific repo, no TUI

# Quick-confirm flow accepts on Enter. In CI, drop `--no-fullscreen` and pipe yes. $ hfo bartowski/Qwen2.5-Coder-7B-Instruct-GGUF --code # Pre-select quant via --dir for a specific install location $ hfo bartowski/Llama-3.2-3B-Instruct-GGUF --dir ./models

Back up and restore models

# Creates a level-9 zip + sidecar metadata.json under settings/backups/<date>/ $ hfo --backup qwen2-5-coder-7b:q4-k-m # Reads the zip, regenerates Modelfile if missing, re-registers with Ollama $ hfo --restore ~/.config/hfo/backups/2026-04-23_11-48-25/qwen2-5-coder-7b_q4-k-m.zip

Tune Ollama env to ~90% of capacity

# Persists OLLAMA_FLASH_ATTENTION, OLLAMA_KV_CACHE_TYPE, OLLAMA_KEEP_ALIVE, # OLLAMA_NUM_PARALLEL, OLLAMA_MAX_LOADED_MODELS, OLLAMA_MAX_QUEUE # via setx (Windows) / launchctl + ~/.zprofile (macOS) / ~/.profile + systemd (Linux) $ hfo --tune

Launch a coding agent with a local model

$ hfo --launch claude --model llama3.1:8b $ hfo --launch codex --model qwen2.5-coder:7b-q6-k $ hfo --launch copilot --model deepseek-coder:6.7b-instruct $ hfo --launch kiro $ hfo --launch antigravity $ hfo --launch-targets

Launch targets served by Ollama: claude, cline, codex, copilot, droid, hermes, kimi, opencode, openclaw, pi, vscode. Unsupported targets on your installed Ollama version are probed at runtime against ollama launch --help.

Custom targets. A launch-plugins.json in hfo's config dir (%APPDATA%\hfo\ on Windows, ~/Library/Application Support/hfo/ on macOS, $XDG_CONFIG_HOME/hfo/ on Linux) registers your own agents. Each entry needs at least id, name and bin; they are always spawned directly. An id may not shadow a built-in id or alias, and a malformed entry is skipped with a reason rather than breaking the picker — hfo --launch-targets lists both the resolved targets and any problems, and exits non-zero when there are any.

Launched directly by hfo, because Ollama has no integration for them: kiro (alias kiro-cli) and antigravity (alias agy). These are marked available only when their binary resolves on PATH or at the vendor's default install location. Both run exclusively on their vendor's hosted models and expose no custom-endpoint setting, so --model <ollama-tag> cannot bind — hfo warns and launches them unbound. Run hfo --launch-targets to print every target with its runner and local status.

Benchmark a model

# Warmup + code + reasoning + translation prompts at temperature 0.2 $ hfo --bench qwen2.5-coder:7b-q5_k_m # Same run, saved in the hfo-bench-v1 schema for a leaderboard PR $ hfo --bench qwen2.5-coder:7b-q5_k_m --out bench.json

The model has to be registered with Ollama first — the bench drives the local daemon, nothing leaves the machine. See Benchmarks for the schema, the prompt set, and how to submit a run.

List and clean up

$ hfo --list # Shallow: removes the tag from Ollama but keeps files on disk for re-registration $ hfo --delete old-tag:q4 # Deep: also wipes the tracked directory $ hfo --delete old-tag:q4 --deep

Exit codes

0 — success
1 — generic runtime error (message on stderr)
2 — invalid flag / unknown launch target
127 — a directly-launched agent's binary (kiro-cli, agy) is not installed
130 — interrupted by Ctrl+C (SIGINT)
143 — terminated by SIGTERM