Skip to content

Usage

There are two moving parts:

  1. annotate your parser with enough metadata for extraction
  2. generate and activate the Bash artifacts

The package does not replace your CLI. It extracts a snapshot from an argparse.ArgumentParser and emits a shell-native completion runtime around it.

Minimal parser

import argparse

from argcomplete_snapshot import CompletionKind, set_completion


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(prog="mycli")
    parser.add_argument("--output", choices=["json", "yaml"])

    region = parser.add_argument("--region")
    set_completion(region, resolver="config_regions")

    target = parser.add_argument("target")
    set_completion(target, kind=CompletionKind.FILE)

    return parser

Generate the cache

acs-refresh refresh \
  --factory mypackage.cli:build_parser \
  --cli-name mycli \
  --distribution mycli \
  --entrypoint mycli

That writes artifacts under:

~/.cache/argcomplete-snapshot/mycli/

acs-refresh print-activation \
  --factory mypackage.cli:build_parser \
  --cli-name mycli \
  --distribution mycli \
  --entrypoint mycli

Source the printed snippet from your shell startup or package-specific completion setup.

Refresh model

At runtime, the generated activation script checks whether:

  • cache files are missing
  • the CLI entrypoint has changed
  • the stored schema or runtime signature is stale

If so, it regenerates the artifacts before delegating to the shell completion function.

  • keep static options, choices, subcommands, and file completion on the Bash hot path
  • use fallback commands only for genuinely dynamic values
  • regenerate artifacts when the CLI shape changes