quiCkLI Concepts

quickli is built from a small set of explicit, modular concepts. Each concept represents a focused building block in your CLI architecture, ensuring clarity, testability, and extensibility without speculative abstractions.

Application
├── global_options           ← application-wide flags/values
├── Command "build"
│   ├── Argument "target"    ← positional required input
│   └── Option "--output"    ← named local flag or setting
├── Command "env"
│   └── Subcommand "create"  ← nested action under parent command
├── Plugin "metrics"
│   └── Command "stats"      ← external commands attached via plugin contract
├── Config                   ← persistent TOML config loaded at application startup
└── Parsers                  ← format helpers (JSON, YAML, TOML) used inside handlers

Core Concept Hierarchy

Every quickli CLI has a single Application instance at its root.

• Application owns the command registry, handles global options, dispatches command tokens, and manages the execution lifecycle (run() vs main()).
• Command wraps an individual CLI operation. Commands define positional Argument resources and named Option resources, and can contain nested Subcommand trees.
• Argument represents required or optional positional input passed to a command in a fixed order.
• Option represents named, order-independent input (such as --verbose or --output=file.txt). Options can be local to a command or global across the application.
• Config manages persistent TOML settings on disk, using a ConfigSchema to validate user configuration on startup.
• Parsers provide utility functions (load_json, render_yaml, load_toml, etc.) to parse and format structured data within handlers or converters.
• Plugin allows external packages or modules to attach new commands to an Application without modifying the core application code.

When to Use Which Concept

Goal / Requirement	Recommended Concept	Concept Page
Single-action CLI tool (like cat or head)	Application + @app.entrypoint	Application
Multi-action CLI tool (like git or kubectl)	Application + @app.command	Application / Command
Accept required or optional positional input	Argument	Argument
Accept optional named flags, toggles, or key-value settings	Option	Option
Define flags that apply to all commands in the CLI	Global Option on Application	Option
Persist user settings to a TOML file across runs	Config + ConfigSchema	Config
Parse or produce JSON, YAML, or TOML data within a command	parsers helpers	Parsers
Package reusable commands across teams or projects	Plugin	Plugin

Explicit Architecture

quickli avoids hidden magic and silent assumptions. Resource definitions (Argument, Option, ConfigField) explicitly declare types, defaults, converters, and validators so that help text, parsing, and signature binding remain completely deterministic.

Separation of Execution Models

When executing a CLI, Application.run() executes the selected command and returns its string result without printing or calling sys.exit(). This makes unit testing straightforward. For production binaries, Application.main() wraps run() with standard output formatting, structured error handling, and process exit codes. See the Application documentation for details.

Where to Start

If you are new to quickli, start with the Getting Started guide to build your first CLI, then reference these concept pages to explore advanced capabilities.

Concept Index

• Application — Root CLI container, registration APIs, global options, and execution models.
• Command — Command authoring, docstrings, subcommands, signature binding, and validation.
• Argument — Positional inputs, converters, built-in validators, and metavar formatting.
• Option — Short/long options, boolean flags, repeatable flags/values, local vs global scope.
• Config — Native TOML configuration files, field validation, auto-initialization, and schema JSON.
• Parsers — Format helpers for JSON, YAML, and TOML serialization and deserialization.
• Plugin — Plugin contract, registration lifecycle, duplicate protection, and error handling.