tiny-pki 0.1.0__py3-none-any.whl

tiny_pki/cli/commands.py

@@ -0,0 +1,176 @@
+"""Command table, per-command flags, and help text for the tiny-pki CLI.
+
+``COMMAND_FLAGS`` is the single source for which flags each verb accepts: the
+flag parser, ``help <command>``, the REPL completer, and the bash/zsh/fish
+completion scripts all read it, and ``docs/cli.md`` is tested against it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from tiny_pki.constants import KEY_TYPES
+from tiny_pki.store import CHECK_KINDS
+
+
+@dataclass(frozen=True)
+class Flag:
+    """One ``--name`` option of a command.
+
+    ``value`` is the placeholder shown in help (``None`` for a switch that takes
+    no value). ``choices`` lists the accepted values for completion, ``path``
+    marks values that name a file, ``repeatable`` flags accumulate, and
+    ``allow_empty`` lets ``--name`` without a value fall back to the default.
+    """
+
+    name: str
+    help: str
+    value: str | None = None
+    choices: tuple[str, ...] = ()
+    path: bool = False
+    repeatable: bool = False
+    allow_empty: bool = False
+
+    @property
+    def option(self) -> str:
+        return f"--{self.name}"
+
+
+_DAYS = Flag("days", "validity in days (default 397 for clients, 90 for servers)", value="N", allow_empty=True)
+_KEY_SIZE = Flag(
+    "key-size",
+    "RSA key size in bits (default 4096 for the CA, 3072 for leaves)",
+    value="BITS",
+    choices=("2048", "3072", "4096"),
+)
+_KEY_TYPE = Flag("key-type", "key algorithm (default rsa)", value="TYPE", choices=KEY_TYPES, allow_empty=True)
+_ORG = Flag("org", "organization (O) in the subject", value="NAME", allow_empty=True)
+_DRY_RUN = Flag("dry-run", "show what would change and write nothing")
+_JSON = Flag("json", "machine-readable JSON output")
+_PASSWORD_FILE = Flag("password-file", "read the PKCS#12 password from this file", value="PATH", path=True)
+
+COMMAND_FLAGS: dict[str, tuple[Flag, ...]] = {
+    "check": (
+        Flag("by", "alert on anything expiring by this date", value="YYYY-MM-DD"),
+        Flag("ca", "CA certificate to verify file targets against", value="PATH", path=True),
+        Flag("crl", "CRL to check file targets against", value="PATH", path=True),
+        Flag("include-revoked", "also report revoked store entries"),
+        _JSON,
+        Flag(
+            "kind",
+            "only check this kind (repeatable)",
+            value="KIND",
+            choices=tuple(sorted(CHECK_KINDS)),
+            repeatable=True,
+        ),
+        _PASSWORD_FILE,
+        Flag("quiet", "print only rows that need attention"),
+        Flag("within", "alert window in days (default: a third of each lifetime)", value="DAYS"),
+    ),
+    "create": (
+        Flag("allow-dn-special-chars", 'allow , + = " < > ; or a leading # in the CN'),
+        Flag("allow-long-validity", "allow validity beyond the 200 / 825 day caps"),
+        _DAYS,
+        Flag("keep-previous", "client only: keep the previous certificate live for rotation"),
+        _KEY_SIZE,
+        _KEY_TYPE,
+        Flag("no-cn-san", "server only: do not add the CN to the SANs"),
+        _ORG,
+        Flag("san", "server only: DNS name or IP address (repeatable)", value="NAME", repeatable=True),
+        Flag("yes", "server only: add the CN to the SANs without asking"),
+    ),
+    "crl": (Flag("days", "change the stored CRL lifetime (1-365)", value="N"),),
+    "delete": (Flag("force", "revoke an active certificate first"), _DRY_RUN),
+    "export": (
+        Flag("legacy", "p12 only: 3DES / SHA-1 encryption for old Android and Apple keychains"),
+        Flag("out", "output file", value="PATH", path=True),
+        _PASSWORD_FILE,
+    ),
+    "init": (
+        Flag("cn", 'CA common name (default "Private CA")', value="NAME", allow_empty=True),
+        Flag("crl-days", "CRL lifetime in days (1-365, default 30)", value="N"),
+        Flag("days", "CA validity in days (default 3650)", value="N", allow_empty=True),
+        _KEY_SIZE,
+        _KEY_TYPE,
+        _ORG,
+        Flag("permit", "name constraint: DNS suffix or IP network (repeatable)", value="NAME", repeatable=True),
+    ),
+    "inspect": (),
+    "list": (_JSON,),
+    "revoke": (_DRY_RUN,),
+    "show": (),
+}
+COMMAND_FLAGS["renew-crl"] = COMMAND_FLAGS["crl"]
+COMMAND_FLAGS["completion"] = (
+    Flag("force", "with --install: overwrite a different existing script"),
+    Flag("install", "write the script to the per-user completion directory"),
+    _JSON,
+)
+
+COMMAND_USAGE: dict[str, str] = {
+    "check": "check [PATH...]",
+    "completion": "completion bash|zsh|fish [--install] [--force] [--json]",
+    "create": "create client|server NAME",
+    "crl": "crl",
+    "delete": "delete NAME|0xSERIAL",
+    "edit-mode": "edit-mode [emacs|vim]",
+    "export": "export pem|p12 NAME",
+    "help": "help [COMMAND]",
+    "init": "init",
+    "inspect": "inspect NAME|PATH",
+    "list": "list [ca|certs|clients|servers|revoked]",
+    "renew-crl": "renew-crl",
+    "revoke": "revoke NAME|0xSERIAL",
+    "show": "show ca|certs|crl|NAME",
+}
+
+COMMAND_HELP: tuple[tuple[str, str], ...] = (
+    (
+        "check",
+        "Flag expired, expiring, revoked or untrusted certificates and CRLs in the store or in files.",
+    ),
+    ("clear", "Clear the terminal screen."),
+    ("completion", "Print or install bash/zsh/fish tab-completion scripts."),
+    ("create", "Issue a client or server certificate."),
+    ("crl", "Regenerate the CRL from revoked entries; --days N changes the stored CRL lifetime."),
+    ("delete", "Remove a revoked certificate's files; --force revokes an active one first; --dry-run previews."),
+    ("edit-mode", "Switch Emacs vs Vim keys: edit-mode emacs | vim."),
+    ("exit", "Leave the REPL."),
+    ("export", "Export pem|p12 for an identity."),
+    ("help", "Show this list, or help <command> for its usage and flags."),
+    ("init", "Create a new CA in --store."),
+    ("inspect", "Inspect a store identity or PEM path."),
+    ("list", "List ca|clients|servers|revoked|certs (optional --json)."),
+    ("quit", "Leave the REPL (same as exit)."),
+    ("renew-crl", "Alias for crl."),
+    ("revoke", "Revoke an identity and regenerate the CRL; --dry-run previews."),
+    ("show", "Show ca|certs|crl|<identity> (aliases list categories)."),
+)
+
+COMMANDS: tuple[str, ...] = tuple(sorted({name for name, _ in COMMAND_HELP}))
+
+POSITIONAL_CHOICES: dict[str, tuple[str, ...]] = {
+    "completion": ("bash", "fish", "zsh"),
+    "create": ("client", "server"),
+    "edit-mode": ("emacs", "vim"),
+    "export": ("p12", "pem"),
+    "help": COMMANDS,
+    "list": ("ca", "certs", "clients", "revoked", "servers"),
+    "show": ("ca", "certs", "clients", "crl", "revoked", "servers"),
+}
+
+PKI_COMMANDS: frozenset[str] = frozenset(
+    {
+        "check",
+        "create",
+        "crl",
+        "delete",
+        "export",
+        "init",
+        "inspect",
+        "list",
+        "renew-crl",
+        "revoke",
+        "show",
+    }
+)

tiny_pki/cli/completer.py

@@ -0,0 +1,91 @@
+"""prompt_toolkit completer for the tiny-pki REPL."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+
+from prompt_toolkit.completion import Completer, Completion
+from prompt_toolkit.document import Document
+
+from tiny_pki.cli.commands import COMMAND_FLAGS
+from tiny_pki.cli.theme import Theme
+
+_CMD_THEN_REST = re.compile(r"^(\S+)(\s+)(.*)$", re.DOTALL)
+
+
+@dataclass(frozen=True)
+class CmdCtx:
+    """Completing a command name."""
+
+    partial: str
+
+
+@dataclass(frozen=True)
+class ArgCtx:
+    """Completing arguments for a known command; ``previous`` holds the complete tokens before ``partial``."""
+
+    command: str
+    partial: str
+    previous: tuple[str, ...] = ()
+
+
+def parse_completion_buffer(buf: str) -> CmdCtx | ArgCtx:
+    """Classify the current input buffer for completion."""
+    stripped = buf.lstrip()
+    if not stripped:
+        return CmdCtx(partial="")
+    match = _CMD_THEN_REST.match(stripped)
+    if match is None:
+        return CmdCtx(partial=stripped)
+    command, _ws, rest = match.group(1), match.group(2), match.group(3)
+    tokens = tuple(rest.split())
+    if not rest or stripped[-1:].isspace():
+        return ArgCtx(command=command, partial="", previous=tokens)
+    return ArgCtx(command=command, partial=tokens[-1], previous=tokens[:-1])
+
+
+class ReplCompleter(Completer):
+    """Complete command names, their flags and flag values, and positional argument tokens."""
+
+    def __init__(
+        self,
+        *,
+        commands: Iterable[str],
+        theme: Theme,
+        argument_tokens: Callable[[str], Iterable[str]] | None = None,
+    ) -> None:
+        self._commands = tuple(sorted(commands))
+        self._theme = theme
+
+        def _empty_tokens(_cmd: str) -> tuple[str, ...]:
+            return ()
+
+        self._argument_tokens: Callable[[str], Iterable[str]] = argument_tokens or _empty_tokens
+
+    def get_completions(self, document: Document, complete_event: object) -> Iterable[Completion]:
+        del complete_event
+        ctx = parse_completion_buffer(document.text_before_cursor)
+        if isinstance(ctx, CmdCtx):
+            style = self._theme.completion_command_style()
+            for cmd in self._commands:
+                if cmd.startswith(ctx.partial):
+                    yield Completion(cmd, start_position=-len(ctx.partial), style=style)
+            return
+        style = self._theme.completion_parameter_style()
+        for token in self._candidates(ctx):
+            if token.startswith(ctx.partial):
+                yield Completion(token, start_position=-len(ctx.partial), style=style)
+
+    def _candidates(self, ctx: ArgCtx) -> Iterable[str]:
+        flags = COMMAND_FLAGS.get(ctx.command, ())
+        pending = next((f for f in flags if ctx.previous[-1:] == (f.option,)), None)
+        if pending is not None and pending.value is not None:
+            return pending.choices
+        used = set(ctx.previous)
+        unused = [f.option for f in flags if f.repeatable or f.option not in used]
+        if ctx.partial.startswith("-"):
+            return unused
+        tokens = list(self._argument_tokens(ctx.command))
+        return [*tokens, *unused] if not ctx.partial else tokens

tiny_pki/cli/completion.py

@@ -0,0 +1,368 @@
+"""Shell completion script generation and optional per-user install."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import NoReturn
+
+from tiny_pki.cli.commands import COMMAND_FLAGS, COMMAND_HELP, COMMANDS, POSITIONAL_CHOICES, Flag
+
+_PROG = "tiny-pki"
+_SHELLS = frozenset({"bash", "fish", "zsh"})
+_TOP_FLAGS = (
+    Flag("color", "colour output", value="WHEN", choices=("auto", "always", "never")),
+    Flag("edit-mode", "REPL key bindings", value="MODE", choices=POSITIONAL_CHOICES["edit-mode"]),
+    Flag("help", "show launcher help"),
+    Flag("store", "store directory (or TINY_PKI_STORE)", value="DIR", path=True),
+    Flag("version", "print the version and exit"),
+)
+# Commands whose positional arguments are file paths.
+_PATH_POSITIONALS = frozenset({"check", "inspect"})
+
+
+def completion_install_path(shell: str) -> Path:
+    """Conventional per-user path for a shell's tiny-pki completion script."""
+    xdg_data = _xdg_base("XDG_DATA_HOME", Path.home() / ".local" / "share")
+    if shell == "bash":
+        return xdg_data / "bash-completion" / "completions" / "tiny-pki.bash"
+    if shell == "fish":
+        xdg_config = _xdg_base("XDG_CONFIG_HOME", Path.home() / ".config")
+        return xdg_config / "fish" / "completions" / "tiny-pki.fish"
+    return xdg_data / "zsh" / "site-functions" / "_tiny-pki"
+
+
+def completion_script(shell: str) -> str:
+    """Return a tab-completion script for ``bash``, ``zsh``, or ``fish``."""
+    if shell == "bash":
+        return _bash_script()
+    if shell == "fish":
+        return _fish_script()
+    if shell == "zsh":
+        return _zsh_script()
+    raise ValueError(f"unsupported shell: {shell!r} (expected bash, zsh, or fish)")
+
+
+def run_completion(argv: list[str]) -> int:
+    """Handle ``tiny-pki completion <shell> [--install] [--force] [--json]``.
+
+    Returns 0 on success, 2 on usage errors, 1 on install I/O failures.
+    """
+    try:
+        shell, install, force, as_json = _parse_completion_argv(argv)
+    except SystemExit as exc:
+        code = exc.code
+        return int(code) if isinstance(code, int) else 2
+    if force and not install:
+        _emit_error(
+            message="--force only applies with --install",
+            as_json=as_json,
+            hint="Pass --install, or drop --force.",
+        )
+        return 2
+
+    script = completion_script(shell)
+    if not script.endswith("\n"):
+        script += "\n"
+
+    if not install:
+        if as_json:
+            print(json.dumps({"shell": shell, "script": script}, sort_keys=True))
+        else:
+            sys.stdout.write(script)
+        return 0
+
+    path = completion_install_path(shell)
+    want = script.encode()
+
+    def _refuse_clobber() -> NoReturn:
+        _emit_error(
+            message=f"{path} already exists with different contents",
+            as_json=as_json,
+            hint="Re-run with --force to overwrite it.",
+        )
+        raise SystemExit(2)
+
+    try:
+        # Refuse symlinks (including dangling) so --force cannot rewrite a
+        # link target outside the conventional install path.
+        if path.is_symlink() or (path.exists() and not path.is_file()):
+            _emit_error(
+                message=f"{path} exists but is not a regular file",
+                as_json=as_json,
+                hint="Remove it (or point XDG_DATA_HOME/XDG_CONFIG_HOME elsewhere), then retry.",
+            )
+            return 1
+        current = path.read_bytes() if path.is_file() else None
+        if current == want:
+            action = "unchanged"
+        elif current is not None and not force:
+            _refuse_clobber()
+        elif force:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(want)
+            action = "written"
+        else:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            try:
+                with path.open("xb") as handle:
+                    handle.write(want)
+                action = "written"
+            except FileExistsError:
+                if path.read_bytes() != want:
+                    _refuse_clobber()
+                action = "unchanged"
+    except SystemExit as exc:
+        code = exc.code
+        return int(code) if isinstance(code, int) else 2
+    except OSError as exc:
+        _emit_error(
+            message=f"could not install the completion script to {path}: {exc}",
+            as_json=as_json,
+            hint="Ensure the path is a writable file (not a directory) that you own.",
+        )
+        return 1
+
+    if as_json:
+        print(json.dumps({"action": action, "path": str(path), "shell": shell}, sort_keys=True))
+    else:
+        lines = [f"{action}: {path}"]
+        if shell == "zsh":
+            lines.append(
+                f"  ensure {path.parent} is on $fpath before `compinit` (e.g. in ~/.zshrc), then open a new shell"
+            )
+        else:
+            lines.append("  open a new shell to pick it up")
+        print("\n".join(lines))
+    return 0
+
+
+def _bash_script() -> str:
+    value_flags = " ".join(f.option for f in _TOP_FLAGS if f.value is not None)
+    top = " ".join(f.option for f in _TOP_FLAGS)
+    top_values = "\n".join(f"      {f.option}) {_bash_values(f)}; return ;;" for f in _TOP_FLAGS if f.value is not None)
+    value_cases = [f'    *" {f.option}") {_bash_values(f)}; return ;;' for f in _TOP_FLAGS if f.value is not None]
+    flag_cases: list[str] = []
+    positional_cases: list[str] = []
+    for cmd in COMMANDS:
+        flags = COMMAND_FLAGS.get(cmd, ())
+        for flag in flags:
+            if flag.value is not None:
+                value_cases.append(f'    "{cmd} {flag.option}") {_bash_values(flag)}; return ;;')
+        if flags:
+            flag_cases.append(
+                f'      {cmd}) COMPREPLY=( $(compgen -W "{" ".join(f.option for f in flags)}" -- "$cur") ) ;;'
+            )
+        if cmd in _PATH_POSITIONALS:
+            positional_cases.append(f'    {cmd}) COMPREPLY=( $(compgen -f -- "$cur") ) ;;')
+        elif cmd in POSITIONAL_CHOICES:
+            words = " ".join(POSITIONAL_CHOICES[cmd])
+            positional_cases.append(
+                f'    {cmd}) [[ "$prev" == "$cmd" ]] && COMPREPLY=( $(compgen -W "{words}" -- "$cur") ) ;;'
+            )
+    nl = "\n"
+    return f"""# tiny-pki bash completion — generated by `tiny-pki completion bash`
+_tiny_pki_completion() {{
+  local cur prev cmd="" i word
+  COMPREPLY=()
+  cur="${{COMP_WORDS[COMP_CWORD]}}"
+  prev="${{COMP_WORDS[COMP_CWORD-1]}}"
+  for (( i = 1; i < COMP_CWORD; i++ )); do
+    word="${{COMP_WORDS[i]}}"
+    case " {value_flags} " in
+      *" $word "*) (( i++ )); continue ;;
+    esac
+    [[ "$word" == -* ]] && continue
+    cmd="$word"
+    break
+  done
+  if [[ -z "$cmd" ]]; then
+    case "$prev" in
+{top_values}
+    esac
+    COMPREPLY=( $(compgen -W "{" ".join(COMMANDS)} {top}" -- "$cur") )
+    return
+  fi
+  case "$cmd $prev" in
+{nl.join(value_cases)}
+  esac
+  if [[ "$cur" != -* ]]; then
+    case "$cmd" in
+{nl.join(positional_cases)}
+    esac
+    (( ${{#COMPREPLY[@]}} )) && return
+  fi
+  case "$cmd" in
+{nl.join(flag_cases)}
+  esac
+}}
+complete -F _tiny_pki_completion {_PROG}
+"""
+
+
+def _bash_values(flag: Flag) -> str:
+    """The ``COMPREPLY=...`` assignment for a flag's value."""
+    if flag.choices:
+        return f'COMPREPLY=( $(compgen -W "{" ".join(flag.choices)}" -- "$cur") )'
+    if flag.name == "store":
+        return 'COMPREPLY=( $(compgen -d -- "$cur") )'
+    if flag.path:
+        return 'COMPREPLY=( $(compgen -f -- "$cur") )'
+    return "COMPREPLY=()"
+
+
+def _emit_error(*, message: str, as_json: bool, hint: str | None = None) -> None:
+    if as_json:
+        payload: dict[str, object] = {"error": "usage_error", "message": message, "ok": False}
+        if hint:
+            payload["hint"] = hint
+        if "not a regular file" in message or "could not install" in message:
+            payload["error"] = "install_failed"
+        print(json.dumps(payload, sort_keys=True), file=sys.stderr)
+        return
+    print(message, file=sys.stderr)
+    if hint:
+        print(hint, file=sys.stderr)
+
+
+def _fish_script() -> str:
+    lines = [
+        "# tiny-pki fish completion — generated by `tiny-pki completion fish`",
+        f"complete -c {_PROG} -f",
+    ]
+    for flag in _TOP_FLAGS:
+        condition = "" if flag.value is not None else "-n __fish_use_subcommand "
+        lines.append(f"complete -c {_PROG} {condition}{_fish_flag(flag)}")
+    descriptions = dict(COMMAND_HELP)
+    for cmd in COMMANDS:
+        lines.append(f"complete -c {_PROG} -n __fish_use_subcommand -a {cmd} -d {_sq(descriptions[cmd])}")
+    for cmd in COMMANDS:
+        seen = _sq(f"__fish_seen_subcommand_from {cmd}")
+        if cmd in _PATH_POSITIONALS:
+            lines.append(f"complete -c {_PROG} -n {seen} -F")
+        elif cmd in POSITIONAL_CHOICES:
+            lines.append(f"complete -c {_PROG} -n {seen} -a {_sq(' '.join(POSITIONAL_CHOICES[cmd]))}")
+        for flag in COMMAND_FLAGS.get(cmd, ()):
+            lines.append(f"complete -c {_PROG} -n {seen} {_fish_flag(flag)}")
+    return "\n".join(lines) + "\n"
+
+
+def _fish_flag(flag: Flag) -> str:
+    parts = [f"-l {flag.name}"]
+    if flag.choices:
+        parts.append(f"-x -a {_sq(' '.join(flag.choices))}")
+    elif flag.name == "store":
+        parts.append("-x -a '(__fish_complete_directories)'")
+    elif flag.path:
+        parts.append("-r -F")
+    elif flag.value is not None:
+        parts.append("-x")
+    parts.append(f"-d {_sq(flag.help)}")
+    return " ".join(parts)
+
+
+def _parse_completion_argv(argv: list[str]) -> tuple[str, bool, bool, bool]:
+    if not argv:
+        print(
+            "usage: tiny-pki completion <bash|zsh|fish> [--install] [--force] [--json]",
+            file=sys.stderr,
+        )
+        raise SystemExit(2)
+    shell = argv[0]
+    if shell not in _SHELLS:
+        print(f"unsupported shell: {shell!r} (expected bash, zsh, or fish)", file=sys.stderr)
+        raise SystemExit(2)
+    install = False
+    force = False
+    as_json = False
+    for token in argv[1:]:
+        if token == "--install":
+            install = True
+        elif token == "--force":
+            force = True
+        elif token == "--json":
+            as_json = True
+        else:
+            print(f"unexpected argument: {token!r}", file=sys.stderr)
+            raise SystemExit(2)
+    return shell, install, force, as_json
+
+
+def _xdg_base(var: str, default: Path) -> Path:
+    """XDG base dir from ``$var``, honoring the spec: a relative value is ignored."""
+    value = os.environ.get(var, "")
+    candidate = Path(value) if value else default
+    return candidate if candidate.is_absolute() else default
+
+
+def _zsh_script() -> str:
+    descriptions = dict(COMMAND_HELP)
+    cmds = "\n    ".join(_sq(f"{cmd.replace(':', '\\:')}:{descriptions[cmd]}") for cmd in COMMANDS)
+    top = " \\\n    ".join(_zsh_spec(flag) for flag in _TOP_FLAGS)
+    global_specs = [_zsh_spec(flag) for flag in _TOP_FLAGS if flag.value is not None]
+    cases: list[str] = []
+    for cmd in COMMANDS:
+        specs = [_zsh_spec(flag) for flag in COMMAND_FLAGS.get(cmd, ())] + global_specs
+        if cmd in _PATH_POSITIONALS:
+            specs.append("'*:file:_files'")
+        elif cmd == "export":
+            specs.extend(["'1:format:(p12 pem)'", "'2:name: '"])
+        elif cmd in POSITIONAL_CHOICES:
+            specs.append(_sq(f"1:argument:({' '.join(POSITIONAL_CHOICES[cmd])})"))
+        cases.append(f"        {cmd}) _arguments {' '.join(specs)} ;;")
+    body = "\n".join(cases)
+    # Function name must match the installed file (``_tiny-pki``) so zsh
+    # autoload from ``$fpath`` finds the right completer without a second
+    # ``compdef`` call.
+    return f"""#compdef {_PROG}
+# tiny-pki zsh completion — generated by `tiny-pki completion zsh`
+_tiny-pki() {{
+  local -a cmds
+  cmds=(
+    {cmds}
+  )
+  local context state state_descr line
+  typeset -A opt_args
+  _arguments -C \\
+    {top} \\
+    '1:command:->cmd' \\
+    '*::arg:->args'
+  case $state in
+    cmd)
+      _describe -t commands 'tiny-pki command' cmds
+      ;;
+    args)
+      case $words[1] in
+{body}
+      esac
+      ;;
+  esac
+}}
+"""
+
+
+def _zsh_spec(flag: Flag) -> str:
+    """An ``_arguments`` option spec such as ``'--key-type[key algorithm]:TYPE:(rsa ec-p256)'``."""
+    text = flag.help.replace("\\", "\\\\").replace("[", "\\[").replace("]", "\\]")
+    prefix = "*" if flag.repeatable else ""
+    spec = f"{prefix}{flag.option}[{text}]"
+    if flag.value is not None:
+        if flag.choices:
+            action = f"({' '.join(flag.choices)})"
+        elif flag.name == "store":
+            action = "_files -/"
+        elif flag.path:
+            action = "_files"
+        else:
+            action = " "
+        spec += f":{flag.value}:{action}"
+    elif flag.name in {"help", "version"}:
+        spec = f"(- *){spec}"
+    return _sq(spec)
+
+
+def _sq(text: str) -> str:
+    """Quote ``text`` as one single-quoted shell word."""
+    return "'" + text.replace("'", "'\\''") + "'"

tiny_pki/cli/entry.py

@@ -0,0 +1,27 @@
+"""``tiny-pki`` console script: explain a missing ``[cli]`` extra instead of a traceback.
+
+The library needs only ``cryptography``; the REPL and one-shot CLI also need
+``prompt-toolkit``, which ships in the optional ``tiny-pki[cli]`` extra. This
+module must not import :mod:`tiny_pki.cli.main` at module level, because that
+import is exactly what fails without the extra.
+"""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from importlib.util import find_spec
+
+CLI_EXTRA_HINT = (
+    "tiny-pki: the command-line tool needs the [cli] extra, which is not installed. "
+    "Install it with: pipx install 'tiny-pki[cli]' (or uv tool install 'tiny-pki[cli]', "
+    "or pip install 'tiny-pki[cli]')"
+)
+
+
+def main() -> None:
+    """Run the CLI, or exit 1 with install instructions when ``prompt-toolkit`` is missing."""
+    if find_spec("prompt_toolkit") is None:
+        print(CLI_EXTRA_HINT, file=sys.stderr)
+        raise SystemExit(1)
+    importlib.import_module("tiny_pki.cli.main").main()