id = "fabric"
name = "Fabric"
homepage = "https://www.fabfile.org/"
description = "Library and command-line tool for SSH"
executables = ["fab"]

[dotfiles]

# Fabric's configuration docs say its user-level candidates are named
# fabric.yaml, fabric.yml, fabric.json, or fabric.py under ~/. (the loader
# tries these suffixes in that order). Fabric 1.x called the same user file
# ~/.fabricrc; keep that historical spelling for users upgrading from it.
# https://docs.fabfile.org/en/stable/concepts/configuration.html
# https://docs.fabfile.org/en/0.9.7/changes/0.9.html
paths = []
# Fabric settings can include SSH usernames, private-key material, and
# connection or sudo passwords; the complete user file is therefore treated
# as secret content.
secret = [
  "~/.fabric.yaml",
  "~/.fabric.yml",
  "~/.fabric.json",
  "~/.fabric.py",
  "~/.fabricrc",
]

[commands]
format = 1
label = "Run fabfile tasks"
description = "Run tasks from a fabfile.py over SSH against a list of hosts, or list the available tasks. Collections, config files, task arguments and sudo prompts 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://docs.fabfile.org/en/stable/cli.html"
revision = "3.x stable"
evidence = """
-H, --hosts
Takes a comma-separated string listing hostnames against which tasks should be executed, in serial.
-i, --identity
Typically this can be thought of as identical to ssh -i <path>, i.e. supplying a specific, runtime private key file.
--prompt-for-login-password
--prompt-for-passphrase
-S, --ssh-config
Takes a path to load as a runtime SSH config file.
-t, --connect-timeout
Takes an integer of seconds after which connection should time out.
$ fab --hosts host1,host2,host3 taskA taskB
fab --list
"""

[[commands.source]]
id = "invoke"
kind = "manual"
url = "https://docs.pyinvoke.org/en/stable/invoke.html"
revision = "stable"
evidence = """
-d, --debug
--dry
-e, --echo
-l, --list=STRING
-p, --pty
-r STRING, --search-root=STRING
-w, --warn-only
"""

[[commands.field]]
id = "tasks"
label = "Tasks"
description = "Task names from fabfile.py, run in this order for each host."
type = "string"
position = 0
multiple = true
sources = ["docs"]

[[commands.field]]
id = "hosts"
label = "Hosts"
description = "Comma-separated list of hostnames, for example host1,host2."
type = "string"
option = ["--hosts", "-H"]
sources = ["docs"]

[[commands.field]]
id = "identity"
label = "SSH private key"
type = "path"
option = ["--identity", "-i"]
path = { kind = "file", role = "input", must_exist = true }
sources = ["docs"]

[[commands.field]]
id = "ssh_config"
label = "SSH config file"
type = "path"
option = ["--ssh-config", "-S"]
path = { kind = "file", role = "input", must_exist = true }
sources = ["docs"]

[[commands.field]]
id = "connect_timeout"
label = "Connect timeout (seconds)"
type = "integer"
option = ["--connect-timeout", "-t"]
min = 1
sources = ["docs"]

[[commands.field]]
id = "prompt_login_password"
label = "Prompt for login password"
type = "boolean"
option = ["--prompt-for-login-password"]
sources = ["docs"]

[[commands.field]]
id = "prompt_passphrase"
label = "Prompt for key passphrase"
type = "boolean"
option = ["--prompt-for-passphrase"]
sources = ["docs"]

[[commands.field]]
id = "list"
label = "List tasks"
description = "List available tasks instead of running any."
type = "boolean"
option = ["--list", "-l"]
sources = ["invoke"]

[[commands.field]]
id = "echo"
label = "Echo commands"
type = "boolean"
option = ["--echo", "-e"]
sources = ["invoke"]

[[commands.field]]
id = "dry"
label = "Dry run"
type = "boolean"
option = ["--dry"]
sources = ["invoke"]

[[commands.field]]
id = "pty"
label = "Use a pty"
type = "boolean"
option = ["--pty", "-p"]
sources = ["invoke"]

[[commands.field]]
id = "warn_only"
label = "Warn only on failures"
type = "boolean"
option = ["--warn-only", "-w"]
sources = ["invoke"]

[[commands.task]]
id = "run"
label = "Run tasks on hosts"
fields = ["tasks", "hosts", "identity", "echo"]
required = ["tasks", "hosts"]

[[commands.task]]
id = "list"
label = "List tasks"
fields = ["list"]
set = { list = [true] }
lock = ["list"]

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["tasks", "hosts", "identity", "list"]

[[commands.group]]
id = "advanced"
label = "Advanced"
fields = ["ssh_config", "connect_timeout", "prompt_login_password", "prompt_passphrase", "echo", "dry", "pty", "warn_only"]