id          = "sq"
name        = "sq"
homepage    = "https://sq.io/"
description = "A free/libre open-source data wrangling swiss-army knife to inspect, query, join, import, and export data."
executables      = ["sq"]

[dotfiles]

# https://sq.io/docs/config — sq stores its main config in sq.yml in an
# OS-dependent config directory; the official macOS example resolves this to
# ~/.config/sq/sq.yml. This is the Homebrew/macOS spelling.
paths = ["~/.config/sq/"]

# https://sq.io/docs/secrets explains that source locations may contain inline
# passwords in sq.yml and that exported configs preserve inline credentials.
secret = ["~/.config/sq/sq.yml"]

[commands]
format = 1
label = "sq"
description = "Inspect a data source's metadata and schema. Queries, source management and other sq subcommands are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }

[[commands.subcommand]]
path = ["inspect"]
label = "Inspect a source or table"
description = "Show metadata, tables and columns for a source (@handle) or a table (@handle.table). Omit the target to use the active source."

[[commands.subcommand.source]]
id = "help"
kind = "help"
url = "https://sq.io/docs/cmd/inspect"
revision = "v0.55.0"
evidence = """
Usage:
  sq inspect [@HANDLE|@HANDLE.TABLE|.TABLE]
  -j, --json                       Output JSON
  -y, --yaml                       Output YAML
      --markdown                   Output a Markdown schema document
      --html                       Output a standalone HTML schema document
  -O, --overview                   Show metadata only (no schema)
  -p, --dbprops                    Show DB properties only
  -C, --catalogs                   List catalogs only
  -S, --schemata                   List schemas (in current catalog) only
      --src.schema string          Override active schema (and/or catalog) for this query
      --no-cache                   Don't cache ingest data
  -o, --output string              Write output to <file> instead of stdout
  -v, --verbose                    Print verbose output
"""

[[commands.subcommand.field]]
id = "target"
label = "Source or table"
description = "@handle, @handle.table or .table; leave empty for the active source."
type = "string"
position = 0
min = 0
sources = ["help"]

[[commands.subcommand.field]]
id = "json"
label = "JSON output"
type = "boolean"
option = ["--json", "-j"]
sources = ["help"]

[[commands.subcommand.field]]
id = "yaml"
label = "YAML output"
type = "boolean"
option = ["--yaml", "-y"]
sources = ["help"]

[[commands.subcommand.field]]
id = "markdown"
label = "Markdown schema document"
type = "boolean"
option = ["--markdown"]
sources = ["help"]

[[commands.subcommand.field]]
id = "html"
label = "HTML schema document"
type = "boolean"
option = ["--html"]
sources = ["help"]

[[commands.subcommand.field]]
id = "overview"
label = "Metadata only"
type = "boolean"
option = ["--overview", "-O"]
sources = ["help"]

[[commands.subcommand.field]]
id = "schemata"
label = "List schemas"
type = "boolean"
option = ["--schemata", "-S"]
sources = ["help"]

[[commands.subcommand.field]]
id = "catalogs"
label = "List catalogs"
type = "boolean"
option = ["--catalogs", "-C"]
sources = ["help"]

[[commands.subcommand.field]]
id = "verbose"
label = "Verbose"
type = "boolean"
option = ["--verbose", "-v"]
sources = ["help"]

[[commands.subcommand.field]]
id = "output"
label = "Output file"
type = "path"
option = ["--output", "-o"]
path = { kind = "file", role = "output", must_exist = false }
effect = "overwrite"
sources = ["help"]

[[commands.subcommand.task]]
id = "json"
label = "Inspect as JSON"
fields = ["target", "json"]
required = ["target"]
set = { json = [true] }

[[commands.subcommand.task]]
id = "html"
label = "Write HTML schema doc"
fields = ["target", "html", "output"]
required = ["target", "output"]
set = { html = [true] }

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["target", "json", "yaml", "markdown", "html", "output"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["overview", "schemata", "catalogs", "verbose"]