// cmdxray — curated knowledge base of common commands and their flags.
// Hand-curated for accuracy and readability. Short flags are keyed by their
// single letter (so combined flags like -xzvf resolve per-letter); long flags
// are keyed with their leading "--". Extend freely; keep glosses plain-English.

export interface CommandInfo {
  summary: string;
  flags: Record<string, string>;
  // Subcommands, e.g. git: { commit: "record staged changes", ... }.
  subcommands?: Record<string, string>;
  // Flags that consume the FOLLOWING word as their value (short-letter keys and
  // long "--name" keys). Used to label that word as "value for <flag>".
  takesValue?: string[];
  // Per-subcommand flag overrides. When a subcommand is active, these glosses
  // win over the command-level `flags` (e.g. `docker build -t` = tag, not tty;
  // `kubectl logs -f` = follow, not file). Key = subcommand name.
  subFlags?: Record<string, Record<string, string>>;
  // Per-subcommand value-taking overrides. When a subcommand overrides a flag
  // via `subFlags`, whether that flag consumes the next word is decided here
  // (default: it does NOT). Key = subcommand name.
  subTakesValue?: Record<string, string[]>;
  // Traditional tools (tar, ps) accept a leading flag cluster with NO dash,
  // e.g. `tar czf x.tgz`, `ps aux`. When true, the first bare operand made up
  // entirely of known single-letter flags is expanded letter-by-letter.
  bareFlags?: boolean;
  // Two-level subcommands, e.g. `docker compose up`, `git stash pop`. Keyed by
  // the first subcommand; the second bare word is looked up here.
  subSubcommands?: Record<string, Record<string, string>>;
}

export const DB: Record<string, CommandInfo> = {
  tar: {
    summary: "archive utility — bundle files into (or extract them from) a .tar",
    takesValue: ["f", "C", "--exclude", "--exclude-from", "--strip-components", "-T"],
    bareFlags: true,
    flags: {
      c: "create a new archive",
      x: "extract files from an archive",
      t: "list the contents of an archive",
      r: "append files to the end of an archive",
      u: "append only files newer than the archive copy",
      z: "filter the archive through gzip (.gz)",
      j: "filter the archive through bzip2 (.bz2)",
      J: "filter the archive through xz (.xz)",
      v: "verbose — list each file as it is processed",
      f: "use the next argument as the archive file name",
      C: "change to the given directory first",
      p: "preserve file permissions when extracting",
      h: "follow symlinks — archive the files they point to",
      k: "keep existing files; don't overwrite when extracting",
      "--create": "create a new archive",
      "--extract": "extract files from an archive",
      "--list": "list the contents of an archive",
      "--gzip": "filter the archive through gzip",
      "--bzip2": "filter the archive through bzip2",
      "--xz": "filter the archive through xz",
      "--verbose": "verbose — list each file as it is processed",
      "--file": "use the given archive file",
      "--exclude": "skip files matching this pattern",
      "--exclude-from": "skip files matching patterns read from this file",
      "--exclude-vcs": "skip version-control dirs (.git, .svn, …)",
      "--strip-components": "strip this many leading path parts when extracting",
    },
  },
  grep: {
    summary: "search input for lines matching a pattern",
    takesValue: ["e", "f", "A", "B", "C", "m", "d", "--include", "--exclude", "--exclude-dir", "--include-dir"],
    flags: {
      i: "ignore case when matching",
      v: "invert — show lines that do NOT match",
      r: "search directories recursively",
      R: "search directories recursively, following symlinks",
      n: "prefix each match with its line number",
      l: "print only the names of files with matches",
      L: "print only the names of files with NO match",
      c: "print only a count of matching lines",
      E: "interpret the pattern as an extended regex",
      F: "match fixed strings, not regexes",
      P: "interpret the pattern as a Perl-compatible regex (PCRE)",
      G: "interpret the pattern as a basic regex (the default)",
      o: "print only the matched part of each line",
      w: "match whole words only",
      x: "match only whole lines",
      I: "skip binary files (treat them as non-matching)",
      a: "treat binary files as text",
      H: "print the file name with each match",
      h: "never print the file name with matches",
      q: "quiet — print nothing, exit 0 on the first match",
      s: "suppress error messages about unreadable files",
      z: "treat input and output as NUL-separated lines",
      A: "also print N lines after each match",
      B: "also print N lines before each match",
      C: "also print N lines of context around each match",
      e: "use the next argument as the pattern",
      f: "read patterns from the given file",
      "--ignore-case": "ignore case when matching",
      "--invert-match": "show lines that do NOT match",
      "--recursive": "search directories recursively",
      "--line-number": "prefix each match with its line number",
      "--color": "highlight matches in color",
      "--include": "only search files whose name matches this glob",
      "--exclude": "skip files whose name matches this glob",
      "--exclude-dir": "skip directories whose name matches this glob",
      "--include-dir": "only descend into directories matching this glob",
      "--word-regexp": "match whole words only",
      "--fixed-strings": "match fixed strings, not regexes",
      "--files-with-matches": "print only the names of files with matches",
      "--count": "print only a count of matching lines",
      "--only-matching": "print only the matched part of each line",
      "--extended-regexp": "interpret the pattern as an extended regex",
      "--perl-regexp": "interpret the pattern as a Perl-compatible regex",
      "--quiet": "quiet — print nothing, exit 0 on the first match",
      "--no-filename": "never print the file name with matches",
      "--with-filename": "print the file name with each match",
    },
  },
  ls: {
    summary: "list directory contents",
    flags: {
      l: "long format — permissions, owner, size, date",
      a: "show hidden entries (dotfiles) too",
      A: "show hidden entries except . and ..",
      h: "human-readable sizes (K, M, G)",
      t: "sort by modification time, newest first",
      r: "reverse the sort order",
      S: "sort by file size, largest first",
      R: "list subdirectories recursively",
      d: "list directories themselves, not their contents",
      1: "list one entry per line",
      F: "append an indicator (/, *, @) to entries by type",
      i: "show each entry's inode number",
      "--color": "colorize the output (auto, always, never)",
      "--group-directories-first": "list directories before files",
    },
  },
  rm: {
    summary: "remove files or directories",
    flags: {
      r: "recurse into directories (delete their contents)",
      f: "force — ignore missing files, never prompt",
      i: "prompt before every removal",
      v: "verbose — explain what is being done",
      d: "remove empty directories",
    },
  },
  cp: {
    summary: "copy files or directories",
    flags: {
      r: "copy directories recursively",
      R: "copy directories recursively",
      f: "force — overwrite the destination if needed",
      i: "prompt before overwriting",
      p: "preserve mode, ownership and timestamps",
      v: "verbose — print each file as it is copied",
      a: "archive — recursive plus preserve everything",
      u: "copy only when the source is newer than the destination",
    },
  },
  mv: {
    summary: "move or rename files and directories",
    flags: {
      f: "force — overwrite the destination without prompting",
      i: "prompt before overwriting",
      n: "never overwrite an existing file",
      v: "verbose — print each file as it is moved",
    },
  },
  ln: {
    summary: "make links between files",
    flags: {
      s: "make a symbolic (soft) link instead of a hard link",
      f: "force — remove an existing destination first",
      n: "treat a symlinked destination as a normal file",
      v: "verbose — print the name of each linked file",
      r: "make the symlink target relative to the link location",
    },
  },
  mkdir: {
    summary: "create directories",
    flags: {
      p: "create parent directories as needed, no error if they exist",
      v: "print a message for each created directory",
      m: "set the permission mode of the new directory",
    },
  },
  curl: {
    summary: "transfer data to or from a URL",
    takesValue: ["o", "X", "H", "d", "u", "A", "b", "c", "e"],
    flags: {
      s: "silent — hide the progress meter and errors",
      S: "with -s, still show errors",
      L: "follow HTTP redirects",
      o: "write output to the given file",
      O: "save output using the remote file name",
      X: "set the HTTP request method (e.g. POST)",
      H: "add a request header",
      d: "send the given data in a POST body",
      F: "send a multipart/form-data field",
      f: "fail silently on server errors (no error page)",
      k: "allow insecure TLS connections",
      i: "include the response headers in the output",
      I: "fetch only the response headers (HEAD request)",
      u: "supply user:password credentials",
      A: "set the User-Agent header",
      b: "send cookies (string or file)",
      "--silent": "hide the progress meter",
      "--location": "follow HTTP redirects",
      "--output": "write output to the given file",
      "--header": "add a request header",
      "--request": "set the HTTP request method",
      "--data": "send the given data in a POST body",
      "--fail": "fail silently on server errors",
    },
  },
  wget: {
    summary: "download files from the web over HTTP/FTP",
    takesValue: ["O", "P", "--limit-rate", "e"],
    flags: {
      O: "write the download to the given file name",
      P: "save files into the given directory",
      c: "continue a partially downloaded file",
      q: "quiet — no output",
      r: "recursive — download linked pages too",
      "--show-progress": "always show the progress bar, even when quiet",
      "--no-check-certificate": "skip TLS certificate validation",
      "--limit-rate": "cap the download speed (e.g. 200k)",
      N: "only download if the remote file is newer than the local one",
      "--no-verbose": "turn off verbose output without going fully quiet",
    },
  },
  find: {
    summary: "walk a directory tree looking for files",
    takesValue: [
      "-name",
      "-iname",
      "-path",
      "-ipath",
      "-type",
      "-mtime",
      "-mmin",
      "-size",
      "-maxdepth",
      "-mindepth",
      "-newer",
      "-user",
      "-group",
      "-perm",
    ],
    flags: {
      "-name": "match files by this name pattern",
      "-iname": "match by name, case-insensitively",
      "-path": "match by path pattern",
      "-ipath": "match by path pattern, case-insensitively",
      "-type": "match by type (f=file, d=directory, l=symlink)",
      "-mtime": "match by modification age in days",
      "-mmin": "match by modification age in minutes",
      "-size": "match by file size",
      "-newer": "match files newer than the given reference file",
      "-user": "match files owned by this user",
      "-group": "match files owned by this group",
      "-perm": "match files with these permission bits",
      "-empty": "match empty files and directories",
      "-exec": "run a command on each match ({} = the file, ; ends it)",
      "-execdir": "like -exec, but run from the match's own directory",
      "-ok": "like -exec, but prompt before running each command",
      "-okdir": "like -execdir, but prompt before running each command",
      "-delete": "delete each matching file",
      "-prune": "don't descend into a matching directory",
      "-maxdepth": "descend at most this many directory levels",
      "-mindepth": "ignore matches shallower than this many levels",
      "-print": "print each match (the default action)",
      "-print0": "print each match separated by NUL (for xargs -0)",
    },
  },
  ffmpeg: {
    summary: "record, convert and stream audio and video",
    flags: {
      "-i": "read from this input file (repeat for multiple inputs)",
      "-vf": "apply a video filter graph (scale, crop, fps, overlay, …)",
      "-af": "apply an audio filter graph",
      "-filter_complex": "apply a filter graph across multiple inputs/outputs",
      "-c": "set the codec (use -c:v for video, -c:a for audio, copy = remux)",
      "-c:v": "set the video codec (e.g. libx264, libx265)",
      "-c:a": "set the audio codec (e.g. aac, libmp3lame)",
      "-vcodec": "set the video codec (older spelling of -c:v)",
      "-acodec": "set the audio codec (older spelling of -c:a)",
      "-b:v": "set the target video bitrate (e.g. 1M)",
      "-b:a": "set the target audio bitrate (e.g. 128k)",
      "-crf": "constant rate factor — quality vs size (lower = better, x264/x265)",
      "-preset": "encoding speed vs compression trade-off (ultrafast … veryslow)",
      "-r": "set the frame rate in frames per second",
      "-s": "set the frame size as WxH (e.g. 1280x720)",
      "-ss": "seek to this start time before processing",
      "-t": "limit the output to this duration",
      "-to": "stop writing at this timestamp",
      "-map": "choose which input streams end up in the output",
      "-f": "force this container/output format",
      "-an": "drop the audio stream (no audio)",
      "-vn": "drop the video stream (no video)",
      "-sn": "drop the subtitle stream",
      "-y": "overwrite the output file without asking",
      "-n": "never overwrite an existing output file",
      "-loglevel": "set how verbose ffmpeg's logging is",
      "-hide_banner": "suppress the startup copyright/build banner",
    },
    takesValue: [
      "-i", "-vf", "-af", "-filter_complex", "-c", "-c:v", "-c:a", "-vcodec",
      "-acodec", "-b:v", "-b:a", "-crf", "-preset", "-r", "-s", "-ss", "-t",
      "-to", "-map", "-f", "-loglevel",
    ],
  },
  openssl: {
    summary: "OpenSSL — command-line cryptography and TLS toolkit",
    subcommands: {
      req: "create or process a certificate signing request (CSR)",
      x509: "display or convert an X.509 certificate",
      genrsa: "generate an RSA private key",
      genpkey: "generate a private key (any algorithm)",
      rsa: "inspect or convert an RSA key",
      pkey: "inspect or convert a private key",
      s_client: "open a TLS connection to a server (debugging client)",
      s_server: "run a simple TLS server",
      dgst: "compute a message digest (hash) or sign/verify",
      enc: "symmetric-cipher encrypt or decrypt",
      rand: "generate random bytes",
      verify: "verify a certificate chain",
      pkcs12: "build or parse a PKCS#12 (.p12/.pfx) bundle",
    },
    flags: {
      "-x509": "output a self-signed certificate instead of a CSR",
      "-new": "generate a new request/key",
      "-newkey": "generate a new key of this type (e.g. rsa:4096)",
      "-key": "use this existing private key",
      "-keyout": "write the generated private key to this file",
      "-out": "write output to this file",
      "-in": "read input from this file",
      "-days": "how many days the certificate stays valid",
      "-nodes": "don't encrypt the private key (no passphrase)",
      "-subj": "set the subject DN inline (skip the interactive prompts)",
      "-sha256": "use SHA-256 as the signature/digest algorithm",
      "-text": "also print the certificate/key in human-readable text",
      "-noout": "don't print the encoded (PEM/DER) output",
      "-config": "use this OpenSSL configuration file",
      "-connect": "host:port to connect to (s_client)",
      "-servername": "SNI hostname to send (s_client)",
      "-passin": "source of the input passphrase",
      "-passout": "source of the output passphrase",
    },
    takesValue: [
      "-newkey", "-key", "-keyout", "-out", "-in", "-days", "-subj",
      "-config", "-connect", "-servername", "-passin", "-passout",
    ],
  },
  chmod: {
    summary: "change file mode (permission) bits",
    flags: {
      R: "apply changes recursively",
      v: "verbose — report each change",
      c: "report only files that actually change",
      f: "suppress error messages",
    },
  },
  chown: {
    summary: "change file owner and group",
    flags: {
      R: "apply changes recursively",
      v: "verbose — report each change",
      h: "affect symlinks themselves, not their targets",
    },
  },
  ssh: {
    summary: "log in to or run a command on a remote machine",
    takesValue: ["i", "p", "L", "R", "o"],
    flags: {
      i: "use the given private key file",
      p: "connect to this port",
      L: "set up local port forwarding",
      R: "set up remote port forwarding",
      D: "set up a local SOCKS proxy (dynamic forwarding)",
      N: "do not run a remote command (forwarding only)",
      f: "go to the background after authenticating",
      v: "verbose — print debugging output",
      t: "force a pseudo-terminal",
      o: "set an ssh_config option (e.g. StrictHostKeyChecking=no)",
    },
  },
  scp: {
    summary: "copy files between hosts over SSH",
    takesValue: ["i", "P"],
    flags: {
      r: "copy directories recursively",
      P: "connect to this port (capital P, unlike ssh)",
      i: "use the given private key file",
      p: "preserve modification times and modes",
      C: "compress data during transfer",
    },
  },
  rsync: {
    summary: "efficiently sync files, copying only what changed",
    takesValue: ["e"],
    flags: {
      a: "archive — recurse and preserve nearly everything",
      v: "verbose — list files as they transfer",
      z: "compress data during transfer",
      r: "recurse into directories",
      P: "show progress and keep partial files",
      n: "dry run — show what would happen, change nothing",
      u: "skip files that are newer on the destination",
      e: "use the given remote shell (e.g. ssh)",
      "--delete": "delete files on the destination that are gone from the source",
      "--exclude": "skip files matching this pattern",
      "--progress": "show a progress bar during transfer",
      "--dry-run": "show what would happen, change nothing",
    },
  },
  docker: {
    summary: "build, run and manage containers",
    takesValue: ["p", "v", "e", "--name", "--network", "-w"],
    subcommands: {
      run: "create and start a new container",
      build: "build an image from a Dockerfile",
      ps: "list running containers",
      images: "list local images",
      exec: "run a command inside a running container",
      pull: "download an image from a registry",
      push: "upload an image to a registry",
      stop: "stop a running container",
      rm: "remove a container",
      rmi: "remove an image",
      logs: "show a container's output",
      compose: "run multi-container apps from a compose file",
    },
    subFlags: {
      build: {
        t: "tag the built image (name:tag)",
        "--no-cache": "build without using any cached layers",
        "--build-arg": "set a build-time variable (NAME=value)",
        "--pull": "always pull a newer version of the base image",
        "--platform": "build for this target platform (e.g. linux/arm64)",
        "--target": "stop at this named build stage (multi-stage builds)",
        f: "use the given Dockerfile (--file)",
      },
      compose: {
        d: "detached — run the services in the background",
        "--build": "build images before starting the containers",
        "--no-cache": "don't use cache when building images",
        "--force-recreate": "recreate containers even if config is unchanged",
        "--remove-orphans": "remove containers for services not in the compose file",
        "-f": "use the given compose file",
      },
    },
    subTakesValue: {
      build: ["t", "--build-arg", "--platform", "--target", "f"],
      compose: ["-f"],
    },
    subSubcommands: {
      compose: {
        up: "create and start the services in the compose file",
        down: "stop and remove the services, networks and volumes",
        build: "build or rebuild the services' images",
        ps: "list the compose project's containers",
        logs: "show output from the services",
        exec: "run a command in a running service container",
        run: "run a one-off command against a service",
        start: "start existing service containers",
        stop: "stop running service containers",
        restart: "restart service containers",
        pull: "pull the services' images",
        config: "validate and print the resolved compose file",
      },
    },
    flags: {
      d: "detached — run in the background",
      it: "interactive with a terminal attached",
      i: "keep STDIN open (interactive)",
      t: "allocate a pseudo-terminal",
      p: "publish a container port to the host (host:container)",
      v: "mount a volume (host path : container path)",
      e: "set an environment variable",
      w: "set the working directory inside the container",
      "--rm": "remove the container when it exits",
      "--name": "give the container a name",
      "--network": "connect the container to this network",
    },
  },
  git: {
    summary: "the distributed version control system",
    takesValue: ["-C", "m", "b"],
    subFlags: {
      log: { n: "limit output to the last N commits" },
      shortlog: { n: "sort authors by number of commits" },
      commit: { n: "skip the pre-commit and commit-msg hooks (--no-verify)" },
      rebase: { i: "interactive — edit the list of commits before replaying them" },
    },
    subTakesValue: {
      log: ["n"],
    },
    subcommands: {
      clone: "copy a repository to your machine",
      init: "create a new empty repository here",
      add: "stage changes for the next commit",
      commit: "record staged changes as a new commit",
      status: "show what is staged, modified and untracked",
      push: "upload your commits to a remote",
      pull: "fetch from a remote and merge into the current branch",
      fetch: "download objects and refs from a remote (no merge)",
      checkout: "switch branches or restore files",
      switch: "switch to another branch",
      branch: "list, create or delete branches",
      merge: "join another branch's history into this one",
      rebase: "reapply your commits on top of another base",
      log: "show the commit history",
      diff: "show changes between commits, branches or the working tree",
      stash: "shelve uncommitted changes for later",
      reset: "move the current branch and optionally the index/working tree",
      revert: "make a new commit that undoes an earlier one",
      tag: "create, list or delete tags",
      remote: "manage the set of tracked repositories",
      cherry: "apply the change introduced by a specific commit",
      restore: "restore working-tree files",
    },
    flags: {
      m: "use the next argument as the commit message",
      a: "automatically stage every tracked, modified file",
      b: "create and switch to a new branch",
      f: "force the operation",
      d: "delete (e.g. a branch)",
      D: "force-delete (e.g. an unmerged branch)",
      n: "dry run / no-commit, depending on the subcommand",
      "--amend": "replace the previous commit instead of adding a new one",
      "--force": "force the operation (e.g. push)",
      "--force-with-lease": "force-push only if the remote hasn't moved since you fetched",
      "--all": "operate on everything (all branches / all changes)",
      "--oneline": "show each commit on a single line",
      "--graph": "draw an ASCII graph of the branch structure",
      "--decorate": "show ref names (branches, tags) next to commits",
      "--continue": "resume the operation after resolving conflicts",
      "--abort": "cancel the operation and restore the original state",
      "--skip": "skip the current commit and continue",
      "--interactive": "interactive — edit the list of commits before replaying them",
      "--set-upstream": "record this remote branch as the upstream for tracking",
      "--no-verify": "skip the pre-commit and commit-msg hooks",
      "-C": "run as if git was started in the given directory",
    },
  },
  npm: {
    summary: "the Node.js package manager",
    subcommands: {
      install: "install dependencies (or a named package)",
      i: "install dependencies (short for install)",
      run: "run a script defined in package.json",
      test: "run the project's test script",
      start: "run the project's start script",
      publish: "publish the package to the registry",
      init: "create a package.json",
      update: "update packages to newer allowed versions",
      uninstall: "remove a package",
      ci: "clean install exactly from the lockfile",
      exec: "run a package's binary",
    },
    takesValue: ["--omit", "--include", "-w", "--workspace"],
    flags: {
      g: "operate globally, not on the local project",
      D: "save to devDependencies",
      S: "save to dependencies (default)",
      "--save-dev": "save to devDependencies",
      "--save": "save to dependencies",
      "--global": "operate globally",
      "--production": "skip devDependencies",
      "--omit": "exclude a dependency type from install (e.g. dev)",
      "--include": "force-include a dependency type",
      "--force": "overwrite conflicts and bypass some checks",
      "--legacy-peer-deps": "ignore peer-dependency conflicts (npm v7+ behavior)",
      "--workspace": "run the command for this workspace only",
    },
  },
  systemctl: {
    summary: "control the systemd init system and its services",
    subcommands: {
      start: "start a service now",
      stop: "stop a running service now",
      restart: "stop and start a service",
      reload: "tell a service to reload its configuration",
      status: "show whether a service is running, plus recent logs",
      enable: "start this service automatically at boot",
      disable: "do not start this service at boot",
      "daemon-reload": "reload systemd's own unit files after edits",
      list: "list units",
      "is-active": "check whether a unit is currently running",
    },
    flags: {
      "--now": "also start/stop immediately (with enable/disable)",
      "--user": "act on the per-user systemd, not the system one",
      "--failed": "limit output to failed units",
      "--no-pager": "print output directly instead of piping it to a pager",
      l: "show full output — do not truncate long lines",
      "--full": "show full output — do not truncate long lines",
      q: "quiet — suppress informational messages",
      "--quiet": "quiet — suppress informational messages",
      "--type": "limit to units of this type (service, socket, …)",
    },
  },
  journalctl: {
    summary: "query and display logs from the systemd journal",
    takesValue: [
      "u",
      "--unit",
      "--since",
      "--until",
      "-p",
      "--priority",
      "-n",
      "--lines",
      "-t",
      "--identifier",
      "--user-unit",
      "-b",
      "--boot",
    ],
    flags: {
      u: "show logs for this systemd unit only",
      "--unit": "show logs for this systemd unit only",
      "--user-unit": "show logs for this per-user unit only",
      f: "follow — keep printing new log entries as they arrive",
      "--follow": "follow — keep printing new log entries as they arrive",
      "--since": "only entries at or after this time (e.g. \"1 hour ago\")",
      "--until": "only entries at or before this time",
      n: "show only the last N lines",
      "--lines": "show only the last N lines",
      e: "jump to the end of the journal in the pager",
      "--pager-end": "jump to the end of the journal in the pager",
      r: "reverse — show newest entries first",
      "--reverse": "reverse — show newest entries first",
      k: "show only kernel messages",
      "--dmesg": "show only kernel messages",
      b: "show logs from a specific boot (default: current boot)",
      "--boot": "show logs from a specific boot (default: current boot)",
      x: "add explanatory help text to log messages where available",
      "--catalog": "add explanatory help text to log messages where available",
      p: "filter by priority (e.g. err, warning, or 0-7)",
      "--priority": "filter by priority (e.g. err, warning, or 0-7)",
      "--no-pager": "print straight to the terminal, don't use a pager",
      "--system": "show messages from system services and the kernel",
      "--user": "show messages from the current user's services",
      o: "set the output format (short, json, cat, …)",
      "--output": "set the output format (short, json, cat, …)",
    },
  },
  aws: {
    summary: "command-line interface for Amazon Web Services",
    subcommands: {
      s3: "high-level Amazon S3 object-storage commands (cp, sync, ls, rm…)",
      s3api: "low-level, 1:1 mapping to the S3 API",
      ec2: "manage EC2 virtual machines, volumes, security groups…",
      iam: "manage IAM users, roles, and permissions",
      lambda: "manage AWS Lambda serverless functions",
      logs: "CloudWatch Logs — view and query log groups",
      sts: "Security Token Service — assume roles, get caller identity",
      ecr: "Elastic Container Registry commands",
      eks: "manage Elastic Kubernetes Service clusters",
      configure: "set up credentials, region, and output defaults",
      dynamodb: "manage DynamoDB tables and items",
      ssm: "Systems Manager — parameters, session manager, run command",
    },
    subSubcommands: {
      s3: {
        cp: "copy files/objects to, from, or between S3",
        sync: "sync a directory tree to/from S3 (only changed files)",
        ls: "list buckets or objects",
        rm: "delete objects",
        mv: "move (copy then delete) objects",
        mb: "make (create) a bucket",
        rb: "remove (delete) a bucket",
      },
    },
    takesValue: [
      "--region",
      "--profile",
      "--output",
      "--acl",
      "--query",
      "--endpoint-url",
      "--sse",
      "--storage-class",
    ],
    flags: {
      "--recursive": "apply the command to all objects under the prefix/directory",
      "--acl": "set a canned access-control policy (e.g. public-read, private)",
      "--dryrun": "show what would happen without actually doing it",
      "--delete": "with sync: delete destination files missing from the source",
      "--exclude": "skip paths matching this pattern",
      "--include": "re-include paths (after --exclude) matching this pattern",
      "--profile": "use this named credentials profile",
      "--region": "target this AWS region",
      "--output": "output format: json, text, table, or yaml",
      "--query": "filter/reshape the output with a JMESPath expression",
      "--no-paginate": "return all results in one response, don't paginate",
      "--endpoint-url": "talk to this endpoint (e.g. an S3-compatible service)",
      "--sse": "server-side-encrypt uploaded objects",
      "--storage-class": "S3 storage class (STANDARD, GLACIER, …)",
      "--version": "print the aws CLI version",
    },
  },
  kubectl: {
    summary: "control a Kubernetes cluster",
    takesValue: ["n", "-n", "o", "-o", "f", "-f", "l", "-l"],
    subcommands: {
      get: "list resources of a given type",
      describe: "show detailed state of a resource",
      apply: "create or update resources from a file",
      delete: "remove resources",
      logs: "print a pod's logs",
      exec: "run a command inside a pod",
      create: "create a resource",
      edit: "edit a live resource in your editor",
      scale: "change the number of replicas",
      rollout: "manage a rollout (status, undo, restart)",
      port: "forward a local port to a pod (port-forward)",
    },
    subFlags: {
      logs: { f: "follow — stream new log lines as they arrive" },
      "port-forward": { f: "read the resource definition from this file" },
    },
    subTakesValue: {
      logs: [],
    },
    flags: {
      n: "act in the given namespace",
      o: "choose the output format (json, yaml, wide)",
      f: "read the resource definition from this file",
      l: "select resources by label",
      w: "watch for changes and stream updates",
      "--watch": "watch for changes and stream updates",
      A: "act across all namespaces",
      "--all-namespaces": "act across all namespaces",
      "--namespace": "act in the given namespace",
    },
  },
  apt: {
    summary: "install and manage Debian/Ubuntu packages",
    subcommands: {
      install: "install one or more packages",
      remove: "remove packages but keep their config",
      purge: "remove packages and their config",
      update: "refresh the list of available packages",
      upgrade: "install newer versions of installed packages",
      search: "search for packages by keyword",
      show: "show details about a package",
      list: "list packages (installed, upgradable, …)",
      autoremove: "remove packages no longer needed",
    },
    flags: {
      y: "assume yes — do not prompt for confirmation",
      "--yes": "assume yes — do not prompt for confirmation",
      "--no-install-recommends": "do not install recommended extras",
    },
  },
  sed: {
    summary: "stream editor — transform text line by line",
    takesValue: ["e", "f"],
    flags: {
      i: "edit files in place instead of printing to stdout",
      n: "suppress automatic printing (use with p)",
      e: "add the next argument as an editing script",
      E: "use extended regular expressions",
      r: "use extended regular expressions (GNU)",
      "--in-place": "edit files in place",
    },
  },
  awk: {
    summary: "pattern-scanning and text-processing language",
    takesValue: ["F", "v", "f"],
    flags: {
      F: "set the input field separator",
      v: "assign a variable before the program runs",
      f: "read the awk program from a file",
    },
  },
  jq: {
    summary: "command-line JSON processor (apply a filter to JSON input)",
    takesValue: ["arg", "argjson", "f", "slurpfile", "rawfile"],
    flags: {
      r: "raw output — print strings without JSON quotes",
      j: "raw output with no trailing newline between results",
      c: "compact output — one JSON result per line",
      n: "don't read input; use null as the input",
      s: "slurp — read the whole input stream into one array",
      R: "read raw input — each line becomes a JSON string",
      e: "set the exit code from the last output (for scripting)",
      S: "sort object keys in the output",
      a: "output non-ASCII characters as \\uXXXX escapes",
      f: "read the filter program from a file",
      arg: "define a string variable: --arg name value",
      argjson: "define a JSON variable: --argjson name json",
      tab: "indent the output with tabs",
    },
  },
  ps: {
    summary: "report a snapshot of running processes",
    bareFlags: true,
    takesValue: ["--sort", "-o", "-p", "-u", "-C"],
    flags: {
      a: "show processes for all users",
      u: "show a user-oriented, detailed format",
      x: "include processes without a controlling terminal",
      e: "show every process",
      f: "full-format listing",
      "--sort": "order the output by this column (prefix - for descending)",
      "--forest": "show the process tree with ASCII art",
      "--no-headers": "omit the column header line",
    },
  },
  netstat: {
    summary: "show network connections, routing tables, and interface stats",
    flags: {
      t: "TCP connections",
      u: "UDP connections",
      l: "only listening sockets",
      p: "show the PID and program name for each socket",
      n: "numeric output — don't resolve hosts, ports, or users",
      a: "all sockets (listening and non-listening)",
      r: "show the kernel routing table",
      e: "extended information",
      s: "per-protocol summary statistics",
      c: "continuously refresh the display",
    },
  },
  ss: {
    summary: "inspect sockets (a faster, modern replacement for netstat)",
    flags: {
      t: "TCP sockets",
      u: "UDP sockets",
      l: "only listening sockets",
      p: "show the process using each socket",
      n: "numeric output — don't resolve service names",
      a: "all sockets (listening and non-listening)",
      s: "print summary statistics",
    },
  },
  lsof: {
    summary: "list open files (and the processes that hold them open)",
    takesValue: ["i", "p", "u", "c"],
    flags: {
      i: "list network files — optionally filtered, e.g. -i :8080, -i tcp:80",
      p: "restrict to the given process ID(s)",
      u: "restrict to files opened by the given user(s)",
      c: "restrict to processes whose name begins with this string",
      n: "don't resolve host names — numeric addresses (faster)",
      P: "don't resolve port names — numeric ports (faster)",
      t: "terse output — print only process IDs (handy for scripting)",
      a: "AND the selection filters together instead of OR-ing them",
    },
  },
  ip: {
    summary: "show / manipulate routing, network devices, interfaces and tunnels",
    subcommands: {
      addr: "protocol (IP) addresses on network interfaces",
      address: "protocol (IP) addresses on network interfaces",
      a: "protocol (IP) addresses on network interfaces",
      link: "network devices (interfaces)",
      l: "network devices (interfaces)",
      route: "the routing table",
      r: "the routing table",
      neigh: "the ARP / neighbour table",
      rule: "routing policy rules",
      tunnel: "IP tunnels",
      maddr: "multicast addresses",
      monitor: "watch for network events as they happen",
    },
    subSubcommands: {
      addr: { show: "list the addresses", add: "add an address", del: "remove an address", flush: "remove all matching addresses" },
      address: { show: "list the addresses", add: "add an address", del: "remove an address", flush: "remove all matching addresses" },
      a: { show: "list the addresses", add: "add an address", del: "remove an address", flush: "remove all matching addresses" },
      link: { show: "list the devices", set: "change device settings", add: "create a virtual device", del: "delete a device" },
      l: { show: "list the devices", set: "change device settings" },
      route: { show: "list the routes", add: "add a route", del: "remove a route", get: "resolve the route for an address", flush: "remove all matching routes" },
      r: { show: "list the routes", add: "add a route", del: "remove a route", get: "resolve the route for an address" },
      neigh: { show: "list the neighbour entries", flush: "clear the neighbour table" },
    },
    flags: {
      "-4": "operate on IPv4 only",
      "-6": "operate on IPv6 only",
      "-br": "brief, tabular output",
      "-brief": "brief, tabular output",
      "-c": "colorize the output",
      "-s": "show statistics (repeat for more detail)",
      "-j": "output as JSON",
      "-json": "output as JSON",
      "-d": "show detailed output",
    },
  },
  crontab: {
    summary: "install, view, or edit a user's scheduled (cron) jobs",
    takesValue: ["u"],
    flags: {
      e: "edit the current crontab in your $EDITOR",
      l: "list (print) the current crontab",
      r: "remove the current crontab entirely",
      i: "prompt for confirmation before removing",
      u: "operate on the named user's crontab (needs privileges)",
    },
  },
  unzip: {
    summary: "extract files from a ZIP archive",
    takesValue: ["d", "x"],
    flags: {
      l: "list the archive contents without extracting",
      d: "extract into the given directory",
      o: "overwrite existing files without prompting",
      n: "never overwrite existing files",
      q: "quiet — suppress the per-file listing",
      p: "extract to standard output (pipe-friendly)",
      j: "junk paths — don't recreate the archive's directory tree",
      x: "exclude files matching the given name(s)",
      v: "verbose / show archive details",
    },
  },
  nc: {
    summary: "open, listen on, or script raw TCP/UDP connections (netcat)",
    takesValue: ["p", "w", "s"],
    flags: {
      l: "listen for an incoming connection instead of connecting",
      v: "verbose — report connections and errors",
      n: "numeric only — skip DNS/service-name lookups",
      p: "use this source port",
      u: "use UDP instead of TCP",
      k: "keep listening for more connections after one closes",
      w: "give up after this many seconds of inactivity (timeout)",
      z: "zero-I/O mode — just scan for listening ports, send no data",
      s: "use this source address",
    },
  },
  kill: {
    summary: "send a signal to a process",
    flags: {
      "9": "SIGKILL — force the process to stop immediately",
      "15": "SIGTERM — politely ask the process to stop",
      l: "list the available signal names",
      s: "send the named signal",
    },
  },
  xargs: {
    summary: "build and run command lines from standard input",
    takesValue: ["n", "I", "P", "d"],
    flags: {
      n: "use at most this many arguments per command",
      I: "replace this token with each input item",
      "0": "input items are separated by NUL, not whitespace",
      P: "run this many commands in parallel",
      r: "do nothing if the input is empty",
      t: "print each command before running it",
    },
  },
  head: {
    summary: "print the first part of files",
    takesValue: ["n", "c"],
    flags: {
      n: "print the first N lines",
      c: "print the first N bytes",
    },
  },
  tail: {
    summary: "print the last part of files",
    takesValue: ["n", "c"],
    flags: {
      n: "print the last N lines",
      c: "print the last N bytes",
      f: "follow — keep printing new lines as the file grows",
      F: "follow by name, retrying if the file is rotated",
    },
  },
  sort: {
    summary: "sort lines of text",
    takesValue: ["k", "t"],
    flags: {
      n: "sort numerically, not alphabetically",
      r: "reverse the result order",
      u: "output only the first of equal lines (unique)",
      h: "sort human-readable sizes (2K, 1G)",
      k: "sort by the given field/key",
      t: "use the given field separator",
      f: "fold case — treat lower and upper case alike",
    },
  },
  uniq: {
    summary: "report or omit repeated adjacent lines",
    takesValue: ["f", "s", "w"],
    flags: {
      c: "prefix each line with the number of times it occurred",
      d: "print only lines that are repeated",
      u: "print only lines that are never repeated",
      i: "ignore case when comparing lines",
      f: "skip the first N fields when comparing",
      s: "skip the first N characters when comparing",
      w: "compare no more than N characters per line",
    },
  },
  cut: {
    summary: "extract selected columns from each line",
    takesValue: ["d", "f", "c"],
    flags: {
      d: "use the given delimiter between fields",
      f: "select these fields",
      c: "select these character positions",
    },
  },
  tr: {
    summary: "translate or delete characters",
    flags: {
      d: "delete the given characters",
      s: "squeeze repeats of the given characters into one",
      c: "use the complement of the given set",
    },
  },
  wc: {
    summary: "count lines, words and bytes",
    flags: {
      l: "count lines",
      w: "count words",
      c: "count bytes",
      m: "count characters",
    },
  },
  tee: {
    summary: "copy input to a file and pass it through to output too",
    flags: {
      a: "append to the file instead of overwriting it",
      i: "ignore interrupt signals",
    },
  },
  diff: {
    summary: "compare two files line by line and show the differences",
    takesValue: ["C", "U"],
    flags: {
      u: "unified format — the diff style used by patches and git",
      r: "recursively compare any subdirectories found",
      i: "ignore case differences",
      w: "ignore all whitespace",
      b: "ignore changes in the amount of whitespace",
      q: "report only whether files differ, not the details",
      N: "treat absent files as empty (with -r)",
      C: "output the given number of lines of copied context",
      U: "output the given number of lines of unified context",
    },
  },
  gzip: {
    summary: "compress files with gzip (replaces the original with .gz)",
    takesValue: ["S"],
    flags: {
      d: "decompress instead of compress",
      k: "keep the input file instead of deleting it",
      c: "write to standard output, keep the original",
      r: "recurse into directories",
      f: "force — overwrite existing files / compress links",
      v: "verbose — show the name and compression ratio",
      "9": "compress best (slowest); -1 is fastest, least compression",
    },
  },
  column: {
    summary: "format input into neatly aligned columns",
    takesValue: ["s", "c", "o"],
    flags: {
      t: "create a table, determining columns from the input",
      s: "use the given characters as input field separators",
      o: "use the given string to separate output columns",
      c: "format output to fit this display width",
      n: "do not merge multiple adjacent delimiters into one",
    },
  },
  cat: {
    summary: "concatenate files and print them",
    flags: {
      n: "number every output line",
      A: "show non-printing characters, tabs and line ends",
      b: "number non-blank output lines",
    },
  },
  du: {
    summary: "estimate file and directory disk usage",
    takesValue: ["-max-depth"],
    flags: {
      h: "human-readable sizes (K, M, G)",
      s: "show only a total for each argument",
      a: "show sizes for files too, not just directories",
      c: "also print a grand total",
      "-max-depth": "only report directories this many levels deep",
    },
  },
  df: {
    summary: "report free space on mounted filesystems",
    flags: {
      h: "human-readable sizes (K, M, G)",
      T: "also show each filesystem's type",
      i: "report inode usage instead of block usage",
    },
  },
  ping: {
    summary: "test reachability of a host on the network",
    takesValue: ["c", "i", "W"],
    flags: {
      c: "stop after sending this many packets",
      i: "wait this many seconds between packets",
      W: "time to wait for a reply, in seconds",
    },
  },
  dd: {
    summary: "copy and convert data block by block",
    flags: {
      "if": "read from this input file",
      of: "write to this output file",
      bs: "read and write this many bytes at a time",
      count: "copy only this many blocks",
      status: "control how progress is reported",
    },
  },
  make: {
    summary: "build targets according to a Makefile",
    takesValue: ["j", "f", "C"],
    flags: {
      j: "run this many recipe jobs in parallel",
      f: "use the given file instead of Makefile",
      C: "change to this directory first",
      B: "unconditionally rebuild every target",
      n: "dry run — print recipes without running them",
    },
  },
  pip: {
    summary: "the Python package installer",
    subcommands: {
      install: "install packages",
      uninstall: "remove packages",
      list: "list installed packages",
      show: "show details about an installed package",
      freeze: "output installed packages in requirements format",
      download: "download packages without installing",
      wheel: "build wheel archives from requirements",
      check: "verify installed packages have compatible dependencies",
    },
    takesValue: ["r", "-r", "--requirement", "e", "-e", "--editable", "-c", "--constraint", "--index-url", "-i", "--extra-index-url", "--target", "-t"],
    flags: {
      r: "install from the given requirements file",
      e: "install a project in editable/development mode",
      U: "upgrade packages to the newest available version",
      "--requirement": "install from the given requirements file",
      "--editable": "install a project in editable/development mode",
      "--upgrade": "upgrade packages to the newest available version",
      "--user": "install to the per-user site-packages directory",
      "--no-cache-dir": "disable the wheel/download cache",
      "--no-deps": "don't install package dependencies",
      "--force-reinstall": "reinstall even if already up to date",
      "--index-url": "base URL of the package index to use",
      "--extra-index-url": "an additional package index to consult",
      "--target": "install packages into this directory",
      "--break-system-packages": "allow modifying an externally-managed environment",
    },
  },
  python: {
    summary: "the Python interpreter",
    takesValue: ["m", "c", "-W", "-X"],
    flags: {
      m: "run the named library module as a script",
      c: "run the given program passed as a string",
      i: "drop into interactive mode after running the script",
      u: "force stdout/stderr to be unbuffered",
      O: "enable basic optimizations (assert stripped)",
      B: "don't write .pyc bytecode files",
      E: "ignore PYTHON* environment variables",
      "--version": "print the Python version and exit",
    },
  },
  go: {
    summary: "the Go toolchain — build, test, and manage Go code",
    subcommands: {
      build: "compile packages and dependencies",
      run: "compile and run a Go program",
      test: "run package tests",
      get: "add or update a dependency in go.mod",
      install: "compile and install a package's binary",
      mod: "manage the module's go.mod file",
      fmt: "reformat source with gofmt",
      vet: "report likely mistakes in packages",
      generate: "run code generators marked with go:generate",
      clean: "remove object and cached files",
    },
    takesValue: ["o", "-o", "-tags", "-ldflags", "-run", "-count"],
    flags: {
      o: "write the output binary to this path",
      v: "print the names of packages as they compile",
      "-race": "enable the data-race detector",
      "-tags": "build tags to consider satisfied",
      "-ldflags": "flags to pass to the linker",
      "-run": "run only tests matching this regexp",
      "-count": "run each test this many times (use 1 to disable caching)",
      "-cover": "enable coverage analysis",
      "-bench": "run benchmarks matching this regexp",
    },
    subFlags: {
      mod: { init: "create a new go.mod", tidy: "add missing and remove unused modules", download: "download modules to the cache" },
    },
    subSubcommands: {
      mod: {
        init: "create a new go.mod in the current directory",
        tidy: "add missing and remove unused module requirements",
        download: "download modules to the local cache",
        vendor: "copy dependencies into a vendor directory",
      },
    },
  },
  cargo: {
    summary: "the Rust package manager and build tool",
    subcommands: {
      build: "compile the current package",
      run: "build and run a binary target",
      test: "run the package's tests",
      check: "type-check without producing a binary",
      add: "add a dependency to Cargo.toml",
      remove: "remove a dependency from Cargo.toml",
      update: "update dependencies in Cargo.lock",
      publish: "upload the crate to a registry (crates.io)",
      install: "build and install a Rust binary",
      new: "create a new cargo package",
      init: "create a cargo package in an existing directory",
      clippy: "run the Clippy linter",
      fmt: "format the code with rustfmt",
      bench: "run benchmarks",
    },
    takesValue: ["-p", "--package", "--bin", "--example", "--features", "--target"],
    flags: {
      "--release": "build with optimizations (the release profile)",
      "--all-features": "activate all Cargo features",
      "--no-default-features": "do not activate the default feature set",
      "--features": "space/comma-separated list of features to activate",
      "--workspace": "run the command for every package in the workspace",
      "--package": "run the command for this package only",
      "--bin": "build/run only this binary target",
      "--example": "build/run this example target",
      "--target": "build for the given target triple",
      "--locked": "require an up-to-date Cargo.lock and don't change it",
      "--offline": "run without accessing the network",
    },
  },
  gcloud: {
    summary: "the Google Cloud CLI",
    subcommands: {
      compute: "manage Compute Engine resources",
      storage: "manage Cloud Storage buckets and objects",
      auth: "manage credentials and authorization",
      config: "manage the local gcloud configuration",
      projects: "manage Cloud projects",
      container: "manage Kubernetes Engine (GKE) clusters",
      functions: "manage Cloud Functions",
      run: "manage Cloud Run services",
      iam: "manage identity and access management",
      app: "manage App Engine applications",
    },
    takesValue: ["--project", "--region", "--zone", "--account", "--format", "--configuration"],
    flags: {
      "--project": "the Cloud project ID to operate on",
      "--region": "the region to operate in",
      "--zone": "the zone to operate in",
      "--account": "the account to run the command as",
      "--format": "output format (json, yaml, table, value, …)",
      "--quiet": "disable interactive prompts, use defaults",
      "--recursive": "recurse into directories (e.g. storage copies)",
      "--impersonate-service-account": "run the command as this service account",
    },
  },
  terraform: {
    summary: "infrastructure-as-code provisioning tool",
    subcommands: {
      init: "initialize a working directory and download providers",
      plan: "show the changes required to reach the desired state",
      apply: "create or update infrastructure to match the config",
      destroy: "remove all managed infrastructure",
      validate: "check whether the configuration is syntactically valid",
      fmt: "rewrite config files to the canonical format",
      output: "read an output value from state",
      state: "advanced state management",
      import: "associate existing infrastructure with a resource",
      workspace: "manage multiple named states",
    },
    takesValue: ["-var", "-var-file", "-target", "-state", "-out"],
    flags: {
      "-auto-approve": "skip the interactive approval prompt",
      "-var": "set a single input variable (name=value)",
      "-var-file": "load input variables from this file",
      "-target": "limit the operation to this resource address",
      "-out": "write the generated plan to this file",
      "-no-color": "disable colored output",
      "-json": "produce machine-readable JSON output",
      "-upgrade": "upgrade provider/module versions during init",
    },
  },
  gh: {
    summary: "the official GitHub CLI",
    subcommands: {
      repo: "manage repositories (create, clone, view, fork)",
      pr: "manage pull requests (create, checkout, merge, …)",
      issue: "manage issues (create, list, close, …)",
      release: "manage releases",
      run: "view and manage GitHub Actions runs",
      workflow: "view and manage GitHub Actions workflows",
      auth: "authenticate gh and manage credentials",
      api: "make an authenticated GitHub API request",
      gist: "manage gists",
      secret: "manage repository/organization secrets",
    },
    takesValue: ["-R", "--repo", "-t", "--title", "-b", "--body", "-F", "--field", "-f"],
    flags: {
      R: "operate on the given owner/repo instead of the current one",
      "--repo": "operate on the given owner/repo instead of the current one",
      "--title": "set the title (PR/issue/release)",
      "--body": "set the body text (PR/issue/release)",
      "--web": "open the relevant page in a browser",
      "--json": "output selected fields as JSON",
      "--jq": "filter JSON output with a jq expression",
    },
    subFlags: {
      pr: { "-B": "the base branch to merge into", "-d": "delete the branch after merge", "-s": "squash the commits when merging" },
    },
  },
  yarn: {
    summary: "an alternative Node.js package manager",
    subcommands: {
      install: "install project dependencies",
      add: "add a dependency to the project",
      remove: "remove a dependency",
      run: "run a script defined in package.json",
      build: "run the build script",
      test: "run the test script",
      upgrade: "upgrade dependencies to their latest allowed versions",
      dlx: "download and run a package one-off (Yarn Berry)",
      why: "explain why a package is installed",
    },
    takesValue: [],
    flags: {
      D: "add to devDependencies",
      "--dev": "add to devDependencies",
      "--frozen-lockfile": "fail rather than update the lockfile (Yarn 1)",
      "--immutable": "fail if the lockfile would change (Yarn Berry)",
      "--production": "skip devDependencies",
      "--global": "operate on the global package set",
    },
  },
  pnpm: {
    summary: "a fast, disk-efficient Node.js package manager",
    subcommands: {
      install: "install project dependencies",
      add: "add a dependency to the project",
      remove: "remove a dependency",
      run: "run a script defined in package.json",
      dlx: "download and run a package one-off",
      exec: "run a command from a local dependency's binaries",
      update: "update dependencies to newer allowed versions",
      why: "show which packages depend on a given one",
    },
    takesValue: ["--filter", "-C", "--dir"],
    flags: {
      D: "add to devDependencies",
      "--save-dev": "add to devDependencies",
      "--frozen-lockfile": "fail rather than update the lockfile",
      "--prod": "install only production dependencies",
      "-r": "run the command in every workspace package (recursive)",
      "--recursive": "run the command in every workspace package",
      "--filter": "restrict the command to matching workspace packages",
      "-g": "operate on globally-installed packages",
      "--global": "operate on globally-installed packages",
    },
  },
  zip: {
    summary: "package and compress files into a .zip archive",
    takesValue: ["x", "-x", "i", "-i"],
    flags: {
      r: "recurse into directories",
      q: "quiet — suppress normal output",
      v: "verbose output (or print version when used alone)",
      "0": "store only — no compression",
      "9": "compress better (slowest)",
      e: "encrypt the archive, prompting for a password",
      m: "move files into the zip — delete the originals after adding",
      j: "junk paths — store just the file names, not directories",
      u: "update — add new files and replace changed ones",
      x: "exclude files matching the given pattern",
      i: "include only files matching the given pattern",
    },
  },
  sudo: {
    summary: "run a command as another user (root by default)",
    takesValue: ["u", "g", "p"],
    flags: {
      u: "run as this user instead of root",
      g: "run as this group",
      i: "start a fresh login shell as the target user",
      s: "run a shell as the target user",
      k: "invalidate the cached credentials (force a re-prompt next time)",
      l: "list the commands you're allowed to run",
      b: "run the command in the background",
      E: "preserve your current environment variables",
      H: "set HOME to the target user's home directory",
      n: "non-interactive — fail rather than prompt for a password",
      p: "use this custom password prompt",
    },
  },
  touch: {
    summary: "create empty files, or update a file's access/modification times",
    takesValue: ["d", "t", "r"],
    flags: {
      a: "change only the access time",
      m: "change only the modification time",
      c: "don't create the file if it doesn't already exist",
      r: "use this reference file's timestamps instead of now",
      d: "set the time from a human-readable date string",
      t: "set the time from a [[CC]YY]MMDDhhmm[.ss] stamp",
    },
  },
  less: {
    summary: "view text one screen at a time (a pager)",
    takesValue: ["x"],
    flags: {
      N: "show line numbers",
      S: "chop long lines instead of wrapping them",
      i: "ignore case in searches",
      F: "quit immediately if the content fits on one screen",
      R: "pass ANSI color escape sequences through unchanged",
      X: "don't clear the screen on exit",
      x: "set the tab width in columns",
    },
  },
  date: {
    summary: "print or set the system date and time",
    takesValue: ["d", "r", "s"],
    flags: {
      u: "use UTC instead of local time",
      d: "print the given date string instead of the current time",
      s: "set the system clock to the given time",
      r: "show the last-modified time of the given file",
      I: "output in ISO 8601 format",
      R: "output in RFC 5322 format (for email headers)",
    },
  },
  echo: {
    summary: "print text to standard output",
    takesValue: [],
    flags: {
      n: "don't print the trailing newline",
      e: "interpret backslash escapes like \n and \t",
      E: "don't interpret backslash escapes (the default)",
    },
  },
  printf: {
    summary: "format and print data using a printf-style template",
    takesValue: [],
    flags: {
      v: "store the output in a shell variable instead of printing it",
    },
  },
  base64: {
    summary: "encode or decode data in Base64",
    takesValue: ["w"],
    flags: {
      d: "decode Base64 input instead of encoding",
      i: "ignore non-alphabet characters while decoding",
      w: "wrap encoded lines after this many characters (0 = no wrap)",
    },
  },
  env: {
    summary: "show the environment, or run a command with a modified one",
    takesValue: ["u", "C"],
    flags: {
      i: "start with a completely empty environment",
      u: "remove this variable from the environment",
      "0": "end each output line with NUL instead of a newline",
      C: "change to this directory before running the command",
    },
  },
  dig: {
    summary: "query DNS name servers (a DNS lookup tool)",
    takesValue: ["t", "p", "x", "b"],
    flags: {
      x: "do a reverse lookup on the given IP address",
      t: "query for this record type (A, AAAA, MX, TXT, NS…)",
      p: "query the server on this port instead of 53",
      "4": "use IPv4 transport only",
      "6": "use IPv6 transport only",
      b: "send the query from this source address",
    },
  },
  watch: {
    summary: "run a command repeatedly and watch its output update",
    takesValue: ["n"],
    flags: {
      n: "set the interval between runs, in seconds",
      d: "highlight what changed between updates",
      t: "hide the header showing the interval and command",
      g: "exit as soon as the output first changes",
      b: "beep if the command exits non-zero",
      e: "freeze and wait for a key if the command errors",
    },
  },
  uname: {
    summary: "print system and kernel information",
    takesValue: [],
    flags: {
      a: "print everything",
      s: "the kernel name",
      r: "the kernel release",
      v: "the kernel version",
      m: "the machine hardware name",
      n: "the network node hostname",
      o: "the operating system",
      p: "the processor type",
    },
  },
  sha256sum: {
    summary: "compute or verify SHA-256 checksums",
    takesValue: ["c"],
    flags: {
      c: "read checksums from a file and verify them",
      b: "read the files in binary mode",
      t: "read the files in text mode",
      "--quiet": "don't print OK for each file that verifies",
      "--ignore-missing": "don't fail for files that are missing when verifying",
    },
  },
  free: {
    summary: "show memory and swap usage",
    takesValue: ["s", "c"],
    flags: {
      h: "human-readable units (KiB/MiB/GiB)",
      m: "show the amounts in mebibytes",
      g: "show the amounts in gibibytes",
      b: "show the amounts in bytes",
      s: "refresh continuously every N seconds",
      c: "stop after this many refreshes",
      t: "add a line showing the totals",
    },
  },
  top: {
    summary: "show a live, sorted view of running processes",
    takesValue: ["d", "p", "u", "n"],
    flags: {
      d: "set the refresh delay in seconds",
      n: "exit after this many refreshes",
      p: "monitor only these process IDs",
      u: "show only this user's processes",
      b: "batch mode — plain output for logs or pipes",
      i: "hide idle processes",
    },
  },
  mount: {
    summary: "attach a filesystem to the directory tree (or list current mounts)",
    takesValue: ["t", "o"],
    flags: {
      t: "specify the filesystem type (ext4, xfs, nfs…)",
      o: "pass a comma-separated list of mount options",
      a: "mount everything listed in /etc/fstab",
      r: "mount the filesystem read-only",
      w: "mount the filesystem read-write",
      v: "verbose output",
      B: "bind-mount an existing directory somewhere else",
    },
  },
  umount: {
    summary: "detach (unmount) a mounted filesystem",
    takesValue: ["t", "O"],
    flags: {
      a: "unmount every filesystem listed in /etc/mtab",
      f: "force the unmount (useful for an unreachable NFS mount)",
      l: "lazy unmount — detach now, clean up once it is no longer busy",
      r: "if the unmount fails, remount the filesystem read-only instead",
      n: "unmount without writing to /etc/mtab",
      R: "recursively unmount the given directory and everything below it",
      t: "act only on filesystems of the given type",
      v: "verbose output",
      O: "act only on filesystems with the given mount options",
    },
  },
  which: {
    summary: "locate a command — print the full path of the executable that would run",
    flags: {
      a: "print ALL matching executables on PATH, not just the first",
      s: "print nothing; just set exit status (found / not found)",
    },
  },
  whoami: {
    summary: "print the effective user name of the current user",
    flags: {},
  },
  hostname: {
    summary: "show or set the system's host name",
    flags: {
      I: "print all network addresses of the host (space-separated)",
      i: "print the host's IP address(es)",
      f: "print the fully-qualified domain name (FQDN)",
      s: "print the short host name (everything up to the first dot)",
      d: "print the DNS domain name",
      a: "print the host's alias names",
    },
  },
  ifconfig: {
    summary: "configure or display network-interface settings (legacy; prefer `ip`)",
    flags: {
      a: "show all interfaces, including ones that are down",
      s: "short listing, like `netstat -i`",
      v: "verbose — show extra error details",
    },
  },
  "ssh-keygen": {
    summary: "generate, manage and convert SSH authentication keys",
    takesValue: ["t", "b", "C", "f", "N", "R", "F"],
    flags: {
      t: "type of key to create (ed25519, rsa, ecdsa)",
      b: "number of bits in the key",
      C: "comment to attach to the key (often your email)",
      f: "key file to write to or read from",
      N: "new passphrase for the key ('' means no passphrase)",
      p: "change the passphrase of an existing private key",
      y: "read a private key and print its public key",
      l: "show the fingerprint of a key file",
      R: "remove all keys for the given hostname from known_hosts",
      F: "search known_hosts for the given hostname",
      q: "quiet — suppress the usual output",
    },
  },
  stat: {
    summary: "display detailed file status — size, permissions, timestamps, inode",
    takesValue: ["c", "--format", "--printf"],
    flags: {
      c: "use the given custom output format",
      f: "report on the filesystem the file lives on, not the file",
      t: "terse output — one line of raw numbers",
      L: "follow symlinks — stat the file they point to",
      "--format": "use the given output format (add a trailing newline)",
      "--printf": "like --format, but interpret backslash escapes and add no newline",
      "--dereference": "follow symlinks",
    },
  },
  file: {
    summary: "identify a file's type by inspecting its contents, not its name",
    flags: {
      b: "brief — don't print the file name, just the type",
      i: "print a MIME type string instead of human-readable text",
      z: "look inside compressed files",
      L: "follow symlinks",
      s: "read block/character special files (devices) too",
      k: "keep going — report all matches, not just the first",
      "--mime": "print the MIME type",
      "--mime-type": "print only the MIME type (e.g. text/plain)",
    },
  },
  basename: {
    summary: "strip the directory (and optionally a suffix) from a path, leaving the file name",
    takesValue: ["s"],
    flags: {
      a: "treat every argument as a name to strip (process multiple)",
      s: "remove the given trailing suffix from the name",
      z: "end each output line with NUL instead of a newline",
    },
  },
  dirname: {
    summary: "strip the last component from a path, leaving the directory portion",
    flags: {
      z: "end each output line with NUL instead of a newline",
    },
  },
  realpath: {
    summary: "resolve a path to its absolute, symlink-free canonical form",
    takesValue: ["--relative-to", "--relative-base"],
    flags: {
      e: "require every path component to exist (error otherwise)",
      m: "allow missing components — resolve the path anyway",
      s: "don't expand symlinks (only collapse . and .. and slashes)",
      z: "end each output line with NUL instead of a newline",
      "--relative-to": "print the result relative to the given directory",
      "--relative-base": "print relative when under this dir, else absolute",
    },
  },
  md5sum: {
    summary: "compute or verify MD5 checksums (128-bit; use sha256sum for security)",
    flags: {
      c: "read checksums from the given file(s) and verify them",
      b: "read files in binary mode",
      t: "read files in text mode (the default)",
      "--check": "verify checksums listed in a file",
      "--quiet": "with -c, don't print OK for each verified file",
      "--ignore-missing": "with -c, don't fail over files that are missing",
      "--status": "with -c, print nothing — signal the result via exit code",
    },
  },
  tree: {
    summary: "list directory contents as an indented tree",
    takesValue: ["L", "P", "I"],
    flags: {
      L: "descend only this many directory levels deep",
      a: "include hidden files (dotfiles)",
      d: "list directories only",
      f: "print the full path prefix for each entry",
      i: "don't indent — print a flat list (pair with -f)",
      h: "print sizes in human-readable form",
      p: "show the type and permissions of each entry",
      s: "print the size of each file",
      P: "list only files matching the given pattern",
      I: "do NOT list files matching the given pattern",
      "--du": "show each directory's size as the sum of its contents",
      "--dirsfirst": "list directories before files",
    },
  },
  htop: {
    summary: "interactive process and resource viewer (a friendlier `top`)",
    takesValue: ["d", "u", "p", "s"],
    flags: {
      d: "delay between updates, in tenths of a second",
      u: "show only processes owned by the given user",
      p: "monitor only the given PIDs (comma-separated)",
      s: "sort by the given column on startup",
      t: "start in tree view",
      C: "use a monochrome (no-color) scheme",
      H: "hide user threads",
      "--tree": "show processes as a parent/child tree",
    },
  },
  pkill: {
    summary: "signal processes selected by name or attribute — no PID needed",
    takesValue: ["u", "U", "t"],
    flags: {
      f: "match against the full command line, not just the process name",
      u: "match processes with the given effective user",
      U: "match processes with the given real user",
      x: "require an exact match of the process name",
      n: "select only the newest matching process",
      o: "select only the oldest matching process",
      c: "print a count of matches instead of signalling them",
      "9": "SIGKILL — force the matching processes to stop immediately",
      "15": "SIGTERM — politely ask the matching processes to stop",
    },
  },
  killall: {
    summary: "kill all processes matching a given name",
    takesValue: ["u", "s"],
    flags: {
      i: "ask for confirmation before killing each process",
      u: "kill only processes owned by the given user",
      v: "report whether each signal was sent successfully",
      w: "wait for the killed processes to actually die",
      e: "require an exact match for long process names",
      I: "match the process name case-insensitively",
      g: "kill the process group instead of the process",
      s: "send the named signal instead of SIGTERM",
      "9": "SIGKILL — force the matching processes to stop immediately",
    },
  },
  sleep: {
    summary: "pause for a given amount of time before returning",
    flags: {
      "--help": "show usage information and exit",
      "--version": "print version information and exit",
    },
  },
  timeout: {
    summary: "run a command, killing it if it runs longer than a time limit",
    takesValue: ["s", "k", "--signal", "--kill-after"],
    flags: {
      s: "send this signal instead of SIGTERM when time runs out",
      k: "if still alive after this long, follow up with SIGKILL",
      "--signal": "send this signal instead of SIGTERM when time runs out",
      "--kill-after": "if still alive after this long, follow up with SIGKILL",
      "--preserve-status": "exit with the command's own status, not 124",
      "--foreground": "let the command read from the terminal (don't isolate it)",
      v: "verbose — announce when the command is being signalled",
      "--verbose": "verbose — announce when the command is being signalled",
    },
  },
  seq: {
    summary: "print a sequence of numbers, from FIRST to LAST",
    takesValue: ["s", "f", "-w"],
    flags: {
      s: "use this string to separate numbers (default: newline)",
      f: "format each number with this printf-style float format",
      w: "pad numbers with leading zeros to equal width",
      "--separator": "use this string to separate numbers",
      "--format": "format each number with this printf-style float format",
      "--equal-width": "pad numbers with leading zeros to equal width",
    },
  },
  nohup: {
    summary: "run a command immune to hangups, ignoring SIGHUP so it survives logout",
    flags: {
      "--help": "show usage information and exit",
      "--version": "print version information and exit",
    },
  },
  nslookup: {
    summary: "query DNS name servers for a domain's records interactively or in one shot",
    flags: {
      "-type": "query this record type (e.g. -type=MX, -type=NS)",
      "-query": "query this record type (alias of -type)",
      "-debug": "show the full debugging detail of each response",
      "-port": "query the server on this port instead of 53",
    },
  },
  traceroute: {
    summary: "trace the network hops (routers) packets take to reach a host",
    takesValue: ["m", "q", "w", "p", "f"],
    flags: {
      n: "show numeric addresses; don't resolve hop names via DNS",
      I: "use ICMP ECHO probes instead of UDP datagrams",
      T: "use TCP SYN probes (handy through firewalls)",
      m: "set the maximum number of hops (TTL) to probe",
      q: "send this many probe packets per hop (default 3)",
      w: "wait this many seconds for a reply before giving up",
      p: "use this base destination port for probes",
      f: "start probing from this first TTL (hop) instead of 1",
    },
  },
  sha1sum: {
    summary: "compute or check SHA-1 (160-bit) checksums of files",
    flags: {
      c: "read checksums from the files and verify them",
      b: "read files in binary mode",
      t: "read files in text mode (default)",
      "--check": "read checksums from the files and verify them",
      "--quiet": "when checking, don't print OK for each verified file",
      "--status": "when checking, print nothing; signal result via exit code",
      "--ignore-missing": "when checking, don't fail for missing files",
    },
  },
  xz: {
    summary: "compress or decompress files with the LZMA2 algorithm (.xz)",
    takesValue: ["T", "--threads"],
    flags: {
      z: "compress (the default action)",
      d: "decompress",
      k: "keep — don't delete the input file after (de)compressing",
      f: "force overwrite of the output and (de)compress even unusual files",
      c: "write to standard output; leave files unchanged",
      l: "list information about the compressed .xz file",
      t: "test the integrity of the compressed file",
      "9": "use the maximum compression level (slowest, smallest)",
      "0": "use the fastest compression level (largest)",
      e: "use extra effort for a slightly smaller file",
      T: "use this many worker threads (0 = one per CPU)",
      v: "verbose — show progress and stats",
      "--threads": "use this many worker threads (0 = one per CPU)",
      "--keep": "keep — don't delete the input file",
      "--decompress": "decompress",
    },
  },
  bzip2: {
    summary: "compress or decompress files with the Burrows-Wheeler algorithm (.bz2)",
    flags: {
      z: "compress (the default action)",
      d: "decompress",
      k: "keep — don't delete the input file after (de)compressing",
      f: "force overwrite of existing output files",
      c: "write to standard output; leave files unchanged",
      t: "test the integrity of the compressed file",
      "9": "use the largest block size — best compression (default)",
      "1": "use the smallest block size — least memory",
      v: "verbose — show the compression ratio for each file",
      "--decompress": "decompress",
      "--keep": "keep — don't delete the input file",
    },
  },
  paste: {
    summary: "merge lines of files side by side, separated by tabs",
    takesValue: ["d", "--delimiters"],
    flags: {
      d: "use these characters instead of tab to separate columns",
      s: "paste one file at a time — its lines onto a single row",
      z: "treat input and output lines as NUL-terminated",
      "--delimiters": "use these characters instead of tab to separate columns",
      "--serial": "paste one file at a time onto a single row",
    },
  },
  comm: {
    summary: "compare two SORTED files line by line, in three columns",
    flags: {
      "1": "suppress column 1 — lines unique to the first file",
      "2": "suppress column 2 — lines unique to the second file",
      "3": "suppress column 3 — lines common to both files",
      i: "compare lines case-insensitively",
      "--check-order": "fail if either input is not properly sorted",
      "--nocheck-order": "do not check that the input is sorted",
      "--total": "also print a summary count line",
    },
  },
  nl: {
    summary: "number the lines of a file as it writes them out",
    takesValue: ["b", "w", "s", "v", "i"],
    flags: {
      b: "which lines to number: a=all, t=non-empty (default), n=none",
      w: "use this column width for the line numbers",
      s: "put this string between the number and the text",
      v: "start numbering at this value",
      i: "increment the line number by this step",
      n: "number format: ln, rn (default), or rz (zero-padded)",
    },
  },
  tac: {
    summary: "concatenate and print files in reverse — last line first",
    takesValue: ["s", "--separator"],
    flags: {
      s: "use this string as the line separator instead of newline",
      r: "treat the separator as a regular expression",
      b: "attach the separator before, rather than after, each line",
      "--separator": "use this string as the line separator instead of newline",
      "--before": "attach the separator before each line",
    },
  },
  rev: {
    summary: "reverse the order of characters on every line",
    flags: {
      "--help": "show usage information and exit",
      "--version": "print version information and exit",
    },
  },
  "ssh-copy-id": {
    summary: "install your public SSH key into a remote host's authorized_keys",
    takesValue: ["i", "p", "o"],
    flags: {
      i: "use this identity (public key) file",
      p: "connect to this port on the remote host",
      o: "pass this option through to ssh",
      f: "force — copy the key even if it appears to be installed already",
      n: "dry run — show which keys would be installed, but don't",
    },
  },
  sftp: {
    summary: "interactive secure file transfer over SSH",
    takesValue: ["P", "i", "o", "b", "l"],
    flags: {
      P: "connect to this port on the remote host",
      i: "use this identity (private key) file",
      o: "pass this option through to ssh",
      b: "read batch commands from this file (non-interactive)",
      r: "recursively copy entire directories",
      l: "limit the transfer bandwidth (Kbit/s)",
      a: "resume (append to) partial transfers of existing files",
    },
  },
  vim: {
    summary: "Vi IMproved — a modal terminal text editor",
    takesValue: ["u", "c", "S"],
    flags: {
      R: "open the file read-only (view mode)",
      m: "disable modifications (writing is turned off)",
      d: "start in diff mode, like vimdiff",
      o: "open the files in horizontally split windows",
      O: "open the files in vertically split windows",
      p: "open the files in separate tabs",
      u: "use this config file instead of ~/.vimrc",
      c: "run this Ex command after loading the first file",
      S: "source this session/script file after loading",
      e: "start in line-based Ex mode",
    },
  },
  nano: {
    summary: "a simple, friendly terminal text editor",
    takesValue: ["T", "r", "Y"],
    flags: {
      l: "show line numbers in the left margin",
      i: "automatically indent new lines to match the previous one",
      m: "enable mouse support",
      w: "don't hard-wrap long lines",
      c: "constantly show the cursor position",
      B: "save a backup of the previous version of the file",
      S: "use smooth (line-by-line) scrolling",
      T: "set the width of a tab in columns",
      r: "hard-wrap lines at this column",
      Y: "use this syntax-highlighting definition",
      v: "open the file in view (read-only) mode",
    },
  },
  man: {
    summary: "display the on-line manual page for a command",
    takesValue: ["M", "P"],
    flags: {
      k: "search the short descriptions of all pages (apropos)",
      f: "show the one-line description of a page (whatis)",
      a: "show all matching manual pages, not just the first",
      w: "print the file location of the manual page instead of showing it",
      K: "search for a string in the full text of all pages",
      M: "look for pages in this manual-path directory",
      P: "use this program as the pager",
    },
  },
  id: {
    summary: "print user and group identity (UID, GID, groups)",
    flags: {
      u: "print only the effective user ID",
      g: "print only the effective (primary) group ID",
      G: "print all group IDs the user belongs to",
      n: "print names instead of numeric IDs",
      r: "print the real ID instead of the effective one",
    },
  },
  who: {
    summary: "show who is currently logged in",
    flags: {
      a: "show all available information",
      b: "show the time of the last system boot",
      H: "print a header row of column titles",
      q: "print only login names and a count of logged-in users",
      u: "include how long each user has been idle",
      m: "show information only for the current terminal",
      r: "show the current runlevel",
    },
  },
  uptime: {
    summary: "show how long the system has been running plus load averages",
    flags: {
      p: "show the uptime in a pretty, human-readable form",
      s: "show the date and time the system booted",
    },
  },
  su: {
    summary: "switch to another user and start a shell (defaults to root)",
    takesValue: ["c", "s"],
    flags: {
      l: "start a login shell, giving the target user's full environment",
      c: "run this single command as the target user, then exit",
      s: "run this shell instead of the target user's default",
      p: "preserve the current environment instead of resetting it",
    },
  },
  gpg: {
    summary: "GNU Privacy Guard — encrypt, decrypt, and sign data",
    takesValue: ["o", "r", "u"],
    flags: {
      c: "encrypt with a symmetric passphrase (no keys needed)",
      e: "encrypt the input for one or more recipients",
      d: "decrypt the input",
      s: "make a signature",
      a: "produce ASCII-armored (text) output instead of binary",
      b: "make a detached signature (separate .sig file)",
      v: "verbose output",
      o: "write output to this file",
      r: "encrypt for this recipient (key ID or email)",
      u: "sign using this local key",
      "--gen-key": "interactively generate a new key pair",
      "--full-generate-key": "generate a key pair with all options prompted",
      "--list-keys": "list the public keys in your keyring",
      "--export": "export a public key",
      "--import": "import keys from a file",
      "--verify": "verify a signature",
    },
  },
  tmux: {
    summary: "terminal multiplexer — persistent sessions with split panes",
    takesValue: ["t", "s", "L", "f"],
    subcommands: {
      new: "create a new session",
      "new-session": "create a new session",
      attach: "attach to an existing session",
      "attach-session": "attach to an existing session",
      ls: "list sessions",
      "list-sessions": "list sessions",
      "kill-session": "terminate a single session",
      "kill-server": "terminate the tmux server and every session",
      "rename-session": "rename a session",
      "split-window": "split the current pane into two",
      detach: "detach the client from its session",
    },
    flags: {
      t: "target session or window",
      s: "name for a new session",
      d: "start the session detached (or detach other clients)",
      a: "attach to an existing session",
      L: "use this socket name for the server",
      f: "use this alternate config file",
    },
  },
  lsblk: {
    summary: "list block devices (disks and their partitions) as a tree",
    takesValue: ["o"],
    flags: {
      a: "also list empty (zero-size) devices",
      f: "show filesystem info — type, label, and UUID",
      m: "show permission info — owner, group, and mode",
      p: "print full device paths (/dev/sda) instead of names",
      b: "print sizes in bytes rather than human units",
      l: "use a flat list instead of the tree layout",
      n: "don't print the header line",
      o: "choose exactly which columns to show",
      S: "list only SCSI devices",
    },
  },
  dmesg: {
    summary: "print or control the kernel ring buffer (boot and driver messages)",
    takesValue: ["l", "f"],
    flags: {
      H: "human-readable output with colors and relative time",
      w: "wait and keep printing new messages as they arrive (follow)",
      T: "show human-readable timestamps",
      c: "clear the ring buffer after printing its contents",
      l: "restrict output to these log levels (e.g. err,warn)",
      f: "restrict output to these facilities (e.g. kern)",
      k: "print kernel messages",
      u: "print userspace messages",
      x: "show the facility and level of each line as text",
    },
  },
  mktemp: {
    summary: "safely create a unique temporary file or directory and print its name",
    takesValue: ["p", "--suffix"],
    flags: {
      d: "create a directory instead of a file",
      u: "only print an unused name without creating anything (unsafe)",
      q: "suppress diagnostics if creation fails",
      p: "create the file/dir in this directory instead of $TMPDIR",
      t: "interpret the template relative to the temp directory",
      "--suffix": "append this suffix to the generated name",
    },
  },
  gunzip: {
    summary: "decompress .gz files created by gzip",
    flags: {
      k: "keep (don't delete) the compressed input file",
      c: "write the result to stdout and keep the original",
      f: "force decompression, overwriting existing files",
      v: "verbose — show name and compression ratio",
      t: "test the integrity of the compressed file without extracting",
      l: "list the contents and compression stats of an archive",
      r: "recurse into directories, decompressing every file",
    },
  },
  history: {
    summary: "display or manage the shell command history (shell builtin)",
    takesValue: ["d"],
    flags: {
      c: "clear the entire history list",
      d: "delete the history entry at this position",
      a: "append the new history lines to the history file",
      r: "read the history file and append it to the current list",
      w: "write the current history out to the history file",
      n: "read the history lines not already read from the file",
    },
  },
  alias: {
    summary: "define or display command shortcuts (shell builtin)",
    flags: {
      p: "print all defined aliases in a reusable form",
    },
  },
  export: {
    summary: "mark shell variables for export to child processes (shell builtin)",
    flags: {
      p: "display all exported variables in a reusable form",
      n: "remove the export property from the named variables",
      f: "treat the names as shell functions rather than variables",
    },
  },
  passwd: {
    summary: "change a user's password (and password-aging settings)",
    takesValue: ["n", "x", "w", "i"],
    flags: {
      l: "lock the account's password (prefix it with !)",
      u: "unlock a locked password",
      d: "delete the password, leaving the account passwordless",
      e: "expire the password now, forcing a change at next login",
      S: "show password status (locked/usable, last change)",
      a: "with -S, report status for all accounts",
      n: "minimum days between password changes",
      x: "maximum days a password stays valid",
      w: "days of warning before a password expires",
      i: "days after expiry until the account is disabled",
    },
  },
  useradd: {
    summary: "create a new user account",
    takesValue: ["s", "d", "g", "G", "u", "c", "e", "p", "k", "f",
      "--shell", "--home-dir", "--gid", "--groups", "--uid", "--comment"],
    flags: {
      m: "create the user's home directory",
      M: "do not create a home directory",
      r: "create a system account (low UID, no aging)",
      s: "login shell for the account",
      d: "home directory path",
      g: "primary group (name or GID)",
      G: "supplementary groups, comma-separated",
      u: "specific numeric user ID",
      c: "comment / full-name (GECOS) field",
      e: "account expiration date (YYYY-MM-DD)",
      p: "pre-encrypted password (not plain text)",
      k: "skeleton directory to copy into the new home",
      N: "do not create a group with the same name as the user",
      "--system": "create a system account",
      "--create-home": "create the home directory",
      "--shell": "login shell for the account",
      "--home-dir": "home directory path",
      "--groups": "supplementary groups, comma-separated",
    },
  },
  usermod: {
    summary: "modify an existing user account",
    takesValue: ["l", "G", "s", "d", "u", "g", "c", "e", "f",
      "--login", "--groups", "--shell", "--home", "--uid", "--gid"],
    flags: {
      l: "change the login name",
      G: "set supplementary groups (replaces the list unless -a)",
      a: "append to groups instead of replacing (use with -G)",
      s: "change the login shell",
      d: "change the home directory path",
      m: "move the contents of the old home to the new one (with -d)",
      L: "lock the account's password",
      U: "unlock the account's password",
      u: "change the numeric user ID",
      g: "change the primary group",
      c: "change the comment / full-name field",
      e: "change the account expiration date",
      "--append": "append to groups instead of replacing (use with -G)",
      "--groups": "set supplementary groups",
      "--login": "change the login name",
      "--shell": "change the login shell",
      "--home": "change the home directory path",
    },
  },
  groupadd: {
    summary: "create a new group",
    takesValue: ["g", "--gid"],
    flags: {
      g: "specific numeric group ID",
      r: "create a system group",
      f: "exit successfully if the group already exists",
      o: "allow creating a group with a duplicate (non-unique) GID",
      "--system": "create a system group",
      "--gid": "specific numeric group ID",
    },
  },
  lscpu: {
    summary: "display information about the CPU architecture",
    flags: {
      e: "extended, human-readable per-CPU table",
      p: "parseable (CSV) per-CPU output",
      a: "print both online and offline CPUs",
      b: "print only online CPUs",
      c: "print only offline CPUs",
      x: "show CPU masks in hexadecimal",
      J: "output in JSON",
      "--extended": "extended, human-readable per-CPU table",
      "--parse": "parseable (CSV) per-CPU output",
      "--json": "output in JSON",
    },
  },
  lspci: {
    summary: "list all PCI devices",
    takesValue: ["s", "d"],
    flags: {
      v: "verbose — more detail per device (repeat for more)",
      n: "show numeric vendor/device IDs instead of names",
      k: "show the kernel driver and modules handling each device",
      m: "machine-readable output",
      t: "show devices as a bus tree",
      s: "select a device by [[[[domain:]bus:]slot][.func]]",
      d: "select devices by [vendor]:[device] ID",
      x: "dump the configuration space in hex",
    },
  },
  lsusb: {
    summary: "list USB buses and the devices connected to them",
    takesValue: ["s", "d"],
    flags: {
      v: "verbose — full descriptor details per device",
      t: "show devices as a hierarchical tree",
      s: "show only a device on the given [bus]:[devnum]",
      d: "show only devices with the given [vendor]:[product] ID",
    },
  },
  lsmod: {
    summary: "show the status of loaded kernel modules (reads /proc/modules)",
    flags: {},
  },
  modprobe: {
    summary: "add or remove modules from the Linux kernel",
    flags: {
      r: "remove (unload) the module instead of loading it",
      a: "insert all modules named on the command line",
      v: "verbose — print what is being done",
      n: "dry run — show actions without applying them",
      f: "force load/unload, ignoring version checks",
      q: "quiet — suppress error messages for missing modules",
      "--remove": "remove (unload) the module",
      "--dry-run": "show actions without applying them",
    },
  },
  shuf: {
    summary: "write a random permutation of its input lines",
    takesValue: ["n", "o", "i", "--head-count", "--output", "--input-range"],
    flags: {
      e: "treat each argument as an input line (echo mode)",
      n: "output at most this many lines",
      o: "write the result to this file instead of stdout",
      r: "allow lines to repeat in the output",
      i: "shuffle the integers in this LO-HI range",
      z: "line delimiter is NUL, not newline",
      "--head-count": "output at most this many lines",
      "--output": "write the result to this file",
      "--input-range": "shuffle the integers in this LO-HI range",
      "--repeat": "allow lines to repeat in the output",
    },
  },
  split: {
    summary: "split a file into fixed-size or fixed-count pieces",
    takesValue: ["l", "b", "n", "a", "C", "--lines", "--bytes",
      "--number", "--suffix-length", "--line-bytes", "--additional-suffix"],
    flags: {
      l: "put this many lines in each output file",
      b: "put this many bytes in each output file (accepts K/M/G)",
      n: "split into this many equal chunks",
      d: "use numeric suffixes (00, 01, …) instead of letters",
      a: "length of the generated suffixes",
      C: "at most this many bytes per file, but keep lines whole",
      x: "use hexadecimal suffixes",
      "--lines": "put this many lines in each output file",
      "--bytes": "put this many bytes in each output file",
      "--number": "split into this many equal chunks",
      "--suffix-length": "length of the generated suffixes",
      "--additional-suffix": "append this suffix to output file names",
    },
  },
  strings: {
    summary: "print the printable character sequences found in a file",
    takesValue: ["n", "t", "e", "--bytes", "--radix", "--encoding"],
    flags: {
      a: "scan the entire file, not just loadable sections",
      n: "minimum string length to report (default 4)",
      t: "print the offset of each string (o/x/d radix)",
      f: "print the file name before each string",
      e: "select the character encoding (s/b/l/B/L)",
      "--bytes": "minimum string length to report",
      "--radix": "print the offset of each string (o/x/d)",
      "--encoding": "select the character encoding",
    },
  },
  ldd: {
    summary: "print the shared libraries a program or library depends on",
    flags: {
      v: "verbose — print all information, including symbol versioning",
      u: "print unused direct dependencies",
      r: "perform relocations for both data and functions",
      d: "perform relocations for data objects",
    },
  },
  screen: {
    summary: "terminal multiplexer — detachable sessions that survive logout",
    takesValue: ["S", "p", "t"],
    flags: {
      S: "name the new session",
      r: "reattach to a detached session",
      R: "reattach if possible, otherwise start a new session",
      d: "detach a session (with -r, detach elsewhere then reattach)",
      D: "detach and log out the remote session, then reattach",
      x: "attach to a session that is not detached (multi-attach)",
      m: "force a new session even when one exists (with -d = detached)",
    },
  },
  zcat: {
    summary: "decompress gzip-compressed files and write the result to stdout",
    flags: {
      f: "force — read even from a terminal or non-gzip input",
      q: "suppress warning messages",
    },
  },
  sha512sum: {
    summary: "compute or verify SHA-512 checksums",
    flags: {
      c: "read checksums from the file(s) and verify them",
      b: "read files in binary mode",
      t: "read files in text mode",
      q: "with -c, print nothing; signal failure via exit status",
      w: "with -c, warn about improperly formatted checksum lines",
      "--check": "read checksums from the file(s) and verify them",
      "--quiet": "with -c, print nothing; signal failure via exit status",
    },
  },
  iptables: {
    summary:
      "administer the Linux kernel IPv4 packet-filter rules (netfilter firewall)",
    takesValue: [
      "A", "I", "D", "P", "p", "s", "d", "j", "i", "o", "m", "t",
      "--dport", "--sport", "--state",
    ],
    flags: {
      A: "append a rule to the end of the given chain",
      I: "insert a rule at a position in a chain (default: the top)",
      D: "delete a matching rule from a chain",
      L: "list all rules in a chain",
      F: "flush — delete every rule in a chain",
      N: "create a new user-defined chain",
      X: "delete an empty user-defined chain",
      P: "set the default policy (ACCEPT/DROP) for a built-in chain",
      p: "match a protocol (tcp, udp, icmp, ...)",
      s: "match a source address or subnet",
      d: "match a destination address or subnet",
      j: "jump to a target (ACCEPT, DROP, REJECT, ...) on a match",
      i: "match the input network interface",
      o: "match the output network interface",
      m: "load an extension match module (e.g. state, conntrack)",
      n: "numeric output — don't resolve host names or ports",
      v: "verbose output",
      t: "operate on the given table (filter, nat, mangle, raw)",
      "--dport": "match the destination port",
      "--sport": "match the source port",
      "--state": "match connection state (NEW, ESTABLISHED, RELATED)",
      "--line-numbers": "show rule line numbers when listing",
    },
  },
  ufw: {
    summary:
      "Uncomplicated Firewall — a friendly front-end for the iptables firewall",
    subcommands: {
      enable: "turn the firewall on (and at boot)",
      disable: "turn the firewall off",
      allow: "add a rule permitting traffic",
      deny: "add a rule silently dropping traffic",
      reject: "add a rule rejecting traffic (sends an error back)",
      delete: "remove a previously added rule",
      status: "show the firewall state and active rules",
      reload: "reload the firewall rules",
      reset: "disable and reset to factory defaults",
      default: "set the default policy for incoming/outgoing traffic",
      limit: "allow but rate-limit connections (brute-force protection)",
      logging: "set the logging level",
    },
    flags: {
      "--dry-run": "show the resulting rule set without applying it",
      "--force": "apply without the interactive confirmation prompt",
    },
  },
  "firewall-cmd": {
    summary:
      "manage firewalld — the dynamic firewall daemon on RHEL/Fedora systems",
    takesValue: [
      "--zone", "--add-port", "--remove-port", "--add-service",
      "--remove-service", "--add-rich-rule",
    ],
    flags: {
      "--zone": "operate on the given zone",
      "--add-port": "open a port (e.g. 80/tcp) in the zone",
      "--remove-port": "close a previously opened port",
      "--add-service": "allow a named service (e.g. http, ssh)",
      "--remove-service": "disallow a named service",
      "--add-rich-rule": "add a fine-grained 'rich' rule",
      "--list-all": "show every setting for the zone",
      "--permanent": "make the change persist across reloads/reboots",
      "--reload": "reload rules from the permanent configuration",
      "--state": "report whether firewalld is running",
      "--get-zones": "list the available zones",
      "--get-active-zones": "list zones that have interfaces bound to them",
    },
  },
  strace: {
    summary: "trace the system calls and signals a process makes",
    takesValue: ["e", "p", "o", "s"],
    flags: {
      f: "also trace child processes as they are forked",
      e: "filter which system calls or events to trace",
      p: "attach to and trace an already-running PID",
      o: "write the trace to a file instead of standard error",
      c: "count time, calls and errors per syscall, print a summary",
      t: "prefix each line with the time of day",
      T: "show the time spent inside each system call",
      s: "set the maximum length of printed strings (default 32)",
      v: "verbose — print unabbreviated structs, env, etc.",
      y: "print paths for file-descriptor arguments",
    },
  },
  ltrace: {
    summary: "trace the library (and optionally system) calls a program makes",
    takesValue: ["e", "p", "o", "s"],
    flags: {
      f: "also trace child processes",
      e: "filter which library calls to trace",
      p: "attach to and trace an already-running PID",
      o: "write the trace to a file instead of standard error",
      c: "summarize call counts and time on exit",
      S: "also display system calls",
      s: "set the maximum length of printed strings",
    },
  },
  "systemd-analyze": {
    summary: "inspect and profile systemd boot performance and unit state",
    subcommands: {
      time: "show how long firmware, loader, kernel and userspace took to boot",
      blame: "list units ordered by how long they took to initialise",
      "critical-chain": "show the time-critical chain of units at boot",
      plot: "write an SVG timeline of the boot to standard output",
      dump: "print the internal server state",
      verify: "check unit files for errors",
      security: "score the sandboxing/exposure of a service unit",
    },
    flags: {
      "--user": "operate on the per-user manager, not the system manager",
      "--no-pager": "do not pipe output into a pager",
    },
  },
  hostnamectl: {
    summary: "query and change the system hostname and related metadata",
    subcommands: {
      status: "show the current hostname and machine information",
      "set-hostname": "set the system hostname",
      "set-icon-name": "set the icon name shown in graphical tools",
      "set-chassis": "set the chassis type (laptop, server, vm, ...)",
      "set-location": "set a free-form location string",
    },
    flags: {
      "--static": "operate on the static (persistent) hostname",
      "--pretty": "operate on the pretty (free-form) hostname",
      "--transient": "operate on the transient (runtime) hostname",
      "--no-ask-password": "do not prompt for authentication",
    },
  },
  timedatectl: {
    summary: "query and change the system clock, time zone and NTP settings",
    subcommands: {
      status: "show the current time, time zone and NTP state",
      "set-time": "set the system clock to the given date/time",
      "set-timezone": "set the system time zone",
      "list-timezones": "list the known time-zone names",
      "set-ntp": "enable or disable network time synchronisation",
      "set-local-rtc": "store the hardware clock in local time (vs UTC)",
      "timesync-status": "show details of the running time-sync service",
    },
    flags: {
      "--no-pager": "do not pipe output into a pager",
      "--adjust-system-clock": "with set-local-rtc, also update the system clock",
    },
  },
  nice: {
    summary: "run a program with a modified scheduling priority (niceness)",
    takesValue: ["n", "--adjustment"],
    flags: {
      n: "set the niceness (-20 = highest priority .. 19 = lowest)",
      "--adjustment": "set the niceness increment",
    },
  },
  renice: {
    summary: "change the scheduling priority of already-running processes",
    takesValue: ["n"],
    flags: {
      n: "the new absolute niceness value",
      p: "interpret the following arguments as process IDs",
      g: "interpret the following arguments as process group IDs",
      u: "interpret the following arguments as user names",
    },
  },
  taskset: {
    summary: "set or read a process's CPU affinity (which cores it may use)",
    takesValue: ["c"],
    flags: {
      p: "operate on an existing PID instead of launching a command",
      c: "give the CPU list as numbers, e.g. 0,2,5-7 (not a hex mask)",
      a: "with -p, apply to all threads of the process",
    },
  },
  at: {
    summary: "schedule a command to run once at a specified later time",
    takesValue: ["f", "q"],
    flags: {
      f: "read the job from a file instead of standard input",
      m: "mail the user on completion, even with no output",
      l: "list the pending jobs (same as atq)",
      d: "delete a job by its number (same as atrm)",
      c: "print the named jobs to standard output",
      q: "place the job in the named queue",
    },
  },
  fold: {
    summary: "wrap each input line to a given width",
    takesValue: ["w", "--width"],
    flags: {
      w: "set the maximum line width (default 80 columns)",
      s: "break at spaces so words are not split",
      b: "count bytes rather than display columns",
      "--width": "set the maximum line width",
      "--spaces": "break at spaces so words are not split",
      "--bytes": "count bytes rather than display columns",
    },
  },
  join: {
    summary: "join the lines of two files that share a common field",
    takesValue: ["t", "a", "v", "e", "o"],
    flags: {
      "1": "join on this field number from file 1",
      "2": "join on this field number from file 2",
      t: "use this character as the input/output field separator",
      a: "also print unpairable lines from file 1 or 2 (-a 1 / -a 2)",
      v: "print ONLY the unpairable lines from the given file",
      e: "replace empty output fields with this string",
      o: "control the output format (a list of fields)",
      i: "ignore case when comparing the join field",
    },
  },
  chattr: {
    summary: "change ext2/3/4 file attributes, e.g. +i makes a file immutable",
    flags: {
      R: "recurse into directories",
      V: "be verbose and print the program version",
      f: "suppress most error messages",
    },
  },
  getfacl: {
    summary: "display the Access Control Lists (ACLs) of files and directories",
    flags: {
      R: "recurse into subdirectories",
      a: "display only the file access control list",
      d: "display only the default access control list",
      t: "use the tabular output format",
      n: "show numeric user/group IDs instead of names",
      "--omit-header": "do not print the comment header (file/owner/group)",
    },
  },
}

// Generic hints for very common flags on unknown commands.
export const GENERIC_FLAGS: Record<string, string> = {
  h: "usually: show help / human-readable output",
  v: "usually: verbose output (or print the version)",
  f: "usually: force, or read from a file",
  r: "usually: recurse into directories",
  o: "usually: write output to a file",
  q: "usually: quiet — suppress normal output",
  y: "usually: assume yes to prompts",
  n: "usually: dry run, or a count",
  "--help": "show usage information and exit",
  "--version": "print the version and exit",
  "--verbose": "produce more detailed output",
  "--quiet": "suppress normal output",
  "--force": "proceed without prompting",
  "--yes": "assume yes to prompts",
  "--dry-run": "show what would happen without doing it",
};

// Representative "positive-control" invocations, one or more per command.
// These pin real behaviour so a regression in parsing/flag-resolution for any
// program is caught immediately (see test/positive-controls.test.js). When you
// add a command to DB above, add at least one example here — the test suite
// fails otherwise, keeping coverage in lock-step with the knowledge base.
export const EXAMPLES: Record<string, string[]> = {
  tar: ["tar -xzvf archive.tar.gz", "tar czf backup.tgz src"],
  grep: ["grep -rn TODO src", "grep -i --color needle file.txt"],
  ls: ["ls -la", "ls -lhSr", "ls -la --color=auto -F"],
  rm: ["rm -rf build", "rm -i note.txt"],
  cp: ["cp -r src dest", "cp -p a.txt b.txt"],
  mv: ["mv -i old new", "mv -v a b"],
  mkdir: ["mkdir -p a/b/c", "mkdir -m 755 dir"],
  ln: ["ln -s /usr/bin/python3 python", "ln -sf target link"],
  curl: ["curl -sSL -o out.html https://example.com", "curl -X POST -H 'A: b' -d data url"],
  wget: ["wget -c -O file.zip https://example.com/f.zip", "wget -c -q --show-progress --limit-rate=200k https://x.com/f.iso"],
  find: ["find . -name '*.log' -mtime +30 -delete", "find src -type f -maxdepth 2"],
  ffmpeg: ["ffmpeg -i in.mov -c:v libx264 -crf 23 -preset medium out.mp4", "ffmpeg -i in.mp4 -vf scale=1280:-1 -an out.webm"],
  openssl: ["openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes", "openssl s_client -connect example.com:443 -servername example.com"],
  chmod: ["chmod -R 755 dir", "chmod -v 600 key"],
  chown: ["chown -R user:group dir"],
  ssh: ["ssh -i key.pem -p 2222 user@host", "ssh -N -L 8080:localhost:80 host"],
  scp: ["scp -r -P 22 file user@host:/tmp"],
  rsync: ["rsync -avz --delete src/ dest/", "rsync -a --dry-run a/ b/"],
  docker: ["docker run -it --rm -p 8080:80 nginx", "docker build -t myimg .", "docker build -t app:1.0 --no-cache --build-arg VERSION=1 ."],
  git: ["git commit -am 'fix bug'", "git checkout -b feature", "git log --oneline --graph --all --decorate"],
  npm: ["npm install -D typescript", "npm run build", "npm ci --omit=dev"],
  systemctl: ["systemctl restart nginx", "systemctl enable --now docker", "systemctl status nginx --no-pager -l"],
  journalctl: ["journalctl -u nginx --since \"1 hour ago\" -f", "journalctl -xe -p err"],
  aws: ["aws s3 cp ./dist s3://mybucket/ --recursive --acl public-read", "aws s3 sync . s3://bucket --delete"],
  kubectl: ["kubectl get pods -n default -o wide", "kubectl logs -f mypod", "kubectl get pods -n kube-system -o wide --watch"],
  apt: ["apt install -y curl", "apt upgrade --yes"],
  sed: ["sed -i 's/a/b/g' file.txt", "sed -n -e '1,10p' file.txt"],
  awk: ["awk -F, '{print $1}' data.csv"],
  jq: ["jq -r '.items[] | select(.age > 30) | .name' data.json"],
  ps: ["ps aux", "ps -ef", "ps aux --sort=-%mem"],
  netstat: ["netstat -tulpn", "netstat -rn"],
  ss: ["ss -tulpn", "ss -s"],
  lsof: ["lsof -i :8080", "lsof -p 1234", "lsof -nP -i tcp"],
  ip: ["ip addr show", "ip route add default via 192.168.1.1", "ip -br link"],
  crontab: ["crontab -e", "crontab -l", "crontab -r"],
  unzip: ["unzip archive.zip -d dest", "unzip -l archive.zip"],
  nc: ["nc -lvnp 4444", "nc -zv host 22"],
  kill: ["kill -9 1234", "kill -15 4321"],
  xargs: ["xargs -0 -I{} rm {}", "xargs -n1 -P4 echo"],
  head: ["head -n 20 file.txt", "head -c 100 file.bin"],
  tail: ["tail -f -n 100 log.txt"],
  sort: ["sort -k2 -n -r data.txt", "sort -u -f names.txt"],
  uniq: ["uniq -c sorted.txt", "sort names.txt | uniq -d"],
  tee: ["ls | tee files.txt", "make 2>&1 | tee -a build.log"],
  diff: ["diff -u old.txt new.txt", "diff -r dir1/ dir2/"],
  gzip: ["gzip -k big.log", "gzip -d archive.gz"],
  column: ["column -t -s, data.csv", "mount | column -t"],
  cut: ["cut -d, -f1 data.csv", "cut -c1-10 file.txt"],
  tr: ["tr -d '\\n'", "tr -s ' '"],
  wc: ["wc -l file.txt", "wc -w -c file.txt"],
  cat: ["cat -n file.txt", "cat -A file.txt"],
  du: ["du -sh dir", "du -ah ."],
  df: ["df -h", "df -T -i"],
  ping: ["ping -c 4 host", "ping -i 2 host"],
  dd: ["dd if=/dev/zero of=out.img bs=1M count=10"],
  make: ["make -j4 -C build", "make -f Makefile.dev -n"],
  pip: ["pip install -U -r requirements.txt", "pip install -e . --no-cache-dir"],
  python: ["python -m venv .venv", "python -u -c 'print(1)'"],
  go: ["go build -o bin/app -race ./...", "go test -run TestFoo -count 1 ./...", "go mod tidy"],
  cargo: ["cargo build --release", "cargo test --workspace --all-features", "cargo add serde --features derive"],
  gcloud: ["gcloud compute instances list --project my-proj --zone us-central1-a", "gcloud storage cp ./dist gs://my-bucket --recursive"],
  terraform: ["terraform apply -auto-approve -var-file=prod.tfvars", "terraform plan -out plan.tfplan -no-color"],
  gh: ["gh pr create --title 'fix' --body 'closes #1'", "gh repo clone owner/name", "gh api repos/owner/name --jq .stargazers_count"],
  yarn: ["yarn add -D typescript", "yarn install --frozen-lockfile"],
  pnpm: ["pnpm add -D vitest", "pnpm install --frozen-lockfile", "pnpm -r run build"],
  zip: ["zip -r archive.zip src -x '*.log'", "zip -9 -j out.zip a.txt b.txt"],
  sudo: ["sudo -u postgres psql", "sudo -i"],
  touch: ["touch newfile.txt", "touch -c -m existing.log"],
  less: ["less -N server.log", "less -S -R output.txt"],
  date: ["date -u", 'date -d "next friday"'],
  echo: ["echo -n hello", "echo -e 'a\\tb'"],
  printf: ["printf '%s\\n' hello", 'printf "%-10s %d\\n" name 42'],
  base64: ["base64 secret.bin", "base64 -d encoded.txt"],
  env: ["env", "env -u DEBUG node app.js"],
  dig: ["dig example.com", "dig -t MX example.com"],
  watch: ["watch -n 10 date", "watch -d ls"],
  uname: ["uname -a", "uname -srm"],
  sha256sum: ["sha256sum file.iso", "sha256sum -c SHASUMS256.txt"],
  free: ["free -h", "free -m -s 5"],
  top: ["top", "top -b -n 1"],
  mount: ["mount", "mount -t ext4 -o ro /dev/sdb1 /mnt"],
  umount: ["umount /mnt", "umount -l /mnt/nfs", "umount -a -t nfs"],
  which: ["which python", "which -a node"],
  whoami: ["whoami"],
  hostname: ["hostname", "hostname -I", "hostname -f"],
  ifconfig: ["ifconfig", "ifconfig -a", "ifconfig eth0"],
  "ssh-keygen": ["ssh-keygen -t ed25519 -C you@example.com", "ssh-keygen -R oldhost", "ssh-keygen -y -f id_rsa"],
  stat: ["stat file.txt", "stat -L link", "stat -t /etc/hosts"],
  file: ["file /bin/ls", "file -i document.pdf", "file -b image.png"],
  basename: ["basename /usr/bin/sort", "basename -s .txt notes.txt", "basename -a src/a.c src/b.c"],
  dirname: ["dirname /usr/bin/sort"],
  realpath: ["realpath ./file.txt", "realpath -m /a/b/missing", "realpath --relative-to /home /home/user/x"],
  md5sum: ["md5sum file.iso", "md5sum -c MD5SUMS"],
  tree: ["tree -L 2 src", "tree -a -d", "tree -h --du"],
  htop: ["htop", "htop -u postgres", "htop -t"],
  pkill: ["pkill -f node", "pkill -9 chrome", "pkill -u www-data"],
  killall: ["killall firefox", "killall -9 node", "killall -u alice"],
  sleep: ["sleep 5", "sleep 0.5"],
  timeout: ["timeout 10 ./run.sh", "timeout -s KILL 30 python job.py", "timeout -k 5 60 make"],
  seq: ["seq 1 10", "seq -s, 0 2 20", "seq -w 1 100"],
  nohup: ["nohup ./server &", "nohup python app.py > out.log 2>&1 &"],
  nslookup: ["nslookup example.com", "nslookup -type=MX example.com"],
  traceroute: ["traceroute example.com", "traceroute -n -m 20 1.1.1.1", "traceroute -T -p 443 host"],
  sha1sum: ["sha1sum file.iso", "sha1sum -c SHA1SUMS"],
  xz: ["xz -9 big.log", "xz -dk archive.xz", "xz -T0 data.tar"],
  bzip2: ["bzip2 -k big.log", "bzip2 -d archive.bz2"],
  paste: ["paste a.txt b.txt", "paste -d, cols1 cols2", "paste -s -d, list.txt"],
  comm: ["comm a.txt b.txt", "comm -12 sorted1 sorted2", "comm -23 a b"],
  nl: ["nl file.txt", "nl -ba src.c", "nl -w4 -s': ' notes.txt"],
  tac: ["tac log.txt", "tac -s, data.csv"],
  rev: ["rev file.txt", "echo hello | rev"],
  "ssh-copy-id": ["ssh-copy-id user@host", "ssh-copy-id -i ~/.ssh/id_ed25519.pub -p 2222 user@host"],
  sftp: ["sftp user@host", "sftp -P 2222 -i key user@host", "sftp -b batch.txt user@host"],
  vim: ["vim notes.txt", "vim -R config.yml", "vim -d old.txt new.txt", "vim -O a.py b.py"],
  nano: ["nano file.txt", "nano -l main.c", "nano -w /etc/hosts"],
  man: ["man ls", "man -k compress", "man 5 crontab", "man -f printf"],
  id: ["id", "id -u", "id -un", "id -Gn alice"],
  who: ["who", "who -a", "who -b", "who -q"],
  uptime: ["uptime", "uptime -p", "uptime -s"],
  su: ["su", "su - alice", "su -c 'systemctl restart nginx'", "su -s /bin/bash postgres"],
  gpg: ["gpg -c secrets.txt", "gpg -e -r alice@example.com report.pdf", "gpg -d secrets.txt.gpg", "gpg --list-keys"],
  tmux: ["tmux new -s work", "tmux attach -t work", "tmux ls", "tmux kill-session -t work"],
  lsblk: ["lsblk", "lsblk -f", "lsblk -p", "lsblk -o NAME,SIZE,MOUNTPOINT"],
  dmesg: ["dmesg", "dmesg -H", "dmesg -w", "dmesg -l err,warn"],
  mktemp: ["mktemp", "mktemp -d", "mktemp -p /var/tmp", "mktemp --suffix=.json"],
  gunzip: ["gunzip archive.gz", "gunzip -k data.gz", "gunzip -c logs.gz | less"],
  history: ["history", "history 20", "history -c", "history -w"],
  alias: ["alias", "alias ll='ls -la'", "alias -p"],
  export: ["export PATH=$PATH:/opt/bin", "export EDITOR=vim", "export -p"],
  passwd: ["passwd", "passwd alice", "passwd -S bob", "passwd -l svc"],
  useradd: ["useradd -m -s /bin/bash alice", "useradd -r -s /usr/sbin/nologin svc", "useradd -m -G sudo,docker bob"],
  usermod: ["usermod -aG docker alice", "usermod -s /bin/zsh bob", "usermod -L olduser"],
  groupadd: ["groupadd docker", "groupadd -g 1005 staff", "groupadd -r sysgrp"],
  lscpu: ["lscpu", "lscpu -e", "lscpu --json"],
  lspci: ["lspci", "lspci -v", "lspci -nnk"],
  lsusb: ["lsusb", "lsusb -t", "lsusb -v"],
  lsmod: ["lsmod", "lsmod | grep nvidia"],
  modprobe: ["modprobe nvidia", "modprobe -r nvidia", "modprobe -n -v e1000"],
  shuf: ["shuf -n 1 file.txt", "shuf -i 1-100 -n 5", "shuf -e apple banana cherry"],
  split: ["split -l 1000 big.txt part_", "split -b 10M file.iso chunk_", "split -n 4 -d data seg_"],
  strings: ["strings binary", "strings -n 8 a.out", "strings -t x firmware.bin"],
  ldd: ["ldd /bin/ls", "ldd -v ./a.out"],
  screen: ["screen -S work", "screen -r", "screen -dm long-job.sh"],
  zcat: ["zcat access.log.gz", "zcat -f file", "zcat data.gz | grep error"],
  sha512sum: ["sha512sum file.iso", "sha512sum -c SHA512SUMS", "sha512sum *.tar.gz"],
  iptables: ["iptables -A INPUT -p tcp --dport 22 -j ACCEPT", "iptables -L -n -v", "iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE"],
  ufw: ["ufw allow 22/tcp", "ufw enable", "ufw status verbose"],
  "firewall-cmd": ["firewall-cmd --zone=public --add-port=80/tcp --permanent", "firewall-cmd --reload", "firewall-cmd --list-all"],
  strace: ["strace -f -e trace=open,read -o trace.log ./prog", "strace -p 1234 -c"],
  ltrace: ["ltrace -f -e malloc+free ./prog", "ltrace -p 1234 -c"],
  "systemd-analyze": ["systemd-analyze blame", "systemd-analyze critical-chain", "systemd-analyze security sshd"],
  hostnamectl: ["hostnamectl status", "hostnamectl set-hostname web01"],
  timedatectl: ["timedatectl set-timezone Europe/Paris", "timedatectl status", "timedatectl set-ntp true"],
  nice: ["nice -n 19 tar czf backup.tgz .", "nice -n 10 ./batch-job"],
  renice: ["renice -n 5 -p 1234", "renice 10 -u alice"],
  taskset: ["taskset -c 0,1 ./prog", "taskset -pc 0-3 1234"],
  at: ["at -f script.sh 09:00", "at -l"],
  fold: ["fold -w 72 -s letter.txt", "fold -w 40 notes.txt"],
  join: ["join -t , -a 1 users.csv orders.csv", "join file1 file2"],
  chattr: ["chattr -R +i logs/", "chattr -V +a app.log"],
  getfacl: ["getfacl file.txt", "getfacl -R /srv/www"],
};