Skip to content

Customization

Clak ships sensible defaults. This guide covers what you commonly tweak next: Meta, help text, and built-in behaviour.

Built-in behaviour (no mixin)

These work on any Parser:

  • Automatic --help / -h
  • Instantiating the root parser parses argv and runs the matched command (pass parse=False to build without dispatching)
  • Error and exception handling — ClakUserError, exit codes, Meta.known_exceptions

Clak does not auto-map arbitrary environment variables to CLI options. Library flags that do read the environment:

  • CLAK_DEBUG, CLAK_LOG_COLORS, CLAK_COLORS — see Logging
  • $XDG_* — see Config when using XDGConfigMixin

Env-var → option mapping is on the roadmap.

Arguments

Define arguments on the class with Argument — same kwargs as argparse.ArgumentParser.add_argument(). See the Parser API.

class MyCmd(Parser):
    verbose = Argument("-v", "--verbose", action="store_true", help="Verbose")
    path = Argument("PATH", help="Input path")

Parser Meta

Nested Meta changes parser behaviour. Common settings:

class MyApp(Parser):
    class Meta:
        app_name = "myapp"              # XDG paths, process naming
        help_description = "My CLI"     # override docstring-based description
        known_exceptions = [MyDomainError]

Exception-related settings: Error handling. Logging / views / config each document their own Meta keys on their guides.

Inheritance

Share options or helpers via a base class:

class BaseCmd(Parser):
    dry_run = Argument("--dry-run", action="store_true")

    def maybe_write(self, dry_run=False, **_):
        if dry_run:
            print("skip write")
            return
        ...

class ApplyCmd(BaseCmd):
    def cli_run(self, **kwargs):
        self.maybe_write(**kwargs)

Parent options are visible to child cli_run methods when using nested Commands — see Nested commands.

Next steps