id       = "neonctl"
name     = "Neon CLI"
homepage = "https://github.com/neondatabase/neonctl"
description = "The Neon CLI brings the Neon backend platform to your terminal."
executables   = ["neonctl"]

[dotfiles]

# The official CLI reference in https://github.com/neondatabase/neonctl states
# that --config-dir defaults to ~/.config/neonctl and that auth creates a
# credentials.json file there. This file is only an API credential.
paths = []
secret = ["~/.config/neonctl/credentials.json"]

[commands]
format = 1
label = "Neon CLI"
description = "Global options only; use the psql subcommand to open a psql session on a branch."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = false, short_bundles = false }

[[commands.subcommand]]
path = ["psql"]
label = "Open psql on a branch"
description = "Connect to a Neon branch with psql. Arguments for psql after -- are left out."

[[commands.subcommand.source]]
id = "help"
kind = "manual"
url = "https://raw.githubusercontent.com/neondatabase/neonctl/HEAD/README.md"
revision = "HEAD 2026-10"
evidence = """
`neonctl psql [branch]` opens a psql session against a branch.
neonctl psql main                               # a specific branch
neonctl psql --pooled                           # use the pooled connection
Options: `--project-id`, `--role-name`, `--database-name`, `--pooled`, `--endpoint-type` (`read_only` | `read_write`), `--ssl`, plus the [global options](#global-options).
neonctl projects list --api-key <neon_api_key>
"""

[[commands.subcommand.field]]
id = "branch"
label = "Branch"
description = "Branch name, or branch@timestamp / branch@lsn. Leave empty for the default branch."
type = "string"
position = 0
sources = ["help"]

[[commands.subcommand.field]]
id = "project_id"
label = "Project ID"
type = "string"
option = ["--project-id"]
sources = ["help"]

[[commands.subcommand.field]]
id = "role_name"
label = "Role"
type = "string"
option = ["--role-name"]
sources = ["help"]

[[commands.subcommand.field]]
id = "database_name"
label = "Database"
type = "string"
option = ["--database-name"]
sources = ["help"]

[[commands.subcommand.field]]
id = "pooled"
label = "Pooled connection"
type = "boolean"
option = ["--pooled"]
sources = ["help"]

[[commands.subcommand.field]]
id = "endpoint_type"
label = "Endpoint type"
type = "enum"
option = ["--endpoint-type"]
choices = [{ value = "read_only", label = "Read only" }, { value = "read_write", label = "Read write" }]
sources = ["help"]

[[commands.subcommand.task]]
id = "default"
label = "Default branch"
fields = ["project_id"]

[[commands.subcommand.task]]
id = "branch"
label = "Named branch"
fields = ["branch", "project_id", "pooled"]
required = ["branch"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["branch", "project_id", "pooled"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["role_name", "database_name", "endpoint_type"]