> For the complete documentation index, see [llms.txt](https://docs.mozilla.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mozilla.ai/llamafile/reference/cli_arguments.md).

# CLI Arguments and Flags

llamafile accepts two layers of command-line options:

1. Wrapper flags added by llamafile itself, such as `--server`, `--chat`, `--cli`, and `--gpu`.
2. The bundled `llama.cpp` flags that are passed through to chat, CLI, and server mode.

The examples on this page use `llamafile` as the executable name. This is the name of the standalone runtime distributed in the releases. A pre-built, model-bundled llamafile normally has a model-specific filename instead; use that filename in the same commands. For example, these commands display the same kind of help:

```sh
llamafile --help
./Qwen3.5-0.8B-Q8_0.llamafile --help
```

The `./` prefix runs a downloaded file from the current directory on macOS, Linux, and BSD. On Windows, use the filename after adding the `.exe` suffix.

## Discovering Available Options

Command-line options are scoped by execution mode rather than collected in a single mode-independent list. The complete user-facing interface is the union of the general and mode-specific help views:

```sh
llamafile --help
llamafile --server --help
llamafile --chat --help
llamafile --cli --help
```

The top-level command is the reference for general llamafile wrapper flags. Each mode-specific command selects the matching `llama.cpp` parser and adds that mode's wrapper flags:

| Command                     | Options shown                                                      |
| --------------------------- | ------------------------------------------------------------------ |
| `llamafile --help`          | Default combined-mode options and general llamafile wrapper flags. |
| `llamafile --server --help` | HTTP server, API, Web UI, slot, and server sandbox options.        |
| `llamafile --chat --help`   | Interactive chat, conversation, and multimodal options.            |
| `llamafile --cli --help`    | Single-prompt, output, sampling, and multimodal options.           |

For fuller descriptions and upstream examples, see the llama.cpp [CLI argument reference](https://github.com/ggml-org/llama.cpp/blob/master/tools/cli/README.md#usage) and [server argument reference](https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md#usage). Those pages track the latest llama.cpp development version, so an option may differ from the version bundled in a particular llamafile. The help output from that llamafile is authoritative for its accepted options.

An option listed for one mode is not necessarily available in another. For example, `--host`, `--port`, and `--slot-save-path` configure the server, while `--nothink` is a CLI-mode option.

Since v0.10.4, each `llama.cpp` option list is generated by the same parser that accepts arguments for that mode. This keeps accepted options and their help entries in sync. Llamafile-specific wrapper options appear in the top-level help or in the relevant mode introduction.

Releases before v0.10.4 printed abbreviated hand-written help for the default, chat, and CLI modes. In those versions, `--server --help` provides the broadest option list, although it also contains server-only options.

### Additional Accepted Parameter Spellings

The `--gpu MODE` help uses the canonical backend names but does not spell out all accepted compatibility aliases. Values are case-insensitive:

| Backend             | Accepted `MODE` values          |
| ------------------- | ------------------------------- |
| Automatic selection | `auto`                          |
| NVIDIA CUDA         | `nvidia`, `cublas`              |
| AMD ROCm/HIP        | `amd`, `rocm`, `rocblas`, `hip` |
| Apple Metal         | `apple`, `metal`                |
| Vulkan              | `vulkan`, `vk`                  |
| CPU only            | `disable`, `disabled`           |

Prefer the first value in each row in scripts. The aliases are retained for compatibility.

## Commonly Used Flags

| Flag                                   | What it does                                                           |
| -------------------------------------- | ---------------------------------------------------------------------- |
| `-t, --threads N`                      | Number of CPU threads to use during generation.                        |
| `-tb, --threads-batch N`               | Number of CPU threads to use during prompt and batch processing.       |
| `-c, --ctx-size N`                     | Context window size. `0` means to use the model default.               |
| `-b, --batch-size N`                   | Logical maximum batch size.                                            |
| `-ub, --ubatch-size N`                 | Physical maximum batch size.                                           |
| `--mlock`                              | Keep the model in RAM instead of letting the OS swap or compress it.   |
| `--repeat-penalty N`                   | Penalize repeating tokens during sampling. `1.0` disables the penalty. |
| `-ngl, --gpu-layers, --n-gpu-layers N` | Number of layers to offload to GPU.                                    |
| `--host HOST`                          | Server bind address.                                                   |
| `--port PORT`                          | Server listen port.                                                    |

## Wrapper and Mode Flags

* Mode selection: `--server`, `--chat`, `--cli`
* General wrapper flags: `--gpu MODE`, `--unsecure`, `--version`, `--help`
* Chat-only wrapper flags: `--nologo`, `--ascii`
* CLI-only wrapper flags: `--nothink`
* Server-only wrapper flag: `--confine-reads`

`--unsecure` disables the pledge/SECCOMP sandbox in modes where that sandbox is active. `--confine-reads` adds filesystem read confinement and only applies to `--server` mode.

Model, prompt, GPU-layer, and logging options such as `-m`, `-p`, `-ngl`, and `--verbose` come from the bundled `llama.cpp` parser rather than the llamafile wrapper.

## Shared Flags Accepted by Chat, CLI, and Server

### General, CPU, Context, and Batching

* General help and shell integration: `-h`, `--help`, `--usage`, `--version`, `-cl`, `--cache-list`, `--completion-bash`, `--verbose-prompt`
* CPU scheduling and affinity: `-t`, `--threads`, `-tb`, `--threads-batch`, `-C`, `--cpu-mask`, `-Cr`, `--cpu-range`, `--cpu-strict`, `--prio`, `--poll`, `-Cb`, `--cpu-mask-batch`, `-Crb`, `--cpu-range-batch`, `--cpu-strict-batch`, `--prio-batch`, `--poll-batch`
* Context and batching: `-c`, `--ctx-size`, `-n`, `--predict`, `--n-predict`, `-b`, `--batch-size`, `-ub`, `--ubatch-size`, `--keep`, `--swa-full`, `-fa`, `--flash-attn`
* Prompt input: `-p`, `--prompt`, `-f`, `--file`, `-bf`, `--binary-file`, `-e`, `--escape`, `--no-escape`
* RoPE and YaRN: `--rope-scaling`, `--rope-scale`, `--rope-freq-base`, `--rope-freq-scale`, `--yarn-orig-ctx`, `--yarn-ext-factor`, `--yarn-attn-factor`, `--yarn-beta-slow`, `--yarn-beta-fast`

### Memory, KV Cache, and Offload

* KV cache and host memory: `-kvo`, `--kv-offload`, `-nkvo`, `--no-kv-offload`, `--repack`, `-nr`, `--no-repack`, `--no-host`
* Cache storage and defragmentation: `-ctk`, `--cache-type-k`, `-ctv`, `--cache-type-v`, `-dt`, `--defrag-thold`
* Memory mapping and residency: `--mlock`, `--mmap`, `--no-mmap`, `--numa`, `--check-tensors`, `--op-offload`, `--no-op-offload`
* Draft-model cache types: `-ctkd`, `--cache-type-k-draft`, `-ctvd`, `--cache-type-v-draft`

### Devices, GPU, Tensors, and Adapters

* Devices and tensor placement: `-dev`, `--device`, `--list-devices`, `-ot`, `--override-tensor`
* CPU MoE controls: `-cmoe`, `--cpu-moe`, `-ncmoe`, `--n-cpu-moe`
* GPU offload controls: `-ngl`, `--gpu-layers`, `--n-gpu-layers`, `-sm`, `--split-mode`, `-ts`, `--tensor-split`, `-mg`, `--main-gpu`
* Automatic fitting: `-fit`, `--fit`, `-fitt`, `--fit-target`, `-fitc`, `--fit-ctx`
* Adapters and metadata overrides: `--lora`, `--lora-scaled`, `--control-vector`, `--control-vector-scaled`, `--control-vector-layer-range`, `--override-kv`

### Model Selection, Downloads, and Logging

* Model path and downloads: `-m`, `--model`, `-mu`, `--model-url`, `-dr`, `--docker-repo`
* Hugging Face and related model selectors: `-hf`, `-hfr`, `--hf-repo`, `-hfd`, `-hfrd`, `--hf-repo-draft`, `-hff`, `--hf-file`, `-hfv`, `-hfrv`, `--hf-repo-v`, `-hffv`, `--hf-file-v`, `-hft`, `--hf-token`
* Logging and diagnostics: `--log-disable`, `--log-file`, `--log-colors`, `-v`, `--verbose`, `--log-verbose`, `--offline`, `-lv`, `--verbosity`, `--log-verbosity`, `--log-prefix`, `--log-timestamps`, `--perf`, `--no-perf`

## Sampling Flags

* Sampling order and randomness: `--samplers`, `-s`, `--seed`, `--sampler-seq`, `--sampling-seq`, `--ignore-eos`
* Core sampling controls: `--temp`, `--top-k`, `--top-p`, `--min-p`, `--top-nsigma`, `--xtc-probability`, `--xtc-threshold`, `--typical`
* Repetition controls: `--repeat-last-n`, `--repeat-penalty`, `--presence-penalty`, `--frequency-penalty`
* DRY and dynamic temperature: `--dry-multiplier`, `--dry-base`, `--dry-allowed-length`, `--dry-penalty-last-n`, `--dry-sequence-breaker`, `--dynatemp-range`, `--dynatemp-exp`
* Mirostat and constrained output: `--mirostat`, `--mirostat-lr`, `--mirostat-ent`, `-l`, `--logit-bias`, `--grammar`, `--grammar-file`, `-j`, `--json-schema`, `-jf`, `--json-schema-file`

## CLI and Chat-Specific Flags

* Output and interaction: `--display-prompt`, `--no-display-prompt`, `-co`, `--color`, `--show-timings`, `--no-show-timings`, `-cnv`, `--conversation`, `-no-cnv`, `--no-conversation`, `-st`, `--single-turn`, `-mli`, `--multiline-input`, `--simple-io`
* System prompt and stopping: `-sys`, `--system-prompt`, `-sysf`, `--system-prompt-file`, `-r`, `--reverse-prompt`, `-sp`, `--special`
* Context and cache management: `--ctx-checkpoints`, `--swa-checkpoints`, `-cram`, `--cache-ram`, `--context-shift`, `--no-context-shift`, `--warmup`, `--no-warmup`
* Parallel decode and multimodal input: `-np`, `--parallel`, `-mm`, `--mmproj`, `-mmu`, `--mmproj-url`, `--mmproj-auto`, `--no-mmproj`, `--no-mmproj-auto`, `--mmproj-offload`, `--no-mmproj-offload`, `--image`, `--audio`, `--image-min-tokens`, `--image-max-tokens`
* Draft and speculative decoding: `-otd`, `--override-tensor-draft`, `-cmoed`, `--cpu-moe-draft`, `-ncmoed`, `--n-cpu-moe-draft`, `--draft`, `--draft-n`, `--draft-max`, `--draft-min`, `--draft-n-min`, `--draft-p-min`, `-cd`, `--ctx-size-draft`, `-devd`, `--device-draft`, `-ngld`, `--gpu-layers-draft`, `--n-gpu-layers-draft`, `-md`, `--model-draft`, `--spec-replace`
* Chat templates and reasoning controls: `--chat-template-kwargs`, `--jinja`, `--no-jinja`, `--reasoning-format`, `--reasoning-budget`, `--chat-template`, `--chat-template-file`
* Built-in defaults: `--gpt-oss-20b-default`, `--gpt-oss-120b-default`, `--vision-gemma-4b-default`, `--vision-gemma-12b-default`

`-np, --parallel` in CLI and chat mode controls the number of parallel sequences to decode.

## Server-Only Flags

* Server runtime and batching: `-kvu`, `--kv-unified`, `--spm-infill`, `--pooling`, `-np`, `--parallel`, `-cb`, `--cont-batching`, `-nocb`, `--no-cont-batching`, `--threads-http`, `--cache-reuse`
* Network and API configuration: `-a`, `--alias`, `--host`, `--port`, `--path`, `--api-prefix`, `--api-key`, `--api-key-file`, `-to`, `--timeout`
* Web UI and monitoring: `--webui-config`, `--webui-config-file`, `--webui`, `--no-webui`, `--metrics`, `--props`, `--slots`, `--no-slots`, `--slot-save-path`
* Built-in tools and agent mode: `--tools`, `-ag`, `--agent`, `-no-ag`, `--no-agent`, `--ui-mcp-proxy`, `--webui-mcp-proxy`, `--no-ui-mcp-proxy`, `--no-webui-mcp-proxy`
* Router and media: `--media-path`, `--models-dir`, `--models-preset`, `--models-max`, `--models-autoload`, `--no-models-autoload`
* Embeddings, reranking, and TLS: `--embedding`, `--embeddings`, `--rerank`, `--reranking`, `--ssl-key-file`, `--ssl-cert-file`
* Chat templating and slot behavior: `--chat-template-kwargs`, `--jinja`, `--no-jinja`, `--reasoning-format`, `--reasoning-budget`, `--chat-template`, `--chat-template-file`, `--prefill-assistant`, `--no-prefill-assistant`, `-sps`, `--slot-prompt-similarity`, `--lora-init-without-apply`, `--sleep-idle-seconds`
* Draft, speculative decoding, and TTS: `-td`, `--threads-draft`, `-tbd`, `--threads-batch-draft`, `--draft`, `--draft-n`, `--draft-max`, `--draft-min`, `--draft-n-min`, `--draft-p-min`, `-cd`, `--ctx-size-draft`, `-devd`, `--device-draft`, `-ngld`, `--gpu-layers-draft`, `--n-gpu-layers-draft`, `-md`, `--model-draft`, `--spec-replace`, `-mv`, `--model-vocoder`, `--tts-use-guide-tokens`
* Built-in server defaults: `--embd-gemma-default`, `--fim-qwen-1.5b-default`, `--fim-qwen-3b-default`, `--fim-qwen-7b-default`, `--fim-qwen-7b-spec`, `--fim-qwen-14b-spec`, `--fim-qwen-30b-default`, `--gpt-oss-20b-default`, `--gpt-oss-120b-default`, `--vision-gemma-4b-default`, `--vision-gemma-12b-default`

`-np, --parallel` in server mode controls the number of server slots rather than the number of parallel decode sequences.

The Web UI is inherited from llama.cpp and may refer to its upstream server executable as `llama-server`. In those instructions, use the name of the llamafile executable instead. For example, `llama-server --tools all` becomes `./ModelName.llamafile --server --tools all` for a model-bundled llamafile.

## Notes

* The lists above are a readable index, not a second source of truth. The help output from your executable reflects the exact bundled `llama.cpp` version.
* If you are unsure whether a flag is shared, CLI-only, or server-only, check the help for that mode rather than relying on another mode's option list.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.mozilla.ai/llamafile/reference/cli_arguments.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.