id          = "censys"
name        = "Censys CLI"
homepage    = "https://github.com/censys/censys-python"
description = "An easy-to-use and lightweight API wrapper for Censys APIs."
executables      = ["censys"]

[dotfiles]

# The official legacy Censys Python CLI documentation names the default config
# file and allows CENSYS_CONFIG_PATH to override it. It stores API credentials,
# so this file is secret-only.
# https://censys-python.readthedocs.io/en/v2.2.2/usage-cli.html
paths  = []
secret = ["[configHome]/censys/censys.cfg"]
side_effect = false

[commands]
format = 1
label = "Censys CLI"
description = "Search Censys data, look up a host or certificate, or enumerate subdomains. Credentials (censys config), ASM seed management and account commands are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }

[[commands.source]]
id = "docs"
kind = "manual"
url = "https://censys-python.readthedocs.io/en/stable/usage-cli.html"
revision = "stable 2026-10-27"
evidence = """
censys search 'ip: 8.8.8.0/16' --pages -1
censys search 'parsed.subject_dn: "censys.io"' --index-type certificates
censys search 'parsed.subject.country: AU' --index-type certificates --fields parsed.issuer.organization
censys view 8.8.8.8 -o google.json
censys view 1.1.1.1 --at-time 2023-01-01
censys subdomains censys.io --max-records 10
censys subdomains censys.io --json
"""

[[commands.subcommand]]
path = ["search"]
label = "Search"
description = "Run a Censys search query against hosts or certificates."

[[commands.subcommand.source]]
id = "docs"
kind = "manual"
url = "https://censys-python.readthedocs.io/en/stable/usage-cli.html"
revision = "stable 2026-10-27"
evidence = """
censys search 'ip: 8.8.8.0/16' --pages -1
censys search 'parsed.subject_dn: "censys.io"' --index-type certificates
censys search 'parsed.subject.country: AU' --index-type certificates --fields parsed.issuer.organization
"""

[[commands.subcommand.field]]
id = "query"
label = "Query"
type = "string"
position = 0
min = 1
sources = ["docs"]

[[commands.subcommand.field]]
id = "index_type"
label = "Index"
type = "enum"
option = ["--index-type"]
choices = [{ value = "hosts", label = "Hosts" }, { value = "certificates", label = "Certificates" }]
sources = ["docs"]

[[commands.subcommand.field]]
id = "pages"
label = "Pages"
description = "-1 fetches all pages."
type = "integer"
option = ["--pages"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "fields"
label = "Fields"
description = "Fields to return (certificates index)."
type = "string"
option = ["--fields"]
sources = ["docs"]

[[commands.subcommand.task]]
id = "search"
label = "Search"
fields = ["query", "index_type", "pages", "fields"]
required = ["query"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["query", "index_type", "pages", "fields"]

[[commands.subcommand]]
path = ["view"]
label = "View"
description = "View one host (IP) or certificate (fingerprint)."

[[commands.subcommand.source]]
id = "docs"
kind = "manual"
url = "https://censys-python.readthedocs.io/en/stable/usage-cli.html"
revision = "stable 2026-10-27"
evidence = """
censys view 9b267decc8d23586dc4c56dd0789574cab0f28581ef354ff2fcec8ca6d992fc2 --index-type certificates
censys view 8.8.8.8 -o google.json
censys view 1.1.1.1 --at-time 2023-01-01
"""

[[commands.subcommand.field]]
id = "asset"
label = "IP or certificate fingerprint"
type = "string"
position = 0
min = 1
sources = ["docs"]

[[commands.subcommand.field]]
id = "index_type"
label = "Index"
type = "enum"
option = ["--index-type"]
choices = [{ value = "hosts", label = "Hosts" }, { value = "certificates", label = "Certificates" }]
sources = ["docs"]

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

[[commands.subcommand.field]]
id = "at_time"
label = "At time"
description = "Historical view, hosts index only (YYYY-MM-DD)."
type = "string"
option = ["--at-time"]
sources = ["docs"]

[[commands.subcommand.task]]
id = "view"
label = "View"
fields = ["asset", "index_type", "output", "at_time"]
required = ["asset"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["asset", "index_type", "output", "at_time"]

[[commands.subcommand]]
path = ["subdomains"]
label = "Subdomains"
description = "Enumerate subdomains of a domain."

[[commands.subcommand.source]]
id = "docs"
kind = "manual"
url = "https://censys-python.readthedocs.io/en/stable/usage-cli.html"
revision = "stable 2026-10-27"
evidence = """
censys subdomains censys.io --max-records 10
censys subdomains censys.io --json
"""

[[commands.subcommand.field]]
id = "domain"
label = "Domain"
type = "string"
position = 0
min = 1
sources = ["docs"]

[[commands.subcommand.field]]
id = "max_records"
label = "Max records"
type = "integer"
option = ["--max-records"]
sources = ["docs"]

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

[[commands.subcommand.task]]
id = "subdomains"
label = "Enumerate subdomains"
fields = ["domain", "max_records", "json"]
required = ["domain"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["domain", "max_records", "json"]