Implementation:Ggml org Llama cpp Arg Parser
| Knowledge Sources | |
|---|---|
| Domains | CLI, Configuration |
| Last Updated | 2026-02-15 00:00 GMT |
Overview
Implements the comprehensive CLI argument parsing system for all llama.cpp example programs and tools.
Description
This file is the single source of truth for all CLI options across every llama.cpp tool. At approximately 3800 lines, it is the largest file in the common/ library. It defines the full catalog of command-line arguments as common_arg objects with fluent builder methods (set_examples, set_env, set_sparam). Each argument specifies which examples it applies to, environment variable bindings, help text, and a handler function that mutates common_params. The common_params_parse function iterates through argv, matches arguments, reads environment variables, validates values, and invokes the appropriate handler.
Usage
Used by all llama.cpp example programs and tools to parse command-line arguments into a unified common_params structure. Supports model URL/HF repo resolution, JSON schema to grammar conversion, negative argument forms (--no-xxx), and preset-only parameters.
Code Reference
Source Location
- Repository: Ggml_org_Llama_cpp
- File: common/arg.cpp
- Lines: 1-3799
Signature
#include "arg.h"
static std::string read_file(const std::string & fname);
static const std::vector<common_arg> & get_common_arg_defs();
// Key types used:
// - common_arg: individual argument definition with builder pattern
// - common_params: mega-struct holding all parsed configuration
// - common_params_parse(): main entry point for argument parsing
// - common_params_to_map(): structured access to parsed parameters
Import
#include "arg.h"
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| argc | int | Yes | Number of command-line arguments |
| argv | const char** | Yes | Array of command-line argument strings |
| example | llama_example | Yes | Which example program is running (determines available args) |
| env vars | various | No | Environment variables that override CLI arguments (e.g., LLAMA_ARG_MODEL) |
Outputs
| Name | Type | Description |
|---|---|---|
| common_params | struct | Fully populated parameter structure with all parsed and validated settings |
| help text | string | Auto-generated usage/help text when --help is passed |
Usage Examples
#include "arg.h"
#include "common.h"
int main(int argc, char ** argv) {
common_params params;
if (!common_params_parse(argc, argv, params, LLAMA_EXAMPLE_CLI)) {
return 1;
}
// params is now populated with all CLI arguments
printf("Model: %s\n", params.model.path.c_str());
printf("Threads: %d\n", params.cpuparams.n_threads);
return 0;
}