Skip to content

argcomplete-snapshot

Fast Bash completion artifacts for import-heavy Python CLIs built with argparse and argcomplete.

What it does

argcomplete-snapshot extracts a lightweight completion model from your parser and writes shell-native cache artifacts:

  • snapshot-v1.json
  • completion-v1.bash
  • version-stamp

Steady-state completion stays in Bash. Python runs only when artifacts are missing, the installed CLI changed, or you explicitly route a resolver through a fallback command.

Why it exists

Default argcomplete executes the target Python CLI on every completion request. That means each <TAB> can pay for:

  • Python startup
  • heavy imports
  • parser construction
  • completion logic

That tradeoff is fine for small CLIs. It becomes painful for import-heavy SDK-backed tools.

When to use it

Use argcomplete-snapshot when:

  • your CLI already uses argparse
  • you want faster Bash completions without replacing the parser stack
  • most completions are static or can be represented by a small explicit contract
  • you still want lazy self-refresh after upgrades

Quickstart

Install the package:

pip install argcomplete-snapshot

Build a 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", "text"])

    profile = parser.add_argument("--profile")
    set_completion(profile, resolver="config_profiles")

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

    return parser

Generate the cache artifacts:

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

Print the activation snippet:

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

Docs map

  • Installation covers runtime requirements and local docs commands.
  • Usage covers parser annotation, refresh, and activation.
  • Reference covers the exported Python API and CLI interface.
  • Benchmarks explains the published benchmark numbers and what they mean.