Implementation:Ggml org Llama cpp Arg Header

Knowledge Sources	Ggml_org_Llama_cpp
Domains	CLI, Configuration
Last Updated	2026-02-15 00:00 GMT

Overview

Declares the CLI argument definition and parsing infrastructure used uniformly by all llama.cpp tools.

Description

Defines the `common_arg` struct which represents a single CLI argument with its names, negative forms (`--no-xxx`), environment variable bindings, help text, example scope filtering, and typed handler function pointers (void, string, int, bool, str+str). Provides `common_params_context` to hold the parser state including the example type and option list. Declares `common_params_parse` for standard CLI parsing, `common_params_to_map` for structured extraction, and `common_params_parser_init` for initializing the parser context. Also includes the `common_arg_utils` namespace with helpers for boolean/truthy/falsey value interpretation and `COMMON_ARG_PRESET` macros for preset-only arguments.

Usage

Include this header when defining CLI arguments for any llama.cpp tool. It provides the type system and API that enables all tools to define, parse, and process command-line arguments uniformly through a declarative pattern.

Code Reference

Source Location

• Repository: Ggml_org_Llama_cpp
• File: common/arg.h
• Lines: 1-131

Signature

struct common_arg {
    std::set<enum llama_example> examples;
    std::set<enum llama_example> excludes;
    std::vector<const char *> args;
    std::vector<const char *> args_neg;
    const char * value_hint   = nullptr;
    const char * value_hint_2 = nullptr;
    const char * env          = nullptr;
    std::string help;
    bool is_sparam = false;
    bool is_preset_only = false;

    void (*handler_void)   (common_params & params) = nullptr;
    void (*handler_string) (common_params & params, const std::string &) = nullptr;
    void (*handler_str_str)(common_params & params, const std::string &, const std::string &) = nullptr;
    void (*handler_int)    (common_params & params, int) = nullptr;
    void (*handler_bool)   (common_params & params, bool) = nullptr;

    common_arg & set_examples(std::initializer_list<enum llama_example> examples);
    common_arg & set_excludes(std::initializer_list<enum llama_example> excludes);
    common_arg & set_env(const char * env);
    common_arg & set_sparam();
    common_arg & set_preset_only();
    bool in_example(enum llama_example ex);
    bool is_exclude(enum llama_example ex);
};

struct common_params_context {
    enum llama_example ex;
    std::vector<common_arg> options;
};

bool common_params_parse(int argc, char ** argv, common_params & params, llama_example ex);

Import

#include "common.h"
#include <set>
#include <map>
#include <string>
#include <vector>
#include <cstring>

I/O Contract

Inputs

Name	Type	Required	Description
argc	int	Yes	Argument count from main()
argv	char**	Yes	Argument values from main()
params	common_params&	Yes	Parameter struct to populate with parsed values
ex	llama_example	Yes	Example type enum to filter which arguments are relevant

Outputs

Name	Type	Description
return value	bool	True if parsing succeeded, false on error or --help
params	common_params&	Populated parameter struct with all parsed CLI values

Usage Examples

#include "arg.h"

// Define a custom argument
common_arg my_arg(
    {"-x", "--my-option"},
    "VALUE",
    "Description of my option",
    [](common_params & params, const std::string & val) {
        // handle the value
    }
);
my_arg.set_examples({LLAMA_EXAMPLE_SERVER});

// Parse CLI arguments
common_params params;
if (!common_params_parse(argc, argv, params, LLAMA_EXAMPLE_MAIN)) {
    return 1;
}

Related Pages

• Principle:Ggml_org_Llama_cpp_CLI_Configuration