DEV Community: Mauricio Villegas

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.