id       = "forge"
name     = "Foundry"
homepage = "https://getfoundry.sh"
description = "A blazing fast, portable and modular toolkit for Ethereum application development written in Rust."
# Foundry's own logo, from its homepage.
icon     = "https://getfoundry.sh/foundry-logo.png"
executables   = ["forge", "cast", "anvil", "chisel"]

[dotfiles]

# crates/config/src/lib.rs: FOUNDRY_DIR_NAME = ".foundry", foundry_dir() is
# dirs::home_dir()/.foundry and foundry_dir_toml() joins FILE_NAME =
# "foundry.toml" onto it. The config reference says the same: "You can create a
# foundry.toml file in ~/.foundry folder to configure Foundry globally."
paths = ["~/.foundry/foundry.toml"]

# Same file: foundry_cache_dir() is ~/.foundry/cache, holding the cached RPC and
# Etherscan responses under rpc/<chain> and etherscan/<chain>. ~/.foundry/bin is
# where foundryup installs the toolchain binaries.
exclude = ["~/.foundry/cache/", "~/.foundry/bin/"]

# foundry_keystores_dir() is ~/.foundry/keystores — one encrypted JSON keystore
# per wallet imported with `cast wallet import`, each wrapping a private key.
secret = ["~/.foundry/keystores/"]

# Loaded through figment at the start of each command.
side_effect = false

# etherscan_api_key inside a [profile.<name>] table and the per-chain `key` under
# [etherscan] are block-explorer API keys. [rpc_endpoints] values are counted as
# credentials too: the usual entry is a provider URL with the project key in the
# path (Alchemy, Infura), and there is no way to tell those from a plain URL
# without reading the value.
[[dotfiles.secret_paths]]
file  = "~/.foundry/foundry.toml"
match = { key_path = ["profile.*.etherscan_api_key", "etherscan.*.key", "rpc_endpoints.*"] }

# No machine_lines: the paths a foundry.toml sets (src, out, libs, cache_path)
# are relative to a project root, not to this disk.

[commands]
format = 1
label = "Foundry forge"
description = "Build, test and initialize Solidity projects with Foundry's forge. Only a few common options of forge build, forge test and forge init are covered; fuzzing, invariant, fork, debugger and watch options are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }

[[commands.subcommand]]
path = ["build"]
label = "Build contracts"
description = "Compile the project's smart contracts."

[[commands.subcommand.source]]
id = "help"
kind = "help"
url = "https://www.getfoundry.sh/reference/forge/build"
revision = "2026-10-27"
evidence = """
Usage: forge build [OPTIONS] [PATHS]...
      --names
          Print compiled contract names
      --sizes
          Print compiled contract sizes. Constructor argument length is not
      --force
          Clear the cache and artifacts folder and recompile
      --use <SOLC_VERSION>
          Specify the solc version, path, or executable name on `PATH` to build
      --offline
          Do not access the network.
      --via-ir
          Use the Yul intermediate representation compilation pipeline
      --evm-version <VERSION>
          The target EVM version
  -o, --out <PATH>
          The path to the contract artifacts folder
      --root <PATH>
          The project's root path.
"""

[[commands.subcommand.field]]
id = "paths"
label = "Paths"
description = "Files or directories to build; empty builds the whole project."
type = "path"
path = { kind = "any", role = "input" }
position = 0
multiple = true
sources = ["help"]

[[commands.subcommand.field]]
id = "sizes"
label = "Print contract sizes"
type = "boolean"
option = ["--sizes"]
sources = ["help"]

[[commands.subcommand.field]]
id = "names"
label = "Print contract names"
type = "boolean"
option = ["--names"]
sources = ["help"]

[[commands.subcommand.field]]
id = "force"
label = "Clean and recompile"
description = "Clear the cache and artifacts folder, then recompile everything."
type = "boolean"
option = ["--force"]
effect = "delete"
sources = ["help"]

[[commands.subcommand.field]]
id = "solc"
label = "Solc version"
description = "A version such as 0.8.28, a path, or an executable name."
type = "string"
option = ["--use"]
sources = ["help"]

[[commands.subcommand.field]]
id = "via_ir"
label = "Use Yul IR pipeline"
type = "boolean"
option = ["--via-ir"]
sources = ["help"]

[[commands.subcommand.field]]
id = "evm_version"
label = "EVM version"
type = "string"
option = ["--evm-version"]
sources = ["help"]

[[commands.subcommand.field]]
id = "out"
label = "Artifacts folder"
type = "path"
path = { kind = "directory", role = "output" }
option = ["--out", "-o"]
sources = ["help"]

[[commands.subcommand.field]]
id = "root"
label = "Project root"
type = "path"
path = { kind = "directory", role = "input" }
option = ["--root"]
sources = ["help"]

[[commands.subcommand.field]]
id = "offline"
label = "Offline"
description = "Do not access the network; missing solc versions are not installed."
type = "boolean"
option = ["--offline"]
sources = ["help"]

[[commands.subcommand.task]]
id = "build"
label = "Build project"
fields = []

[[commands.subcommand.task]]
id = "sizes"
label = "Build and print sizes"
fields = ["sizes"]
set = { sizes = [true] }

[[commands.subcommand.task]]
id = "clean_build"
label = "Clean rebuild"
fields = ["force"]
set = { force = [true] }

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["paths", "sizes", "names", "force"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["solc", "via_ir", "evm_version", "out", "root", "offline"]

[[commands.subcommand]]
path = ["test"]
label = "Run tests"
description = "Run the project's tests, optionally filtered by test, contract or path."

[[commands.subcommand.source]]
id = "help"
kind = "help"
url = "https://www.getfoundry.sh/reference/forge/test"
revision = "2026-10-27"
evidence = """
Usage: forge test [OPTIONS] [PATH]
  -v, --verbosity...
  -l, --list
          List tests instead of running them
      --gas-report
          Print a gas report
      --allow-failure
          Exit with code 0 even if a test fails
      --fail-fast
          Stop running tests after the first failure
      --fuzz-runs <RUNS>
      --match-test <REGEX>
          Only run test functions matching the specified regex pattern
      --no-match-test <REGEX>
          Only run test functions that do not match the specified regex pattern
      --match-contract <REGEX>
          Only run tests in contracts matching the specified regex pattern
      --no-match-contract <REGEX>
          Only run tests in contracts that do not match the specified regex
      --match-path <GLOB>
          Only run tests in source files matching the specified glob pattern
      --json
          Format log messages as JSON
"""

[[commands.subcommand.field]]
id = "match_test"
label = "Match test"
description = "Regex of test function names to run."
type = "string"
option = ["--match-test"]
sources = ["help"]

[[commands.subcommand.field]]
id = "no_match_test"
label = "Exclude test"
description = "Regex of test function names to skip."
type = "string"
option = ["--no-match-test"]
sources = ["help"]

[[commands.subcommand.field]]
id = "match_contract"
label = "Match contract"
description = "Regex of contract names to run."
type = "string"
option = ["--match-contract"]
sources = ["help"]

[[commands.subcommand.field]]
id = "no_match_contract"
label = "Exclude contract"
type = "string"
option = ["--no-match-contract"]
sources = ["help"]

[[commands.subcommand.field]]
id = "match_path"
label = "Match path"
description = "Glob of source files to run."
type = "string"
option = ["--match-path"]
sources = ["help"]

[[commands.subcommand.field]]
id = "verbosity"
label = "Verbosity"
description = "Repeat -v to show more detail, e.g. -vvvv for traces."
type = "count"
option = ["-v"]
sources = ["help"]

[[commands.subcommand.field]]
id = "gas_report"
label = "Gas report"
type = "boolean"
option = ["--gas-report"]
sources = ["help"]

[[commands.subcommand.field]]
id = "fuzz_runs"
label = "Fuzz runs"
type = "integer"
option = ["--fuzz-runs"]
sources = ["help"]

[[commands.subcommand.field]]
id = "fail_fast"
label = "Stop at first failure"
type = "boolean"
option = ["--fail-fast"]
sources = ["help"]

[[commands.subcommand.field]]
id = "list"
label = "List tests only"
type = "boolean"
option = ["--list", "-l"]
sources = ["help"]

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

[[commands.subcommand.task]]
id = "all"
label = "Run all tests"
fields = []

[[commands.subcommand.task]]
id = "one_test"
label = "Run one test with traces"
fields = ["match_test", "verbosity"]
required = ["match_test"]
set = { verbosity = [4] }

[[commands.subcommand.task]]
id = "one_contract"
label = "Run one contract"
fields = ["match_contract"]
required = ["match_contract"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["match_test", "match_contract", "match_path", "verbosity", "gas_report", "fail_fast"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["no_match_test", "no_match_contract", "fuzz_runs", "list", "json"]

[[commands.subcommand]]
path = ["init"]
label = "Create a project"
description = "Create a new Forge project."

[[commands.subcommand.source]]
id = "help"
kind = "help"
url = "https://www.getfoundry.sh/reference/forge/init"
revision = "2026-10-27"
evidence = """
  [PATH]
          The root directory of the new project
  -t, --template <TEMPLATE>
          The template to start from
      --offline
          Do not install dependencies from the network
      --force
          Create the project even if the specified root directory is not empty
      --vscode
          Create a .vscode/settings.json file with Solidity settings, and
      --vyper
          Initialize a Vyper project template
      --empty
          Do not create example contracts (Counter.sol, Counter.t.sol,
      --no-git
          Install without adding the dependency as a submodule
"""

[[commands.subcommand.field]]
id = "path"
label = "Project directory"
type = "path"
path = { kind = "directory", role = "output" }
position = 0
sources = ["help"]

[[commands.subcommand.field]]
id = "template"
label = "Template"
description = "A template repository to start from."
type = "string"
option = ["--template", "-t"]
sources = ["help"]

[[commands.subcommand.field]]
id = "empty"
label = "No example contracts"
type = "boolean"
option = ["--empty"]
sources = ["help"]

[[commands.subcommand.field]]
id = "vscode"
label = "VS Code settings"
type = "boolean"
option = ["--vscode"]
sources = ["help"]

[[commands.subcommand.field]]
id = "vyper"
label = "Vyper template"
type = "boolean"
option = ["--vyper"]
sources = ["help"]

[[commands.subcommand.field]]
id = "offline"
label = "Offline"
description = "Do not install dependencies from the network."
type = "boolean"
option = ["--offline"]
sources = ["help"]

[[commands.subcommand.field]]
id = "no_git"
label = "Skip git submodule"
type = "boolean"
option = ["--no-git"]
sources = ["help"]

[[commands.subcommand.field]]
id = "force"
label = "Allow non-empty directory"
type = "boolean"
option = ["--force"]
effect = "overwrite"
sources = ["help"]

[[commands.subcommand.task]]
id = "new"
label = "New project"
fields = ["path"]
required = ["path"]

[[commands.subcommand.task]]
id = "empty"
label = "New project without examples"
fields = ["path", "empty"]
required = ["path"]
set = { empty = [true] }

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["path", "template", "empty", "vscode"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["vyper", "offline", "no_git", "force"]