DEV Community: Mauricio Villegas

Swapping implementations from the command line

Mauricio Villegas — Wed, 16 Sep 2026 05:37:29 +0000

The tool built over the last four posts asks the catalog the same questions again and again. summary alone is six requests, one per magnitude band plus one for the strongest event. Run it, change the end date by a day, run it again, and five of those six answers were already on your screen a moment ago.

So the client wants a cache. The awkward part is not writing one. It is that there is no single right one:

At a terminal the process dies after every command, so anything kept in memory is gone before it is useful. The cache has to be files on disk.
In a notebook or a web service the process stays alive, and a dictionary in memory is both faster and simpler than touching the disk.
On a group of machines that share work, neither of those is right, and the answer is redis or memcached, which this project has no business depending on.

The usual way to offer a choice like that on a command line is a flag with a few allowed words, --cache-type={none,memory,disk}, plus --cache-path and --cache-ttl that mean something for one of those words and nothing for the others, plus a small block of if and elif inside the program that turns the word into an object. And when someone wants the redis one, they cannot have it without editing your tool.

That block is a copy of something already written down, in the same way that the completion script in part 3 and the os.environ.get calls in part 4 were copies. What is already written down, this time, is a type hint:

cache: Cache | None = None

A collaborator, in plain Python

Nothing below is about command lines. It is the code you would write anyway, in quakes_client.py, if the client were only ever used from Python.

A base class that says what a cache has to be able to do:

class Cache(ABC):
    """Store for responses that were already received from the catalog.

    Subclasses decide where the entries are kept and for how long. The client
    only asks for a key and hands back whatever the catalog answered.
    """

    @abstractmethod
    def get(self, key: str) -> dict | None:
        """Return the entry kept for a key, or None if there is no valid one.

        Args:
            key: Identifier of the entry, the URL of the request.
        """

    @abstractmethod
    def set(self, key: str, value: dict) -> None:
        """Keep an entry for a key.

        Args:
            key: Identifier of the entry, the URL of the request.
            value: The response to keep.
        """

And two implementations of it, one for each of the first two situations above:

class MemoryCache(Cache):
    """Cache that keeps entries in memory, for as long as the process lives."""

    def __init__(self, max_entries: int = 128):
        """Initialize the cache.

        Args:
            max_entries: How many entries to keep. The oldest one is dropped first.
        """
        self.max_entries = max_entries
        self._entries: dict[str, dict] = {}

    def get(self, key: str) -> dict | None:
        return self._entries.get(key)

    def set(self, key: str, value: dict) -> None:
        if len(self._entries) >= self.max_entries:
            del self._entries[next(iter(self._entries))]
        self._entries[key] = value


class DiskCache(Cache):
    """Cache that keeps entries as files, so that they outlive the process."""

    def __init__(self, path: Path = Path("~/.cache/quakes"), ttl: float = 3600.0):
        """Initialize the cache.

        Args:
            path: Directory in which the entries are written.
            ttl: Seconds an entry stays valid before the catalog is asked again.
        """
        self.path = path.expanduser()
        self.ttl = ttl

    def get(self, key: str) -> dict | None:
        entry = self._entry(key)
        if not entry.exists() or time.time() - entry.stat().st_mtime > self.ttl:
            return None
        return json.loads(entry.read_text())

    def set(self, key: str, value: dict) -> None:
        self.path.mkdir(parents=True, exist_ok=True)
        self._entry(key).write_text(json.dumps(value))

    def _entry(self, key: str) -> Path:
        return self.path / f"{hashlib.sha256(key.encode()).hexdigest()[:32]}.json"

The two have different parameters, which is the whole point of the example. max_entries only makes sense for a cache in memory. path and ttl only make sense for one on disk.

The client takes one, as a new constructor parameter next to the ones from part 1:

    def __init__(
        self,
        distance_unit: Literal["km", "mi"] = "km",
        min_magnitude: float = 2.5,
        timeout: float = 30.0,
        cache: Cache | None = None,
    ):
        """Initialize the client.

        Args:
            distance_unit: Unit used for all distances, both given and returned.
            min_magnitude: Magnitude below which events are ignored by default.
            timeout: Seconds to wait for a response before giving up.
            cache: Where to keep the responses already received, if anywhere.
        """

and consults it in the one private method that performs a request:

    def _get(self, path: str, **params) -> dict:
        url = f"{USGS_URL}{path}?{urlencode({'format': 'geojson', **params})}"
        if self.cache is not None and (kept := self.cache.get(url)) is not None:
            return kept
        try:
            with urlopen(Request(url), timeout=self.timeout) as response:
                data = json.loads(response.read())
        except HTTPError as ex:
            reported = ex.read().decode(errors="replace").strip().splitlines()
            raise CatalogError(f"{reported[0] if reported else ex.reason} (requesting {path})") from ex
        if self.cache is not None:
            self.cache.set(url, data)
        return data

Note what the client does not do. It does not choose a cache, it does not build one, and it never names MemoryCache or DiskCache. It says what it needs, as a type, and waits to be given one:

from quakes_client import EarthquakeCatalog, MemoryCache

catalog = EarthquakeCatalog(min_magnitude=6, cache=MemoryCache())

That is dependency injection, and there is nothing clever about it. It is ordinary Python, it is what makes the class easy to test, and every part of it is useful with no command line involved. The rest of this post is about what jsonargparse does with it.

An option nobody added

quakes_cli.py was not touched. The help has one more option:

$ quakes --help
Client for the earthquake catalog of the U.S. Geological Survey:
  ...
  ARG:   --cache.help [CLASS_PATH_OR_NAME]
                        Show the help for the given subclass of Cache and
                        exit.
  ARG:   --cache CACHE
  ENV:   QUAKES_CACHE
                        Where to keep the responses already received, if
                        anywhere. (type: Cache | null, default: null, known
                        subclasses: quakes_client.MemoryCache,
                        quakes_client.DiskCache)

known subclasses is the list nobody had to write. jsonargparse looks for subclasses of Cache in the modules the program has imported, and those are what it found. Adding a third one to the client adds a third name to that line.

This is a different treatment from the one Area got in part 1, and the difference comes from the classes, not from any setting. Area is a concrete dataclass, so there is nothing to decide and its three fields became options directly: --area.latitude and friends. Cache is a base class with more than one implementation, so there is something to decide, and the decision comes first. Which options exist depends on what you decided.

Choosing one

The value of --cache is a class:

$ quakes --cache=DiskCache summary --start=2026-07-01 --end=2026-08-01
{
  "start": "2026-07-01",
  "end": "2026-08-01",
  "total": 3817,
  "by_magnitude": {
    "minor 2.0-3.9": 2330,
    "light 4.0-4.9": 1262,
    "moderate 5.0-5.9": 214,
    "strong 6.0-6.9": 10,
    "major 7.0+": 1
  },
  "strongest": {
    "time": "2026-07-17 14:48:40.227000+00:00",
    "magnitude": 7.3,
    "depth": 22,
    "latitude": 14.6361,
    "longitude": -92.8969,
    "id": "us7000t1bu",
    "place": "52 km W of Puerto Madero, Mexico"
  }
}

Run it a second time and the six requests are not made:

$ time quakes --cache=DiskCache summary --start=2026-07-01 --end=2026-08-01 > /dev/null
real    0m0.670s
$ time quakes --cache=DiskCache summary --start=2026-07-01 --end=2026-08-01 > /dev/null
real    0m0.237s

Most of that second number is Python starting up and the parser being built. The catalog was not contacted at all.

The parser imported the class, built it with its defaults, and passed the instance to EarthquakeCatalog.__init__. That is the injection, performed by the command line instead of by a line of Python.

DiskCache is the short name and works because the class is one of the known subclasses above. The full import path, quakes_client.DiskCache, always works and is what a config file or a script should use, since it cannot become ambiguous later.

The options come from the class you chose

--cache.help prints the help of an implementation, built from that implementation's own signature and docstring, the same way the main help was built from the client:

$ quakes --cache.help DiskCache
usage: quakes [--cache.path PATH] [--cache.ttl TTL]

Help for --cache.help=quakes_client.DiskCache

Cache that keeps entries as files, so that they outlive the process:
  --cache.path PATH  Directory in which the entries are written. (type: <class
                     'Path'>, default: ~/.cache/quakes)
  --cache.ttl TTL    Seconds an entry stays valid before the catalog is asked
                     again. (type: float, default: 3600.0)

$ quakes --cache.help MemoryCache
usage: quakes [--cache.max_entries MAX_ENTRIES]

Help for --cache.help=quakes_client.MemoryCache

Cache that keeps entries in memory, for as long as the process lives:
  --cache.max_entries MAX_ENTRIES
                        How many entries to keep. The oldest one is dropped
                        first. (type: int, default: 128)

Two implementations, two different help pages, no shared list of flags between them. And they are set the way you would expect:

$ quakes --cache=DiskCache --cache.ttl=600 --cache.path=/tmp/quakes \
      count --start=2026-07-01 --min_magnitude=6
20

Two small rules go with that.

The class comes before its options. The parser has to know which class it is building before it can decide what --cache.ttl means, so the reverse order is an error:

$ quakes --cache.ttl=600 --cache=DiskCache count
error: Parser key "cache":
  ...
    - Expected an instantiatable class, but quakes_client.Cache is abstract

An option that the chosen class does not have is an error, not a value that is ignored:

$ quakes --cache=MemoryCache --cache.ttl=600 count
error: Parser key "cache":
  ...
    - Problem with given class_path 'quakes_client.MemoryCache':
        Option 'ttl' is not accepted

Which is the behaviour you want and the one a hand written --cache-type flag almost never has. There, --cache-ttl next to --cache-type=memory is usually accepted and quietly does nothing.

A class the tool has never heard of

Here is the part that a fixed list of words cannot do.

Say you want to know which requests are being served from the cache and which are not. That is a cache of your own, and it is short, because it only changes one of the two methods:

# logging_cache.py
"""A cache of my own, in a file the quakes command knows nothing about."""

import sys

from quakes_client import DiskCache


class LoggingCache(DiskCache):
    """Disk cache that reports on standard error whether each key was found."""

    def get(self, key: str) -> dict | None:
        value = super().get(key)
        print(f"cache {'hit ' if value else 'miss'}: {key}", file=sys.stderr)
        return value

Put that file anywhere the Python process can import it from, and name it:

$ PYTHONPATH=. quakes --cache=logging_cache.LoggingCache --cache.ttl=600 \
      count --start=2026-07-01 --min_magnitude=6
cache miss: https://earthquake.usgs.gov/fdsnws/event/1/count?format=geojson&starttime=2026-07-01&minmagnitude=6.0
20
$ PYTHONPATH=. quakes --cache=logging_cache.LoggingCache --cache.ttl=600 \
      count --start=2026-07-01 --min_magnitude=6
cache hit : https://earthquake.usgs.gov/fdsnws/event/1/count?format=geojson&starttime=2026-07-01&minmagnitude=6.0
20

--cache.ttl still works, because LoggingCache inherits the constructor of DiskCache, and the help page of a class written five minutes ago is as complete as the ones that ship with the tool:

$ PYTHONPATH=. quakes --cache.help logging_cache.LoggingCache
usage: quakes [--cache.path PATH] [--cache.ttl TTL]

Help for --cache.help=logging_cache.LoggingCache

Disk cache that reports on standard error whether each key was found:
  --cache.path PATH  Directory in which the entries are written. (type: <class
                     'Path'>, default: ~/.cache/quakes)
  --cache.ttl TTL    Seconds an entry stays valid before the catalog is asked
                     again. (type: float, default: 3600.0)

quakes was not reinstalled, not edited, and not told that this class exists. There is no plug-in registry, no entry point group, no --load-plugin argument. The redis cache from the beginning of this post is now somebody else's file, in somebody else's package, and it costs this project nothing.

That is the property worth naming, because it is what the fixed list of words cannot give you. A tool whose choices are {none,memory,disk} is a tool whose author has to say yes before you can have a fourth. A tool whose choice is a type hint is one where the author is not involved.

What is checked, and what is not

Two conditions have to hold, and both produce a clear failure at startup rather than a strange one later.

The class has to be importable by the process. Nothing is searched for; the dotted path is imported the way Python imports anything. PYTHONPATH=. above is what makes a file in the current directory reachable, since the quakes command is a script installed elsewhere and does not add your working directory to sys.path. If the class lives in an installed package, nothing extra is needed.

$ quakes --cache=logging_cache.LoggingCache count
error: Parser key "cache":
  ...
    - Problem with given class_path 'logging_cache.LoggingCache':
        No module named 'logging_cache'

The class has to satisfy the hint. Any importable name is accepted as text; only a subclass of Cache survives:

$ quakes --cache=quakes_client.Area count
error: Parser key "cache":
  ...
    - Import path does not correspond to a subclass of Cache

And the base class itself is not a choice, because it is abstract and cannot be built:

$ quakes --cache=Cache count
error: Parser key "cache":
  ...
    - Expected an instantiatable class, but is abstract

It is worth being explicit about what all of this means: the command line can now name a class, and the program will import the module that contains it. Importing a Python module runs its top level code. In practice this is the same trust boundary a command line already has — anyone who can choose your arguments can usually choose your PYTHONPATH, and on that machine they can just run Python — but it is a real widening of what an argument can do, and it deserves a thought before a tool that takes arguments from somewhere less trusted than a person's keyboard.

If you want a fixed set instead, say so in the hint. Write the parameter as a union of concrete classes rather than as the base class:

cache: MemoryCache | DiskCache | None = None

and those two, plus anything derived from them, are all that is accepted. A different subclass of Cache is not:

$ quakes --cache=other_cache.NullCache count
error: Parser key "cache":
  Does not validate against any of the Union subtypes
  Subtypes: [<class 'quakes_client.MemoryCache'>, <class 'quakes_client.DiskCache'>, <class 'NoneType'>]
  Errors:
    - Import path does not correspond to a subclass of MemoryCache
    - Import path does not correspond to a subclass of DiskCache
    ...

Which is the same trade as everywhere else in this series. The command line is as open, or as closed, as the type hint says it is, and the type hint is in the client where a reader of the code will see it.

The other four posts still apply

Nothing about --cache is a special case, so everything the earlier posts added works on it.

A config file (part 2) writes the choice as a class and its arguments. This is the full form of the value, and it is what the dotted options on the command line are a shorthand for:

# config.yaml
distance_unit: mi
min_magnitude: 4.0
timeout: 60.0
cache:
  class_path: quakes_client.DiskCache
  init_args:
    ttl: 21600

The two layers combine per option rather than per value, so the command line can change one setting of the cache without repeating which cache it is:

$ quakes --config config.yaml --cache.ttl=60 --print_config count
distance_unit: mi
min_magnitude: 4.0
timeout: 60.0
cache:
  class_path: quakes_client.DiskCache
  init_args:
    path: ~/.cache/quakes
    ttl: 60.0
...

And --cache=null turns it off for one run, whatever the file said.

If all you want is the class with its own defaults, the file can also say just the name, exactly as the command line does:

cache: MemoryCache

Environment variables (part 4) take the same two forms, and this is a case where the JSON one is bearable, because it is one small object:

$ QUAKES_CACHE=DiskCache quakes count --start=2026-07-01
3979
$ QUAKES_CACHE='{"class_path": "quakes_client.DiskCache", "init_args": {"ttl": 60}}' \
      quakes count --start=2026-07-01
3979

Completion (part 3) offers the implementations, since the parser knows them:

$ quakes --cache <TAB><TAB>
Expected type: Cache | null; 3/3 matched choices
null                       quakes_client.MemoryCache
quakes_client.DiskCache

and it offers the options of every known implementation, telling you which one each belongs to, since it cannot know yet what you are about to choose:

$ quakes --cache.<TAB><TAB>
--cache.help         --cache.path
--cache.max_entries  --cache.ttl

$ quakes --cache.ttl <TAB><TAB>
Expected type: float; Accepted by subclasses: DiskCache

--print_config is the one to reach for when a run does not behave as expected, because it prints the finished recipe: which class, with which arguments, after the file, the environment and the command line have all had their turn. It is also the easiest way to write the config file above — run the command once with the options you want, and paste.

The same hint in other shapes

Cache | None is one arrangement. A few others behave the way you would guess, and are worth knowing exist:

A parameter typed list[Cache] takes several of them. Each += appends one more, and the dotted options that follow apply to the one most recently appended.
Callable[[], Cache] asks for a factory instead of a finished object, for when one shared cache is wrong and multiple are needed: one per thread, one per request, one per retry.

The factory is the one worth showing, because nothing about the command line changes. Written this way:

new_cache: Callable[[], Cache] = MemoryCache

the option offers the same implementations, and its value is still a class with its arguments:

  --new_cache NEW_CACHE
                        Builds a fresh cache each time it is called. (type:
                        Callable[[], Cache], default: {'class_path':
                        'quakes_client.MemoryCache'}, known subclasses:
                        quakes_client.MemoryCache, quakes_client.DiskCache)

So --new_cache=DiskCache --new_cache.ttl=60 is typed exactly as it was before. What the constructor receives is not a DiskCache, though. It is something it can call, with the choice and the arguments already decided:

functools.partial(<function default_class_instantiator at ...>, <class 'quakes_client.DiskCache'>,
                  path=PosixPath('~/.cache/quakes'), ttl=60.0)

Every call to it builds a new cache. That splits the two decisions the way you want them: what to build is chosen where the command is typed, and when to build it stays in the code that knows how many are needed and when they stop being valid.

If the callable's own signature has parameters, they are taken off the command line, because the caller is going to supply them. With Callable it is their number that counts: Callable[[int, str], Cache] reserves the first two parameters of whichever class was chosen, whatever they are called, and --new_cache.help then offers only the rest. A callable Protocol, a class with a __call__ method whose signature is the one you want, reserves them by name instead, so the ones left for the caller do not have to be the leading ones.

The shape this post is about, though, is the common one, and it appears far away from caches. An optimizer in a training script, an authentication method, a storage backend, a notifier, an exporter: anything a program should be able to swap without being rewritten is a parameter whose type is a base class. It is how Lightning, which builds its CLI on jsonargparse, lets --optimizer=torch.optim.AdamW --optimizer.lr=0.001 reach a training run that does not know AdamW exists.

What the other libraries do here

Part 1 compared the alternatives and pinned the versions it checked, so here is the same exercise for this one feature, against click 8.4, typer 0.27, fire 0.7 and tyro 1.0. The example is a shortened Catalog class with the same cache: Cache | None = None parameter and the same two implementations.

Fire accepts the argument and passes the text through untouched. --cache=DiskCache arrives at the constructor as the string 'DiskCache', and --cache='{"class_path": "DiskCache"}' arrives as a plain dict. Nothing is imported, nothing is built, nothing is checked.

Typer stops before the program starts, in the same way part 1 found it stopping on a dataclass: RuntimeError: Type not yet supported: <class 'catalog.Cache'>.

Click infers nothing by design, so this is a thing you write: a click.Choice of names, a mapping from name to class, and one option per constructor argument of every implementation. Which is exactly the hand written version this post started from. Click will not stop you from doing it well, but it is your code, and it grows with each implementation.

Tyro is the one with a real answer. Written as a union of concrete classes, the choice becomes a subcommand, tyro builds that class from the arguments that follow it, and the program runs with the instance. The subcommands cost a few lines, because tyro builds a CLI from a function or a class rather than from a class's methods. An unbound method is a function whose first parameter is self, so annotating it with the client class is enough for tyro to build the client and pass it in:

EarthquakeCatalog.__init__.__annotations__["cache"] = Union[MemoryCache, DiskCache, None]

subcommands = {}
for name, method in inspect.getmembers(EarthquakeCatalog, inspect.isfunction):
    if not name.startswith("_"):
        method.__annotations__["self"] = Annotated[EarthquakeCatalog, tyro.conf.arg(name="client")]
        subcommands[name] = method

print(tyro.extras.subcommand_cli_from_dict(subcommands))

All five methods arrive with their own parameters and their docstrings, and nothing is restated. The equivalent of the command earlier in this post:

quakes --cache=DiskCache --cache.ttl=60 summary --start=2026-07-01 --end=2026-08-01

is this:

python quakes_tyro.py summary --start 2026-07-01 --end 2026-08-01 \
    client.cache:disk-cache --client.cache.ttl 60

The difference is the type hint, and the type hint lives in the client. EarthquakeCatalog declares cache: Cache | None, which is what the author of a client writes when no command line is in the picture. tyro reads it as naming the Cache class itself, which is abstract, so there is nothing to build: the option becomes --client.cache {fixed} (fixed to: None), and asking for client.cache:disk-cache is an unrecognized option. To get a choice, the parameter has to be rewritten as MemoryCache | DiskCache | None — an edit to quakes_client.py made for the benefit of the command line, and repeated every time an implementation is added. The snippet above makes that edit from the outside, so that the client in the repository stays the one the other posts describe.

Closed sets are a good design, and the union above says exactly that in jsonargparse too. The point is which way the dependency runs. What a closed set cannot accept is the name of a class written by a user of your tool, in a module your tool has never imported.

Neither of the other two shapes from earlier is available. A list[DiskCache] produces no option at all, the parameter simply not appearing in the help. And an instance factory, Callable[[], DiskCache], is fixed to whatever its default is and refuses any value given for it.

What this post leaves you with

Five posts, and the client has still not imported jsonargparse. What it gained this time was a collaborator it does not construct, described by a base class and a type hint, which is the shape a testable class has anyway.

Out of that, without a line in quakes_cli.py: an option that takes an implementation, a help page per implementation built from its own docstring, its constructor arguments as options, all of it settable from a config file or the environment, completed at the prompt, validated before anything runs, and open to classes that neither the tool nor its author has ever seen.

The trade is the one the series keeps making, and this is the largest version of it. A plug-in system is normally a subproject: a registry, a way to name plug-ins, a way to load them, a way to configure them, documentation for all of that. Here it is a parameter, typed honestly, in a class that does not know it has users at a terminal.

Settings from the environment

Mauricio Villegas — Wed, 02 Sep 2026 05:53:36 +0000

The second post gave the tool a config file it finds on its own, so that ~/.config/quakes.yaml decides what quakes does from any directory. That solves the problem for a person with a home directory, and it is the right default for one. It also assumes a filesystem you can write to before the program runs, which is the assumption that fails everywhere else the command is likely to end up.

A container image is built once and run with different settings. A CI job gets its configuration from the thing that started it. A systemd unit has Environment= lines and no obvious place to put a YAML file. In all three the settings arrive as environment variables, because that is the one channel a process always has, and the usual response is a block of os.environ.get calls somewhere near the top of the program, with its own names, its own defaults and its own idea of how to turn "6" into a float.

That block is another copy of the interface, in the same way the completion script in part 3 was a copy. The parser already knows every setting the program has, what type each one is and what it defaults to. Reading them from the environment instead of from argv is a different source for the same values, and it is two keyword arguments.

Two arguments, again

The change is in quakes_cli.py, next to the one from part 2:

result = auto_cli(
    EarthquakeCatalog,
    # Settings written here apply from any directory, without --config.
    default_config_files=["~/.config/quakes.yaml"],
    # And these let a process pass settings in without a file at all.
    # The prefix is spelled out because prog changes when the module is
    # run directly, and the variable names should not change with it.
    env_prefix="QUAKES",
    default_env=True,
)

default_env=True is what turns the parsing on. env_prefix is the first part of every variable name, and it is worth being explicit about even here, where the value looks redundant. Left unset, the prefix is derived from the program name, which is quakes when the installed command runs and quakes_cli.py when the module is run directly, as part 1 still does. Deriving it would mean QUAKES_MIN_MAGNITUDE and QUAKES_CLI_MIN_MAGNITUDE naming the same setting depending on how the program was started. Writing the prefix down costs one line and removes that.

The names are already decided

The rule is PREFIX_, then the argument name in upper case, with each dot replaced by two underscores. Client options are one level deep, so --min_magnitude is QUAKES_MIN_MAGNITUDE. A subcommand's options are two, so search's --limit is QUAKES_SEARCH__LIMIT.

Which is a rule nobody should have to remember, and does not have to, because the help now prints the variable next to the option it sets:

$ quakes --help
options:
  ARG:   -h, --help     Show this help message and exit.
  ARG:   --config CONFIG
  ENV:   QUAKES_CONFIG
                        Path to a configuration file.
...
Client for the earthquake catalog of the U.S. Geological Survey:
  ARG:   --distance_unit {km,mi}
  ENV:   QUAKES_DISTANCE_UNIT
                        Unit used for all distances, both given and returned.
                        (type: Literal['km', 'mi'], default: km)
  ARG:   --min_magnitude MIN_MAGNITUDE
  ENV:   QUAKES_MIN_MAGNITUDE
                        Magnitude below which events are ignored by default.
                        (type: float, default: 2.5)

The ARG: and ENV: labels appear only once environment parsing is on; before that the help looks as it did in the earlier posts. This is the part that tends to be missing when the variables are read by hand. A program with fifteen os.environ.get calls has fifteen names documented in a README if you are lucky, and the README is where they go out of date. Here the list cannot drift, for the same reason the completions could not: it is printed from the parser, and the parser was built from the client's signature.

The same holds one level down, including for the positional:

$ quakes event --help
  ARG:   event_id
  ENV:   QUAKES_EVENT__EVENT_ID
                        Identifier of the event, e.g. ``us7000srb1``.
                        (required, type: str)

So a run of the tool can be assembled entirely out of the environment:

$ QUAKES_MIN_MAGNITUDE=6 quakes count --start=2026-07-01
13
$ quakes --min_magnitude=6 count --start=2026-07-01
13

The subcommand is a variable too

Note the name in the help for the subcommands group:

$ quakes --help
subcommands:
  ENV:   QUAKES_SUBCOMMAND

The choice of subcommand is an argument like the others, so it is available the same way, and with it the command line can be empty. That is exactly the shape a container wants, and it is what makes the whole Dockerfile this:

FROM python:3.12-slim

WORKDIR /src
COPY pyproject.toml README.md LICENSE quakes_cli.py quakes_client.py ./
RUN pip install --no-cache-dir .

# No arguments. Everything the run needs is passed with -e, including which
# subcommand to run.
ENTRYPOINT ["quakes"]

No CMD, and nothing in the image that says what it does when it starts. Build it once:

docker build -t quakes .

A real image is named {registry}/{project}/quakes-cli:{tag}, and the short name is only used here to keep the runs below down to the part that matters. It does mean the image is spelled exactly like the command, so in every docker run that follows, the bare quakes on the last line is the image and anything after it is what gets appended to the entry point.

With that, the run is described entirely by its environment:

$ docker run --rm \
    -e QUAKES_SUBCOMMAND=count \
    -e QUAKES_COUNT__MIN_MAGNITUDE=6 \
    -e QUAKES_COUNT__START=2026-07-01 \
    quakes
13

There is no home directory in that container, therefore no ~/.config/quakes.yaml, therefore nothing but what was handed in. The same image and the same entry point, with a different set of variables, give a different program:

$ docker run --rm \
    -e QUAKES_SUBCOMMAND=search \
    -e QUAKES_DISTANCE_UNIT=mi \
    -e QUAKES_SEARCH__MIN_MAGNITUDE=6.5 \
    -e QUAKES_SEARCH__START=2026-07-01 \
    -e QUAKES_SEARCH__LIMIT=3 \
    quakes
time              magnitude  depth  latitude  longitude  id          place
2026-07-28 07:27  6.8        6.21   32.6817   130.7217   us6000tgb9  The 2026 Kumamoto Region, Japan Earthquake
2026-07-17 14:48  7.3        13.67  14.6361   -92.8969   us7000t1bu  52 km W of Puerto Madero, Mexico

Dates arrived as dates and mi reached the client, because register_type(date, ...) and the Literal from part 1 apply here too. The environment is a different source, not a different type system.

None of this closes the command line off. An ENTRYPOINT with no CMD appends whatever you put after the image name, so the same image is still the tool it was:

$ docker run --rm quakes count --min_magnitude=6 --start=2026-07-01
13

Which is the property worth protecting when a program grows a container. One image, driven by variables in production and by arguments when you are trying to work out what it did, with a single description of the settings behind both. A .gitlab-ci.yml, a Kubernetes env: block and a systemd unit's Environment= lines all reduce to the same thing.

Where this sits in the order

There are now five places a value can come from, and the order between them is fixed:

The default in the client's signature.
The files in default_config_files, in the order given.
The config file named by QUAKES_CONFIG.
The individual variables, QUAKES_MIN_MAGNITUDE and friends.
The command line, left to right.

With part 2's file in place:

# ~/.config/quakes.yaml
distance_unit: mi
min_magnitude: 4.0

each layer overrides the one before it:

$ quakes count --start=2026-07-01
1486
$ QUAKES_MIN_MAGNITUDE=6 quakes count --start=2026-07-01
13
$ QUAKES_MIN_MAGNITUDE=6 quakes --min_magnitude=7 count --start=2026-07-01
1

The ordering is the one that makes deployment work: the file is what the machine believes, the environment is what this run believes, the command line is what you believe right now. A container inherits the image's defaults and overrides the two settings the job cares about, without a file being rewritten anywhere.

QUAKES_CONFIG deserves its own line in that list. It takes a path and loads a whole file, which is the answer when a run needs more than a couple of settings changed, and it sits below the individual variables rather than above:

# ci.yaml
distance_unit: mi
min_magnitude: 5.0

$ QUAKES_CONFIG=ci.yaml quakes count --start=2026-07-01
262
$ QUAKES_CONFIG=ci.yaml QUAKES_MIN_MAGNITUDE=6 quakes count --start=2026-07-01
13

Which is the combination a deployment usually ends up wanting, and in a container it is literally that: mount the file, name it with a variable, override the one setting this run disagrees about.

$ docker run --rm -v "$PWD/ci.yaml:/etc/quakes.yaml:ro" \
    -e QUAKES_CONFIG=/etc/quakes.yaml \
    -e QUAKES_SUBCOMMAND=count -e QUAKES_COUNT__START=2026-07-01 \
    quakes
262
$ docker run --rm -v "$PWD/ci.yaml:/etc/quakes.yaml:ro" \
    -e QUAKES_CONFIG=/etc/quakes.yaml -e QUAKES_MIN_MAGNITUDE=6 \
    -e QUAKES_SUBCOMMAND=count -e QUAKES_COUNT__START=2026-07-01 \
    quakes
13

Passing --config /etc/quakes.yaml after the image name works too, and puts the file above the variables instead. A third option is to bake the file into the image and name it in default_config_files, which makes it the image's defaults rather than the run's.

When the layers stop being obvious, --print_config from part 2 answers the question, and it answers it after the environment has been read:

$ QUAKES_SUBCOMMAND=count QUAKES_MIN_MAGNITUDE=6 quakes --print_config
distance_unit: mi
min_magnitude: 6.0
timeout: 30.0
count:
  start: null
  ...

That is the debugging tool worth knowing about before you need it. "Which of these four things won" is the whole difficulty of layered configuration, and the command prints the answer rather than requiring you to reconstruct it.

Nothing is trusted more for arriving this way

Values from the environment go through the same validation as everything else, which is not the usual behaviour of a hand written os.environ.get, where the string reaches the code as a string and fails later, somewhere less helpful:

$ docker run --rm -e QUAKES_SUBCOMMAND=count -e QUAKES_DISTANCE_UNIT=miles quakes
error: Parser key "distance_unit":
  Expected a typing.Literal['km', 'mi']. Got value: miles
$ echo $?
2

The same Literal that produced the choices in the help in part 1 and the completions in part 3 rejects the value here, and it does so before the client is constructed. In a container that matters more than at a terminal. A typo in a deployment manifest is something you find out about from logs, and the difference between the container exiting immediately with that message and the program failing an hour later inside a request is most of the debugging. A non-zero exit at startup is also what a scheduler understands: the pod fails, it does not sit there serving errors.

Where the environment stops

Three limits, all worth knowing before you build a deployment on this.

A misspelled variable is silence. --min_mag=6 on the command line is an error, because the parser knows the option does not exist. QUAKES_MIN_MAG=6 is not, because a process's environment is full of variables that are none of the program's business and it cannot tell yours from the rest:

$ QUAKES_MIN_MAG=6 quakes --print_config count
distance_unit: mi
min_magnitude: 4.0

The run proceeds with the file's value and no complaint. This is inherent to the mechanism rather than particular to jsonargparse, and --print_config is the check: if the value you set is not in the output, the name is wrong.

An empty variable is a value, not an absence. QUAKES_MIN_MAGNITUDE= sets it to the empty string, which fails to parse as a float:

$ QUAKES_MIN_MAGNITUDE= quakes count
error: Parser key "min_magnitude":
  Expected a <class 'float'>. Got value:

Shell scripts and CI templates produce empty variables easily, from an unset substitution or a job input nobody filled in. Unset the variable rather than blanking it.

A structured value is one variable, not several. --area is the Area dataclass from part 1, and on the command line it takes either a JSON document or its fields as separate options, --area.latitude=35.7. Through the environment only the first of those exists: the help lists QUAKES_SEARCH__AREA and nothing for latitude, so the entire dataclass arrives in one variable.

$ QUAKES_SEARCH__AREA='{"latitude": 35.7, "longitude": 139.7}' quakes search --limit=2
time              magnitude  depth   latitude  longitude  id          place
2026-08-20 05:28  4.3        29.68   36.651    140.6399   us6000tm2a  5 km N of Hitachi, Japan
2026-08-17 07:36  4.6        230.19  34.8761   135.6311   usd0015ecj  3 km NNE of Takatsuki, Japan

It is parsed and checked like every other value — leave out longitude and the run stops at startup saying so, rather than the dataclass being built without it. What does not improve is the writing: a JSON document squeezed into a shell variable is unpleasant to quote and hard to read in a manifest, and it gets worse the deeper the structure goes. Structure belongs in a config file, and QUAKES_CONFIG exists so that a run can point at one. Environment variables are for the handful of scalars that differ between runs.

Leaving it off

default_env=True is a decision, and the opposite one is defensible. It means the program's behaviour depends on variables that a user cannot see in the command they typed, which is a real cost when someone is debugging over a shoulder, and prefixed names collide with nothing but are still a namespace claimed in every shell the command runs in.

If the tool is mostly used interactively, leave the argument out and let whoever needs it turn it on for a single run:

JSONARGPARSE_DEFAULT_ENV=true quakes count

Same mechanism as the JSONARGPARSE_ADD_PRINT_COMPLETION_ARGUMENT in part 3, and the same reasoning: a behaviour the program's author might not want on by default is still available to the person running it, without a fork. Keeping env_prefix set while leaving default_env unset is a reasonable middle, since it fixes the names for whoever does enable it.

One thing this post has not needed is a secret, because the earthquake catalog wants neither a key nor an account, which is why it makes such a convenient example. If it did want one, this is the mechanism it would arrive by, and the reason is the one part 2 gave for the config file: a token in a variable does not go into your shell history and does not get committed. What it does do is stay readable for as long as the container exists:

$ docker inspect --format '{{json .Config.Env}}' "$container"
["QUAKES_MIN_MAGNITUDE=6","QUAKES_SUBCOMMAND=count","PATH=...","LANG=C.UTF-8",...]

Anyone who can talk to the daemon can read that, and the same is true of ps on some systems and of whatever your CI prints when it dumps the environment for a failed job. A file with restrictive permissions, or a secret mounted as one, is still the better place for a long lived credential — QUAKES_CONFIG pointing at a mounted file is exactly that shape. The variable is the better place for a token that lives as long as the process does.

What this leaves you with

The command now takes its settings from a file it finds on its own, a file named by a variable, individual variables, or the command line, and the same class decides what all four of them accept. Adding a parameter to EarthquakeCatalog still adds an option, a config key, a completion and, now, an environment variable, and quakes_client.py still does not import jsonargparse.

That is four posts of the same trade. Everything a command line tool conventionally maintains by hand — the parser, the help, the config schema, the completion script, the environment variable table — is a projection of something already written down in Python. Write it down accurately once, and the copies stop being copies.

Tab completion, without writing a completion script

Mauricio Villegas — Thu, 20 Aug 2026 16:45:24 +0000

The first post derived a whole command line interface from a client class, and the second turned it into a command that runs from any directory. Both left the same gap in place: the tool knows a great deal that its user does not.

order_by is one of four strings. distance_unit is one of two. level is one of five. The client says so in its type hints, and jsonargparse enforces every one of them, to the point of refusing the run when you get it wrong:

$ quakes search --order_by=depth
error: Parser key "order_by":
  Expected a typing.Literal['time', 'time-asc', 'magnitude', 'magnitude-asc']. Got value: depth

Which is correct, and arrives too late to be of much use. The alternatives on offer are to remember the four values or to stop and read quakes search --help. Neither is what you want at forty characters into a command line.

Tab completion is where that knowledge belongs, and there is nothing to invent for it. The parser has the choices. The shell has a mechanism for asking. All that is missing is the translation between the two, and it is one dependency and one line of code away.

The part that is normally the work

A shell completion is a script in the shell's own language, registered against a command name. Writing one by hand is a small, unpleasant project: bash wants a function that fills COMPREPLY, zsh wants _arguments specs in a file whose first line is #compdef, fish wants a pile of complete -c calls, tcsh wants a single complete statement built out of c/, n/ and p/ patterns. Four dialects, none of which resemble the others.

Worse than writing them once is keeping them. The completion script is a copy of the interface expressed somewhere else, and it goes stale the moment you add an option and forget. Plenty of tools ship a completion that is a version or two behind what the tool accepts.

None of that is necessary when the parser can be inspected. shtab walks an argparse parser and writes the script for you, and jsonargparse hands it a parser that already knows the choices, the paths and the types, because those came out of the client's signatures. So the completion ends up derived from the same source as everything else in this series.

One extra, one line

shtab is an optional dependency of jsonargparse, declared as the shtab extra. In pyproject.toml it goes next to the extra that was already there:

dependencies = [
    "jsonargparse[signatures,shtab]>=4.51.0",
]

pip install -e .

Installing shtab is enough for the machinery to exist, but not for the command to expose it. The argument that prints the script is opt-in, because not every program wants an extra option in its help. Turning it on is a module level call in quakes_cli.py, next to the register_type from part 1:

from jsonargparse import auto_cli, set_parsing_settings

# Add --print_completion, which writes the shell completion script for the CLI.
set_parsing_settings(add_print_completion_argument=True)

set_parsing_settings is jsonargparse's dial for behaviours that apply to every parser in the process rather than to one argument. There is now one more option in the help:

$ quakes --help
options:
  -h, --help            Show this help message and exit.
  --config CONFIG       Path to a configuration file.
  --print_config [=flags]
                        Print the configuration after applying all other
                        arguments and exit. ...
  --print_completion {shtab-bash,shtab-zsh,shtab-tcsh,shtab-fish}
                        Print shell completion script.

Note what did not happen. quakes_client.py was not touched, no argument was annotated with a completer, and nothing anywhere said that order_by has four values. That was said once, in the client's signature, and this is the third thing generated from it after the parser and the help.

If the tool is not yours to edit, the same argument can be added from outside with an environment variable:

JSONARGPARSE_ADD_PRINT_COMPLETION_ARGUMENT=true some-other-tool --print_completion=shtab-bash

Trying it in bash

--print_completion writes a script to standard output and exits. To try it in the shell you are sitting in, run it and evaluate the result:

eval "$(quakes --print_completion shtab-bash)"

That lasts until the shell closes, which is what you want while deciding whether any of this is worth keeping. Subcommands complete:

$ quakes <TAB><TAB>
count    event    feed     search   summary
$ quakes su<TAB>
$ quakes summary

A single dash is enough to ask for options, and which options you are offered depends on where you are. Before a subcommand, the ones that configure the client, which is exactly the set that part 1 got out of __init__:

$ quakes -<TAB><TAB>
--config         --help           --print_config   -h
--distance_unit  --min_magnitude  --timeout

After a subcommand, that subcommand's own, which is the set that came out of the method. --order_by and --limit belong to search and are not offered under count:

$ quakes search --<TAB><TAB>
--area            --area.longitude  --end             --max_magnitude   --print_config
--area.help       --area.radius     --help            --min_magnitude   --start
--area.latitude   --config          --limit           --order_by

$ quakes count --<TAB><TAB>
--area            --area.longitude  --end             --min_magnitude
--area.help       --area.radius     --help            --print_config
--area.latitude   --config          --max_magnitude   --start

That split is not something shtab was told about. It falls out of the parser having a subparser per method, which fell out of the client having a method per subcommand.

And values complete, which is the part that pays for the exercise:

$ quakes search --order_by <TAB><TAB>
Expected type: Literal['time', 'time-asc', 'magnitude', 'magnitude-asc']; 4/4 matched choices
magnitude      magnitude-asc  time           time-asc
$ quakes search --order_by m<TAB>
$ quakes search --order_by magnitude

The line above the choices is jsonargparse rather than shtab, and it is the reason a generated completion can end up better than a hand written one. Pressing tab twice asks the shell to list what it has; jsonargparse takes the chance to also print the declared type and how much of it your prefix still matches, in colour, on standard error, without disturbing the line you are typing. For an argument with choices that is a convenience. For one without, it is the whole answer:

$ quakes search --limit <TAB><TAB>
Expected type: int

$ quakes search --start <TAB><TAB>
Expected type: date | null; 0/1 matched choices

--start is the date that part 1 taught the parser with register_type. There is no list of dates to offer, so the type is what gets shown, and the 1 counts the one value it can complete, the null that the type names.

Arguments whose type is a path complete as paths, because shtab is told so from the type rather than from a hint written by hand. --config is the clearest case, since the client does not declare it at all:

$ quakes --config <TAB><TAB>
config.yaml  config_japan.yaml  data/

The most interesting type in the client goes one level deeper. area is the Area dataclass behind an Area | None hint, and part 1 set its fields from the command line as --area.latitude and friends. Those complete too, dot and all:

$ quakes search --area.<TAB><TAB>
--area.help       --area.latitude   --area.longitude  --area.radius

$ quakes search --area.latitude <TAB><TAB>
Expected type: float

Nothing about the nesting was declared anywhere either. Three annotated fields on the dataclass become three more options on the parser, and three more candidates in the completion, each carrying its own type. --area.help is in that list because it is a real option, the one part 1 used to print the dataclass's own help page.

Making it stick

Typing the eval by hand is fine for an afternoon. The question is where to put it so that it is simply there.

The tempting answer is to generate the script once, save it, and source the file. For a project you are working on, that is the wrong shape. The install is editable; the whole point of it is that the code changes under a command that stays where it is. A completion script written at setup time starts drifting from the interface on the second afternoon, and drifting quietly, which is the failure mode that made hand written completions unpleasant in the first place.

So keep the eval and move it somewhere that runs. In a virtual environment the natural place follows from what a virtual environment is: activating it is the moment quakes appears on the PATH, and that is the moment the shell should learn how to complete it. activate is a plain script that gets sourced, so appending to it is all it takes:

cat >> "$VIRTUAL_ENV/bin/activate" <<'EOF'

# Shell completion for the quakes command.
eval "$(quakes --print_completion shtab-bash)"
EOF

From then on the completion is regenerated from the current code every time you activate, and there is nothing to keep in sync:

$ source venv/bin/activate
(venv) $ quakes search --order_by <TAB><TAB>
Expected type: Literal['time', 'time-asc', 'magnitude', 'magnitude-asc']; 4/4 matched choices
magnitude      magnitude-asc  time           time-asc

Two things this does not do. deactivate does not undo it, so the completion stays registered for the rest of the session; harmless, since it only fires for a command that is no longer on the PATH. And python -m venv writes activate fresh, so recreating the environment loses the appended block. Worth keeping the cat >> above in a script you rerun rather than in your shell history.

For a tool you installed rather than one you are writing, the same line goes in ~/.bashrc instead, and the reasoning is unchanged: the completion is generated from whatever version is installed today.

Or a file, when the startup cost matters

There is a cost to the above, and it is the one thing a saved script buys back. Every eval starts a Python interpreter, imports jsonargparse, builds the parser out of the client's signatures and walks it. Here that is about a quarter of a second:

$ time quakes --print_completion shtab-bash > /dev/null
real    0m0.276s
user    0m0.223s
sys 0m0.042s

Once per source venv/bin/activate is nothing. Once per terminal you open is noticeable, and it is not once: put four tools in your ~/.bashrc this way and you have added a second to every shell. That is the point at which to generate the file instead and let the shell load it, which is also the right thing for a tool other people install, since they gain nothing from paying for a generation step on a program that only changes when they upgrade it.

Each shell has a directory for exactly this. bash looks in /etc/bash_completion.d/ and, with the bash-completion package, in ~/.local/share/bash-completion/completions/, under the command's name:

quakes --print_completion shtab-bash > ~/.local/share/bash-completion/completions/quakes

zsh loads from any directory on $fpath, from a file named _quakes whose first line is #compdef quakes, which is what shtab writes:

quakes --print_completion shtab-zsh > /usr/local/share/zsh/site-functions/_quakes

fish reads ~/.config/fish/completions/quakes.fish, and needs no configuration line anywhere:

quakes --print_completion shtab-fish > ~/.config/fish/completions/quakes.fish

tcsh has no such directory; the file goes wherever you like and ~/.tcshrc sources it.

The trade is the obvious one. Nothing is generated at startup, and nothing notices when the interface changes, so the generation has to happen somewhere else: an installer step, a make target, whatever the project already runs. That is the same discipline a hand written completion needs, minus the writing.

One detail to watch either way. The script registers itself against the program name the parser saw, so running python quakes_cli.py --print_completion shtab-bash ends the script with complete -o filenames -F _shtab_quakes_cli_py quakes_cli.py, which completes a file path rather than a command. Generate from the installed command, so that the name in the script is the name people type.

The other three shells

Everything above is shtab-bash. The other values of --print_completion produce scripts in the other shells' languages, out of the same parser, and the differences between them are the shells' own.

A caveat before the details: bash is the shell I actually use. Everything below was run and its output is real, but it was run by someone who had to look up the syntax first, so take the surrounding judgements as a starting point rather than as advice from a native. If your shell is one of these three and something here is not how it is done, you are right and I am not.

zsh gives the most back. It shows the help text next to each candidate, because the parser had it and zsh has somewhere to put it:

% quakes <TAB>
count    -- Count the events matching the given criteria, without fetching them.
event    -- Get everything the catalog knows about a single event.
feed     -- Get one of the real time feeds of recent events.
search   -- Search the catalog for events matching the given criteria.
summary  -- Summarize the seismic activity of a period as aggregated statistics.

Those sentences are the first lines of the docstrings in the client, which have now been through the help, the completion and nowhere else. Options are scoped to the subcommand as they are in bash, and values complete the same way, without the type guidance, which is a bash-only addition.

The one wrinkle is that zsh does not register a completion by being told the function exists. Its convention is the #compdef file on $fpath from the previous section, read by compinit at startup; anything arriving later has to be attached by hand. So the eval needs a second line:

eval "$(quakes --print_completion shtab-zsh)"
compdef _shtab_quakes quakes

activate is the same file for bash and zsh, so if you use both, branch on $BASH_VERSION and $ZSH_VERSION:

# Shell completion for the quakes command.
if [ -n "$BASH_VERSION" ]; then
    eval "$(quakes --print_completion shtab-bash)"
elif [ -n "$ZSH_VERSION" ]; then
    eval "$(quakes --print_completion shtab-zsh)"
    compdef _shtab_quakes quakes
fi

fish also shows descriptions, and asks the least of the four:

> quakes <TAB>
count    (Count the events matching the given criteria, without fetching them.)
event    (Get everything the catalog knows about a single event.)
feed     (Get one of the real time feeds of recent events.)
search   (Search the catalog for events matching the given criteria.)
summary  (Summarize the seismic activity of a period as aggregated statistics.)

> quakes search --m<TAB>
--max_magnitude  (Only events at or below this magnitude. (type: float | null,…)
--min_magnitude  (Only events at or above this magnitude. Defaults to the valu…)

fish has no eval, and does not need one: a script can be piped straight into source. That line goes in activate.fish, which is the file fish reads:

# Shell completion for the quakes command.
quakes --print_completion shtab-fish | source

tcsh is the modest one, and the only one where the generated script is worse than the shell can do. Its completions are a single complete statement, and shtab writes it with the options of every subparser merged into one list, so --level, which belongs to feed alone, is offered everywhere:

> quakes <TAB>
count   event   feed    search  summary
> quakes search --order_by <TAB>
magnitude     magnitude-asc time          time-asc
> quakes count --level <TAB>
1.0         2.5         4.5         all         significant

That flattening is shtab's, not tcsh's. tcsh completions can run a command to produce their candidates, and that command can look at $COMMAND_LINE and answer differently depending on the subcommand already typed; shtab uses exactly this technique for positional arguments and simply does not for options. It is also worth knowing that a single dash offers - and h rather than the long options, so -- is what you want to type before pressing tab. Both are fixable in shtab rather than facts about the shell.

For the rest, tcsh does what the others do. The only awkwardness is getting the script in without a file: csh's backticks flatten the multi-line complete statement, so the comment lines and the line continuations have to go before eval sees it. In activate.csh:

# Shell completion for the quakes command.
eval `quakes --print_completion shtab-tcsh | grep -v '^#' | tr -d '\\'`

Which is a coincidence worth pointing out. python -m venv writes activate, activate.csh and activate.fish; shtab writes bash, zsh, tcsh and fish. The shells Python thinks are worth an activation script are the shells shtab can complete.

The one thing to remember

Whatever you do with it, the script is a snapshot. It is written from the parser at the moment --print_completion ran, and it does not change afterwards. Add a parameter to EarthquakeCatalog and the CLI grows an option immediately, because the class is read on every run, while a completion generated yesterday keeps offering yesterday's list.

Which is why the shape of the question is when do I regenerate, not where do I keep the file. Every activation, and you never think about it again for the price of a quarter of a second. Every install, and it is correct for as long as the version is. Once, by hand, in a terminal you have since closed, and it will be wrong and you will not be told.

What this leaves you with

Three posts in, the client class has produced the argument parser, the help, the keys a config file may set and now the completions for four shells, and it still does not import jsonargparse. The pattern is the same every time: write the interface honestly in Python, and the things that are usually hand maintained copies of it stop being copies.

Completion is the clearest case of it, because a hand written one is so plainly a duplicate of something you already wrote down. Whatever library you use, if it can walk your parser, generating the script is worth the afternoon you would otherwise spend writing one that is wrong by next month.

A CLI that works from anywhere

Mauricio Villegas — Mon, 10 Aug 2026 05:12:02 +0000

The previous post turned a client class into a command line tool with a single call to auto_cli. It ended with a file you run like this:

python quakes_cli.py search --min_magnitude=5

That is fine while you are the only user and the terminal happens to be open in the right directory. It stops being fine as soon as it is not: the path has to be spelled out in full, quakes_client.py has to be next to it so the import works, and jsonargparse has to be installed in whichever Python python means today. A cron job or a colleague will run into all three.

What you want instead is a command:

$ cd ~
$ quakes count --start=2026-07-01 --min_magnitude=5
243

Available from any directory, with its dependencies installed along with it, and no mention of Python anywhere in the invocation. That takes one new file, pyproject.toml, and a small change to the code that already exists.

The CLI needs a function

An installed command is a small script that the packaging tool generates and puts on your PATH. All it does is import something from your code and call it. So there has to be something to call, and a body sitting inside if __name__ == "__main__" is not it: that block runs when the file is executed as a script, and is skipped when the file is imported — and importing is exactly what the generated script does.

So the tail of quakes_cli.py goes from this:

if __name__ == "__main__":
    try:
        print(render(auto_cli(EarthquakeCatalog)))
    except CatalogError as ex:
        sys.exit(f"error: {ex}")

to this:

def main() -> None:
    """Run the command line interface."""
    try:
        print(render(auto_cli(EarthquakeCatalog)))
    except CatalogError as ex:
        sys.exit(f"error: {ex}")


if __name__ == "__main__":
    main()

The body did not change, only where it lives. The if __name__ block stays, now one line long. Keeping it costs nothing, means the file is still runnable directly while developing, and keeps every command in the first post working as it was written.

The same applies to your own tools, whether or not you ever package them. Whatever is inside if __name__ == "__main__" should be one call to a function that lives just above it.

pyproject.toml

One file declares what the project is, what it needs, and what it installs:

[build-system]
requires = ["setuptools>=77.0"]
build-backend = "setuptools.build_meta"

[project]
name = "quakes-cli"
version = "0.1.0"
description = "Command line client for the earthquake catalog of the U.S. Geological Survey."
requires-python = ">=3.10"
dependencies = [
    "jsonargparse[signatures]>=4.50.0",
]

[project.scripts]
quakes = "quakes_cli:main"

[tool.setuptools]
py-modules = ["quakes_cli", "quakes_client"]

That is the whole of it, minus the metadata that every published project also wants and that changes nothing in how any of this works: the readme, the license, the authors, the URLs. The file in the repository has those as well.

[build-system] names the tool that turns this directory into something installable. Setuptools is the default choice and the one most people already have; hatchling, flit and pdm are equally valid and differ mostly in the last section of this file.

[project] is the metadata, standardised in PEP 621 and identical whichever build backend you picked. The two lines doing real work are dependencies and requires-python. The former replaces requirements.txt, which the repository no longer has: what a package needs belongs in the package's own metadata, so that installing the package installs its dependencies too, in a fresh environment, on a machine that never saw this repository. The latter is what stops pip from installing this on Python 3.9, where the float | None hints that the client is written with fail on import.

[project.scripts] is the point of the exercise:

quakes = "quakes_cli:main"

On the left, the name the command has in a terminal. On the right, the function it calls, as module:function. The two are independent, so the command does not have to be named after the module, and one project can declare several commands pointing at different functions. This is also where the main of the previous section earns its existence.

[tool.setuptools] is the one backend-specific part. This project is two files at the root of the repository rather than a package directory, so they are declared as py-modules. That is unusual enough to explain: most projects put their code in a package, both to claim a single name in site-packages and to have somewhere to grow. Here, quakes_cli and quakes_client are specific enough not to collide with anything else installed, and leaving them where the first post put them keeps its snippets running. Adding a third module would be the moment to reconsider.

Three names show up in that file, which is a common source of confusion. quakes-cli is the distribution name, the one used to install and the one that has to be unique on PyPI. quakes_cli is the module. quakes is the command. They are allowed to differ, and often have to.

Installing it

While working on the project, install it in editable mode:

$ pip install -e .
Building wheels for collected packages: quakes-cli
  Building editable for quakes-cli (pyproject.toml): finished with status 'done'
Successfully built quakes-cli
Installing collected packages: quakes-cli
Successfully installed quakes-cli-0.1.0

The sources stay where they are and the environment points at them, so an edit takes effect on the next run with nothing to reinstall. Drop the -e and it copies instead, which is what you want when checking that the install itself is correct.

Either way there is now a quakes on the PATH, and it behaves like any other command:

$ cd ~
$ quakes --help
usage: quakes [--config CONFIG] [--distance_unit {km,mi}]
              [--min_magnitude MIN_MAGNITUDE] [--timeout TIMEOUT]
              {count,event,feed,search,summary} ...

Note the usage line. It said quakes_cli.py before and says quakes now, and nothing was configured to make that happen: argparse takes the program name from how the program was invoked, so the help follows the command around.

For people who only want to use the tool, pipx install . or uv tool install . are the friendlier form; once the project is published somewhere, the dot becomes the distribution name. Both put the command on the PATH and keep its dependencies in an environment of their own, so a CLI never has to share an environment with anything else.

Settings that follow the command

Something did not survive the move. The first post ended with the client's settings in a config file:

quakes --config config.yaml search --start=2026-07-01

That path is resolved relative to the directory you are standing in, which used to be the repository and can now be anywhere. A command that runs from everywhere, but whose settings only work in one directory, is not much of an improvement.

The fix is one argument. Anything auto_cli does not recognise is handed to the parser, and the parser accepts a list of places to read configuration from on every run, without --config having to point at them:

auto_cli(
    EarthquakeCatalog,
    default_config_files=["~/.config/quakes.yaml"],
)

Write the settings there once:

# ~/.config/quakes.yaml
distance_unit: mi
min_magnitude: 4.0

and they apply from every directory, with nothing on the command line:

$ cd ~
$ quakes count --start=2026-08-01
113

The file gives defaults, not final values, so --config still overrides it, and a command line argument overrides both:

$ quakes --min_magnitude=6 count --start=2026-08-01
2

The help says what is going on, at the top and in the defaults of every option the file touched:

$ quakes --help
usage: quakes [--config CONFIG] [--distance_unit {km,mi}]
              [--min_magnitude MIN_MAGNITUDE] [--timeout TIMEOUT]
              {count,event,feed,search,summary} ...

default config file locations:
  ['~/.config/quakes.yaml'], Note: default values below are the ones
  overridden by the contents of: ~/.config/quakes.yaml
...
  --distance_unit {km,mi}
                        Unit used for all distances, both given and returned.
                        (type: Literal['km', 'mi'], default: mi)

default: mi is not what the client's signature says, because the file said otherwise. --help reports what a run would actually use, not what the code was written with.

The entries are glob patterns and more than one is allowed, with later files winning over earlier ones. So the layering that well behaved command line tools tend to have costs one keyword argument:

default_config_files=["/etc/quakes.yaml", "~/.config/quakes.yaml", "quakes.yaml"]

A system wide file, then the user's, then one for the project you happen to be standing in. That first path is the Unix convention and has no Windows equivalent. ~/.config does work on Windows, but no user there expects to find settings in it; if you would rather use each operating system's native location, platformdirs computes it, and default_config_files takes Path objects as readily as strings.

What this leaves you with

The tool is now something that can be installed rather than a file that can be run. It declares its own dependencies, refuses to install where it would not work, gives its user a command instead of a path, carries its settings around, and can be built into a wheel and put on PyPI or an internal index with python -m build and twine upload.

The part that carries beyond this project is the smallest one. An entry point needs a function, so write the function and let if __name__ == "__main__" do nothing but call it.

From API client to CLI, without writing a parser

Mauricio Villegas — Mon, 03 Aug 2026 04:22:59 +0000

At some point most of us write a class that wraps an HTTP API. The constructor takes the things that do not change between calls: the base URL, the credentials, the timeout, a few defaults. The methods are the endpoints.

Then comes the day you want to call it from a terminal. To check one thing quickly, to put it in a cron job, or to hand it to a colleague who does not write Python. The usual answer is an argparse layer that spells out every parameter a third time, after the signature and after the docstring. It is tedious to write, and it goes stale the moment someone adds a parameter to the client and forgets the CLI.

jsonargparse can derive that layer from the class itself. The signature already says what the parameters are and what types they take. The docstring already says what they mean. That is all a command line parser needs to know, so auto_cli reads it from there:

auto_cli(EarthquakeCatalog)

This post builds such a client from scratch, a few lines at a time, and every snippet runs as it is written. The API is the USGS Earthquake Catalog, the service of the U.S. Geological Survey that publishes every seismic event recorded around the world, updated every minute. It needs no key, no account and no registration, so you can paste the code and get real data back. The catalog is live, so the numbers you get will not be exactly the ones shown here.

If you already have a client class of your own, it will probably need no change at all beyond making sure its type hints and docstrings are complete. Feel free to read the snippets below as a description of what your own class would do.

You will need Python 3.10 or later and:

pip install "jsonargparse[signatures]"

A client small enough to paste

Here is the whole first version. One constructor, one method, and a small private helper that performs the request:

import json
from datetime import datetime, timedelta, timezone
from urllib.parse import urlencode
from urllib.request import urlopen


def since(days: int) -> str:
    return (datetime.now(timezone.utc) - timedelta(days=days)).isoformat()


class EarthquakeCatalog:
    """Client for the earthquake catalog of the U.S. Geological Survey."""

    def __init__(self, min_magnitude: float = 2.5, timeout: float = 30.0):
        """
        Args:
            min_magnitude: Magnitude below which events are ignored by default.
            timeout: Seconds to wait for a response before giving up.
        """
        self.min_magnitude = min_magnitude
        self.timeout = timeout

    def count(self, days: int = 30, min_magnitude: float | None = None) -> int:
        """Count the events recorded over the last few days.

        Args:
            days: How far back to look.
            min_magnitude: Only events at or above this magnitude. Defaults to
                the value given to the client.

        Returns:
            The number of matching events.
        """
        data = self._get(
            "/fdsnws/event/1/count",
            starttime=since(days),
            minmagnitude=self.min_magnitude if min_magnitude is None else min_magnitude,
        )
        return data["count"]

    def _get(self, path: str, **params) -> dict:
        url = f"https://earthquake.usgs.gov{path}?{urlencode({'format': 'geojson', **params})}"
        with urlopen(url, timeout=self.timeout) as response:
            return json.loads(response.read())


if __name__ == "__main__":
    from jsonargparse import auto_cli

    print(auto_cli(EarthquakeCatalog))

Nothing in the class knows about command lines. The last three lines are the entire interface. Save it as quakes.py and ask it for help:

$ python quakes.py --help
usage: quakes.py [--config CONFIG] [--min_magnitude MIN_MAGNITUDE]
                 [--timeout TIMEOUT]
                 {count} ...

Client for the earthquake catalog of the U.S. Geological Survey:
  --min_magnitude MIN_MAGNITUDE
                        Magnitude below which events are ignored by default.
                        (type: float, default: 2.5)
  --timeout TIMEOUT     Seconds to wait for a response before giving up.
                        (type: float, default: 30.0)

  Available subcommands:
                        (required)
    count               Count the events recorded over the last few days.

The shape of the class is the shape of the command line. Constructor parameters became options that come before the subcommand, public methods became the subcommands, and the class docstring became the description. Ask about the subcommand and the same thing happened one level down:

$ python quakes.py count --help
usage: quakes.py [options] count [--config CONFIG] [--days DAYS]
                                 [--min_magnitude MIN_MAGNITUDE]

Count the events recorded over the last few days.

options:
  --days DAYS           How far back to look. (type: int, default: 30)
  --min_magnitude MIN_MAGNITUDE
                        Only events at or above this magnitude. Defaults to
                        the value given to the client. (type: float | None,
                        default: null)

Every line of help text was written once, in the docstring, where it also serves anyone reading the code or the generated API documentation. The types were written once, in the signature, where they also serve the type checker.

So, how many earthquakes of magnitude 5 or above were there last week?

$ python quakes.py count --days=7 --min_magnitude=5
67

Note that min_magnitude appears in two places, and means something slightly different in each. Before the subcommand it is the client's standing default; after it, the value for this one call. That distinction was expressed only by where the parameter lives in the class, and it survives into the CLI:

$ python quakes.py --min_magnitude=6 count --days=7
1

A second endpoint

Counting is a thin thing to do with a catalog of earthquakes. Let us fetch the events themselves, with a real filter: only those within a given distance of a point on the globe.

That filter has three numbers that belong together, so it deserves a small record of its own. The events coming back deserve one too. Add from dataclasses import dataclass and from typing import Literal to the imports, then these:

@dataclass
class Area:
    """Circular region of the globe to restrict a search to.

    Args:
        latitude: Latitude of the center, in degrees, positive towards north.
        longitude: Longitude of the center, in degrees, positive towards east.
        radius: Radius around the center, in kilometers.
    """

    latitude: float
    longitude: float
    radius: float = 500.0


@dataclass
class Quake:
    """Summary of a single seismic event."""

    time: datetime
    magnitude: float
    depth: float
    latitude: float
    longitude: float
    id: str
    place: str


def to_quake(feature: dict) -> Quake:
    properties = feature["properties"]
    longitude, latitude, depth = feature["geometry"]["coordinates"]
    return Quake(
        time=datetime.fromtimestamp(properties["time"] / 1000, tz=timezone.utc),
        magnitude=properties["mag"],
        depth=depth,
        latitude=latitude,
        longitude=longitude,
        id=feature["id"],
        place=properties["place"],
    )

And the method itself, next to count:

    def search(
        self,
        days: int = 30,
        min_magnitude: float | None = None,
        area: Area | None = None,
        order_by: Literal["time", "time-asc", "magnitude", "magnitude-asc"] = "time",
        limit: int = 10,
    ) -> list[Quake]:
        """Search the catalog for events matching the given criteria.

        Args:
            days: How far back to look.
            min_magnitude: Only events at or above this magnitude. Defaults to
                the value given to the client.
            area: Only events within this region of the globe.
            order_by: Order in which the events are returned.
            limit: Maximum number of events to return.

        Returns:
            The matching events, at most ``limit`` of them.
        """
        within = {}
        if area is not None:
            within = {
                "latitude": area.latitude,
                "longitude": area.longitude,
                "maxradiuskm": area.radius,
            }
        data = self._get(
            "/fdsnws/event/1/query",
            starttime=since(days),
            minmagnitude=self.min_magnitude if min_magnitude is None else min_magnitude,
            orderby=order_by,
            limit=limit,
            **within,
        )
        return [to_quake(feature) for feature in data["features"]]

Two of these parameters are more interesting than a number or a string, and the CLI treats both of them accordingly:

$ python quakes.py search --help
usage: quakes.py [options] search [--config CONFIG] [--days DAYS]
                                  [--min_magnitude MIN_MAGNITUDE]
                                  [--area AREA]
                                  [--order_by {time,time-asc,magnitude,magnitude-asc}]
                                  [--limit LIMIT]

options:
  --days DAYS           How far back to look. (type: int, default: 30)
  --min_magnitude MIN_MAGNITUDE
                        Only events at or above this magnitude. Defaults to
                        the value given to the client. (type: float | None,
                        default: null)
  --area.help           Show the help for Area and exit.
  --area AREA           Only events within this region of the globe. (type:
                        Area | None, default: null)
  --order_by {time,time-asc,magnitude,magnitude-asc}
                        Order in which the events are returned. (type:
                        Literal['time', 'time-asc', 'magnitude', 'magnitude-
                        asc'], default: time)
  --limit LIMIT         Maximum number of events to return. (type: int,
                        default: 10)

order_by is a Literal, so its four values became the accepted choices. Anything else is rejected with the list of what is allowed, before a request is made.

area is a whole object, so it got a help page of its own, built from the dataclass the same way the main help was built from the client:

$ python quakes.py search --area.help
usage: quakes.py --area.latitude LATITUDE --area.longitude LONGITUDE
                 [--area.radius RADIUS]

Circular region of the globe to restrict a search to:
  --area.latitude LATITUDE
                        Latitude of the center, in degrees, positive towards
                        north. (required, type: float)
  --area.longitude LONGITUDE
                        Longitude of the center, in degrees, positive towards
                        east. (required, type: float)
  --area.radius RADIUS  Radius around the center, in kilometers. (type: float,
                        default: 500.0)

Its fields are set individually, with a dot:

python quakes.py search --area.latitude=35.68 --area.longitude=139.69 --area.radius=300 \
                    --min_magnitude=5 --days=365 --order_by=magnitude --limit=3

Nothing had to be registered or declared for that to work. The parameter is typed Area | None, and Area is an ordinary dataclass, which is enough.

Printing what comes back

The command above does work, but what it prints is not pleasant:

[Quake(time=datetime.datetime(2025, 10, 4, 15, 21, 10, 42000, tzinfo=datetime.timezone.utc), magnitude=5.9, depth=54.164, latitude=37.4213, longitude=141.5524, id='us6000resn', place='48 km ENE of Tomioka, Japan'), Quake(time=datetime.datetime(2026, 6, 26, 3, 46, 35, 798000, ...

auto_cli deliberately does not print anything itself. It returns whatever the method returned and lets you decide, which is the one place where a command line tool does need code of its own. The methods have return type hints, so the decision can be made once, for all of them:

def render(result) -> str:
    """Render a value returned by a client method as text for a terminal."""
    if isinstance(result, (str, int, float)):
        return str(result)
    if isinstance(result, list) and result and is_dataclass(result[0]):
        return render_table(result)
    return json.dumps(result, indent=2, ensure_ascii=False, default=str)


def render_table(records: list) -> str:
    """Render a list of dataclass instances as a table with aligned columns."""
    columns = [field.name for field in fields(records[0])]
    rows = [columns] + [[cell(getattr(record, column)) for column in columns] for record in records]
    widths = [max(len(row[index]) for row in rows) for index in range(len(columns))]
    return "\n".join("  ".join(value.ljust(width) for value, width in zip(row, widths)).rstrip() for row in rows)


def cell(value) -> str:
    return value.strftime("%Y-%m-%d %H:%M") if isinstance(value, datetime) else str(value)

Import fields and is_dataclass from dataclasses alongside dataclass, and wrap the call:

if __name__ == "__main__":
    from jsonargparse import auto_cli

    print(render(auto_cli(EarthquakeCatalog)))

A list of records is a table whose columns are the fields of the record:

$ python quakes.py search --area.latitude=35.68 --area.longitude=139.69 --area.radius=300 \
                      --min_magnitude=5 --days=365 --order_by=magnitude --limit=3
time              magnitude  depth   latitude  longitude  id          place
2025-10-04 15:21  5.9        54.164  37.4213   141.5524   us6000resn  48 km ENE of Tomioka, Japan
2026-06-26 03:46  5.8        43      35.6907   140.5771   us6000t8cy  2 km ESE of Yōkaichiba, Japan
2026-06-16 10:46  5.3        63.617  36.1715   139.6995   us7000std7  2 km SW of Koga, Japan

A number is still just a number, undecorated rather than quoted or wrapped in JSON:

$ python quakes.py count --days=7 --min_magnitude=5
67

Anything else falls through to indented JSON. Adding a method that returns a dict needs no new printing code, which is the point of dispatching on the type rather than on the subcommand.

The rest of the client

The complete version of this client lives in this repository, split into quakes_client.py for the client and quakes_cli.py for the interface. It is about three hundred lines across the two files, most of them docstrings. Beyond what is above it has:

event(event_id), the full record of one event, returned as the dict the catalog itself provides.
feed(level, period), the USGS real time feeds, which are precomputed and so the fastest way to see what is happening right now.
summary(start, end, area), aggregated statistics that the client computes out of several requests.
Real start and end dates instead of a days count.
A distance_unit on the client that converts both the radius you give and the depths you get back.
Errors from the API turned into one readable line.

Its help is the same shape as the small one, just longer:

$ python quakes_cli.py --help
usage: quakes_cli.py [--config CONFIG] [--distance_unit {km,mi}]
                     [--min_magnitude MIN_MAGNITUDE] [--timeout TIMEOUT]
                     {count,event,feed,search,summary} ...

Client for the earthquake catalog of the U.S. Geological Survey:
  --distance_unit {km,mi}
                        Unit used for all distances, both given and returned.
                        (type: Literal['km', 'mi'], default: km)
  --min_magnitude MIN_MAGNITUDE
                        Magnitude below which events are ignored by default.
                        (type: float, default: 2.5)
  --timeout TIMEOUT     Seconds to wait for a response before giving up.
                        (type: float, default: 30.0)

  Available subcommands:
    count               Count the events matching the given criteria, without
                        fetching them.
    event               Get everything the catalog knows about a single event.
    feed                Get one of the real time feeds of recent events.
    search              Search the catalog for events matching the given
                        criteria.
    summary             Summarize the seismic activity of a period as
                        aggregated statistics.

event takes an event_id with no default, so jsonargparse made it a positional argument rather than an option. If you would rather keep every parameter as a named option, pass as_positional=False to auto_cli.

$ python quakes_cli.py event us7000srb1
{
  "id": "us7000srb1",
  "mag": 7.8,
  "place": "25 km SW of Kablalan, Philippines",
  "time": 1780875461970,
  "updated": 1785641718662,
  "tz": null,
  "url": "https://earthquake.usgs.gov/earthquakes/eventpage/us7000srb1",
  "felt": 581,
  "cdi": 9.1,
  "mmi": 8.53,
  "alert": "orange",
  "status": "reviewed",
  "tsunami": 0,
  "sig": 1529,
  "net": "us",
  "code": "7000srb1",
  "ids": ",us7000srb1,usauto7000srb1,",
  "sources": ",us,usauto,",
  "types": ",dyfi,finite-fault,general-text,ground-failure,impact-text,internal-moment-tensor,losspager,moment-tensor,origin,phase-data,shakemap,",
  "nst": 150,
  "dmin": 1.55,
  "rms": 0.5,
  "gap": 21,
  "magType": "mww",
  "type": "earthquake",
  "title": "M 7.8 - 25 km SW of Kablalan, Philippines"
}

That was the strongest of 2026 at the time of writing. summary returns a dict too, and prints the same way without a single line of code added for it:

$ python quakes_cli.py summary --start=2026-07-01 --end=2026-08-01
{
  "start": "2026-07-01",
  "end": "2026-08-01",
  "total": 3379,
  "by_magnitude": {
    "minor 2.0-3.9": 2240,
    "light 4.0-4.9": 919,
    "moderate 5.0-5.9": 209,
    "strong 6.0-6.9": 10,
    "major 7.0+": 1
  },
  "strongest": {
    "time": "2026-07-17 14:48:40.227000+00:00",
    "magnitude": 7.3,
    "depth": 22,
    "latitude": 14.6361,
    "longitude": -92.8969,
    "id": "us7000t1bu",
    "place": "52 km W of Puerto Madero, Mexico"
  }
}

The full client also uses datetime.date for start and end, which is a type jsonargparse does not handle out of the box. Rather than weakening the client's type hints to str, the CLI teaches the parser how to read and write that type, once:

register_type(date, serializer=date.isoformat, deserializer=date.fromisoformat)

From then on --start=2026-07-01 arrives at the client as a date, and a malformed one is rejected by the parser instead of by the API.

The settings you do not want to retype

The client parameters are the ones you would get tired of typing: the endpoint, the timeout, the credentials. Every tool built with auto_cli accepts a --config file, so they can be written down once:

# config.yaml
distance_unit: mi
min_magnitude: 4.0
timeout: 60.0

python quakes_cli.py --config config.yaml search --start=2026-07-01 --order_by=magnitude --limit=3

time              magnitude  depth  latitude  longitude  id          place
2026-07-17 14:48  7.3        13.67  14.6361   -92.8969   us7000t1bu  52 km W of Puerto Madero, Mexico
2026-07-28 07:27  6.8        6.21   32.6817   130.7217   us6000tgb9  2026 Uto, Japan Earthquake
2026-07-17 15:20  6.4        6.21   14.216    -93.2025   us7000t1cc  101 km WSW of Puerto Madero, Mexico

For an API that needs authentication this is the natural home for the token or the user name, in a file you can keep out of version control and give restrictive permissions, rather than in your shell history.

A config file can also cover a subcommand, by nesting its options under the subcommand's name:

# config_japan.yaml
min_magnitude: 4.0

search:
  start: 2026-01-01
  order_by: magnitude
  limit: 5
  area:
    latitude: 36.2
    longitude: 138.25
    radius: 700

When it does, the subcommand does not have to be named on the command line either. The file is the whole invocation:

$ python quakes_cli.py --config config_japan.yaml
time              magnitude  depth  latitude  longitude  id          place
2026-04-20 07:52  7.4        25     39.971    143.0592   us6000sri7  102 km ENE of Miyako, Japan
2026-06-24 22:30  6.9        34     40.2745   142.1353   us6000t7zq  32 km ENE of Kuji, Japan
2026-05-15 11:22  6.7        42     38.9352   142.1579   us6000sxwq  41 km ESE of Ōfunato, Japan
2026-03-26 14:18  6.5        16     39.4377   143.3826   us7000s7u4  123 km E of Yamada, Japan
2026-07-01 12:08  6          35     40.2085   142.4411   us6000t9ej  54 km ENE of Noda, Japan

Arguments given on the command line still win, so search --limit=2 after that would override the file. And --print_config dumps the settings a run would use, which is the least tedious way to start a new config file:

$ python quakes_cli.py --config config_japan.yaml search --print_config=skip_default
start: '2026-01-01'
area:
  latitude: 36.2
  longitude: 138.25
  radius: 700.0
order_by: magnitude
limit: 5

Bringing your own client

If you already have a client class, the work is mostly checking that it says about itself what it already knows:

Every parameter has a type hint, and the honest one. date rather than str for a date, Literal rather than str for something with four valid values, a small dataclass rather than three loose floats that belong together.
Every parameter is described in the docstring, in a style docstring_parser understands, which covers the Google, Numpy, Sphinx and Epydoc conventions.
Methods you do not want as subcommands start with an underscore.
The constructor takes what does not change between calls. For most real APIs that means the credentials, and a config file already covers them. Passing default_env=True to auto_cli adds an environment variable for each one as well, again without the client having to read either.

Then the whole interface is one call, and it cannot fall out of step with the client, because there is nothing to keep in step.

The client, meanwhile, stays a plain class. It knows nothing about argparse, YAML, config files or terminals, and it is as pleasant to import from a notebook or a web service as it ever was. That is the part worth keeping: the command line tool is a projection of the class, not a second implementation of it.

There is more that jsonargparse can do with the same class, including shell completion, deeper trees of subcommands, and dependency injection through type hints. The documentation has the details.

Disclosure, and the alternatives

I am the author of jsonargparse, so this post is a showcase of its features and you should read it with that in mind. The idea it rests on, that a command line interface can be derived from what the code already declares, is not mine and not exclusive to this package. Several others do a good part of it, and for a given project one of them may fit better. Here is what they do and where they stop, checked against click 8.4, typer 0.27, fire 0.7 and tyro 1.0.

Fire is the closest in spirit. fire.Fire(EarthquakeCatalog) also turns constructor parameters into flags, methods into subcommands and docstrings into help. What it does not do is take the type hints seriously: --days=notanumber arrives at the method as that string, and --area='{"latitude": 1, "longitude": 2}' arrives as a plain dict rather than an Area. There is no config file support. Fire is built to expose arbitrary Python objects, not objects written to be exposed, so it guesses where jsonargparse validates.

Tyro is the closest on types. It builds the parser from hints and docstrings, and its handling of nested structures is excellent: the same area: Area | None becomes a neat pair of area:area and area:none subcommands. It works from a function or a single class, though. tyro.cli(EarthquakeCatalog) gives you the constructor's options and returns an instance; the methods do not become subcommands. There is also no general --config file.yaml, only helpers to serialize dataclasses to and from YAML and to pick among configurations defined in code.

Typer derives options from the hints of functions registered with @app.command(). Literal becomes choices and int is validated, but past the simple types it stops: a dataclass parameter raises RuntimeError: Type not yet supported. Per-parameter help does not come from the docstring either, it is written again inside an Annotated hint with typer.Option(help=...). In exchange you get click underneath, nicely formatted help and shell completion that installs itself with one flag.

Click is the established one and is explicit on purpose. Every option is a decorator, so nothing is inferred: a parameter with only a type hint produces no option at all, and the docstring becomes the description verbatim, Args: section and all. That explicitness is an advantage whenever the command line should not have the same shape as the Python API, and nothing matches click's ecosystem or its control over the terminal. It is a cost when the CLI is meant to be the API, which is the case in this post.

What jsonargparse adds here is the combination: a class with methods becomes a tree of subcommands, arbitrary type hints are validated rather than guessed, and the same tree can be filled from a config file or the environment instead of the command line. And auto_cli is only one way in. Underneath it is an argparse-like interface where you build the parser yourself and add arguments one at a time, or from a function, a class, a method or a bare type hint, wherever you want them, and link one to another. This post shows a small part of what is there.

None of which settles the question. For a tool the size of the one built here any of these packages does the job, and the differences that matter tend to surface later: when the interface grows to cover more of an API, when users start wanting their settings in a file, when the types stop being strings and integers. So the advice is the boring kind. Try a couple of them against the tool you expect to have in a year, rather than the one you are writing this afternoon.