dragiter(1)                     September 2026                         dragiter(1)

NAME
       dragiter - Deterministic Context Iterator - command-line tool for
       structured, reproducible LLM-based processing of materials with
       prompts and looping

SYNOPSIS
       dragiter [OPTIONS]
       dragiter-gen-docs [PATH]
       dragiter-gen-examples [PATH]

DESCRIPTION
       dragiter is a focused command-line tool that performs controlled,
       reproducible calls to OpenAI-compatible LLM services. Live calls
       always stream (OpenAIServiceExt / httpx2). The streaming path
       requires openai >= 3.0.0,<4.0.0 and httpx2 >= 2.7.0,<3.0.0;
       openai 1.x / 2.x do not provide DefaultHttpx2Client. It combines:

       * input material (documents, chunks, JSONL, …)
       * prompt templates
       * optional looping / iteration logic
       * configurable output routing (single file, directory, append /
         overwrite / exclusive)

       Configuration values are resolved in the following strict order of
       precedence (highest priority first):

           1. Command-line arguments
           2. TOML configuration file
              (via -c / --config-file, DRAGITER_CONFIG_FILE, or
              ~/.config/dragiter/config.toml if present)
           3. Environment variables (DRAGITER_*)
           4. Hard-coded program defaults

       Once a value has been set by a higher-priority source it cannot be
       overwritten by a lower-priority source.

OPTIONS
       General Flags
           -d, --debug                Enable debug logging
           -s, --simulate             Simulation mode (no real API calls)
           -v, --verbose              Verbose progress: logger INFO
                                      heartbeat every 10 s while a
                                      completion is streaming (no stdout
                                      spinner)
           -c, --config-file PATH     Path to a specific TOML configuration
                                      file. A relative path is resolved
                                      against -b when -b is set
           -b, --base-directory PATH  Base directory for relative file
                                      paths. Not pre-filled with the
                                      process CWD; unset until -b, the
                                      config file or DRAGITER_BASE_DIRECTORY
                                      supplies a value. Resource globs
                                      without a section base_directory
                                      still start from CWD and are rebased
                                      onto -b only when the original path
                                      was relative
           -L, --log-file PATH        Write application log to the given
                                      file (simple append, no rotation)
           --sequential-processing    Process each material chunk in its
                                      own request instead of batching
           --pack-limit-chars INT     Pack consecutive regex chunks of the
                                      same file until this many characters
                                      is reached. 0 or unset leaves chunks
                                      as the regex produced them. A value
                                      set here overrides pack_limit_chars
                                      in the resource TOML
           --max-chunks INT           Maximum chunks per run. Unset uses
                                      200. Values must be >= 1

       API & Connection
           --api-key KEY              API key for the LLM service
           --base-url URL             Base URL of the OpenAI-compatible
                                      endpoint
           --model-name MODEL         Model identifier (e.g. qwen3:8b,
                                      llama3, grok-beta)
           --temperature FLT          Sampling temperature (0.0 =
                                      deterministic)
           --chars-per-token FLT      Average characters per token used
                                      for context estimation
           --max-context-tokens INT   Total context window of the model
                                      (input + output)
           --max-output-tokens INT    Maximum tokens the model may generate
           --retry-delay INT          Base wait in seconds before attempt
                                      2 and later; doubles each time.
                                      Unset uses 3 s at runtime (0-20)
           --max-retry INT            Number of completion attempts, not
                                      extra retries. Unset or 0 means one
                                      try (allowed range 0-9)
           --ca-bundle-file PATH      Custom CA certificate bundle (PEM)
           --client-cert-file PATH    Client certificate for mTLS (PEM)
           --client-key-file PATH     Client private key for mTLS
           --tcp-keep-alive           Enable TCP keep-alive on the HTTP
                                      transport (httpx2 HTTPTransport)

       Task & Prompt Control
           -p, --prompt-file PATH     Path to prompt template (TOML)
           -t, --task TEXT            Direct task string (alternative to
                                      -p)
           -r, --resource-file PATH   Path to resource definition (TOML)
           -l, --loop-file PATH       Path to loop file (.txt or .jsonl)

       Output Control
           -m, --output-mode MODE     File open mode: x = exclusive
                                      (default), w = overwrite, a = append
           -o, --output-file PATH     Write all results to a single file
           -O, --output-directory DIR Write results into the given
                                      directory
           --output-delimiter TEXT    Text inserted between multiple
                                      results
           --output-filename-schema   Filename template for -O (supports
                                      {CHUNK_*}, {LOOP_*} placeholders)
           -a, --activity-file PATH   Write detailed activity trace (JSONL)

       Help & Utilities
           -h, --help                 Show short argparse help and exit
           --info                     Show this detailed information page
           --version                  Show program version and exit

       Utility Commands
           dragiter-gen-docs [PATH]       Extract documentation (default:
                                          ./docs/)
           dragiter-gen-examples [PATH]   Extract examples (default:
                                          ./examples/)

EXIT STATUS
       0      Success
       1      Configuration or critical error
       130    Process interrupted by user (KeyboardInterrupt)

ENVIRONMENT
       Boolean flags (env / TOML strings for the env path) accept, after
       strip + upper-case: TRUE / 1 / YES / ON / Y (true) and FALSE / 0 /
       NO / OFF / N (false). Other values raise. Native TOML booleans
       (simulate = true) are required in the config file; quoted strings
       are not coerced there:

           DRAGITER_DEBUG
           DRAGITER_SIMULATE
           DRAGITER_VERBOSE
           DRAGITER_SEQUENTIAL_PROCESSING
           DRAGITER_TCP_KEEP_ALIVE

       String / numeric settings:

           DRAGITER_API_KEY
           DRAGITER_BASE_URL
           DRAGITER_MODEL_NAME
           DRAGITER_TEMPERATURE
           DRAGITER_CHARS_PER_TOKEN
           DRAGITER_MAX_CONTEXT_TOKENS
           DRAGITER_MAX_OUTPUT_TOKENS
           DRAGITER_PACK_LIMIT_CHARS
           DRAGITER_MAX_CHUNKS
           DRAGITER_RETRY_DELAY
           DRAGITER_MAX_RETRY
           DRAGITER_OUTPUT_MODE          (x | w | a)
           DRAGITER_OUTPUT_DELIMITER
           DRAGITER_OUTPUT_FILENAME_SCHEMA
           DRAGITER_ACTIVITY_FILE
           DRAGITER_BASE_DIRECTORY
           DRAGITER_CONFIG_FILE
           DRAGITER_CA_BUNDLE_FILE
           DRAGITER_CLIENT_CERT_FILE
           DRAGITER_CLIENT_KEY_FILE
           DRAGITER_LOG_FILE
           DRAGITER_LOOP_FILE
           DRAGITER_OUTPUT_FILE
           DRAGITER_OUTPUT_DIRECTORY
           DRAGITER_PROMPT_FILE
           DRAGITER_RESOURCE_FILE

FILES
       ~/.config/dragiter/config.toml
              Default user configuration file (loaded when neither -c nor
              DRAGITER_CONFIG_FILE is set).

SEE ALSO
       Full documentation (Tutorial, How-to guides, Explanation and
       Technical Reference) can be extracted with:

           dragiter-gen-docs .

REPORTING BUGS
       dragiter is a small, community-driven tool. Bug reports are of
       course accepted. Should you feel inclined to investigate the
       matter yourself, modern language models have been known to be
       surprisingly competent at reading the code and suggesting
       patches.

       For issues that prove rather more troublesome, please contact:
       Michael Buchold <michael.buchold@dragiter.app>


AUTHOR
       Michael Buchold <michael.buchold@dragiter.app>

dragiter(1)                     September 2026                         dragiter(1)
