{
  "name": "ls",
  "section": 1,
  "title": "list directory contents",
  "synopsis": [
    "ls [-1al] [--color[=never|auto|always]] [FILE...]"
  ],
  "description": "Lists directory contents. Long format shows mode, links, owner, group, size, mtime, and symlink targets. With color (default auto on a TTY), directories, symlinks, executables, and permission bits are highlighted.",
  "options": [
    {
      "flag": "-a",
      "meaning": "Include names starting with ."
    },
    {
      "flag": "-l",
      "meaning": "Long listing"
    },
    {
      "flag": "-1",
      "meaning": "One name per line (short format)"
    },
    {
      "flag": "--color[=never|auto|always]",
      "meaning": "ANSI colors: never, auto (TTY only), or always; plain --color is auto"
    }
  ],
  "keywords": [
    "ls",
    "list",
    "directory",
    "dir"
  ],
  "environment": [
    "NO_COLOR — disable color even when a TTY or --color=always"
  ],
  "bareOsNotes": "Hides .bareos_empty marker like other tools.",
  "examples": [
    {
      "caption": "long + hidden",
      "code": "ls -la ~"
    },
    {
      "caption": "one per line",
      "code": "ls -1 /bin | head"
    },
    {
      "caption": "multiple paths",
      "code": "ls /bin /etc"
    }
  ]
}