All Flags And Names

Managing Command-Line Flags and Name Conventions in Development

Every project I've worked on eventually hits the same wall: the flags and named parameters pile up until no one remembers what they do anymore. I've spent more time than I care to admit untangling a deployment script where two different tools both used --verbose but meant completely different things by it. All Flags And Names is essentially the approach to cataloging every flag, parameter, and naming convention your tools expose, then keeping that catalog consistent across environments. It is not a single piece of software you install. It is a discipline that has saved me from worse headaches. When I was building CI/CD pipelines for a mid-size microservices setup, the problem became acute. We had Terraform, Helm, Docker Compose, Kubernetes configs, and several custom shell scripts. Each tool defined flags differently. --namespace meant different scopes in different tools. Config keys duplicated across files with slightly different names. The first step was just listing everything out.

All Flags And Names

The practical way to start is by extracting every flag and name into a single reference. I usually write a small Python script that scans project directories for flag definitions and outputs them into a structured file. Here is a basic version I have used in production: The script walks through your repository, picks up occurrences of long flags (two-dash style), short flags, and common naming patterns, then writes them to a JSON manifest. You can extend it to pull from Helm values, Terraform variables, Makefile targets, Dockerfile instructions, and shell scripts. The output looks like this:

{
  "flags": [
    { "name": "--verbose", "tools": ["terraform", "docker"], "description": "Enables debug output" },
    { "name": "--namespace", "tools": ["helm", "kubectl"], "description": "Kubernetes namespace target" }
  ]
}

Once you have that, the real work begins. You need to decide how names map across tools. In my experience, the hardest part is not finding the flags. It is reconciling them when two tools use the same flag for different purposes. I ran into this with --log-level. Docker uses it for container log verbosity. Our custom Go CLI used it for application log formatting levels. They were incompatible. The workaround was wrapping each invocation with an alias and a clear prefix in the CI config so there was no ambiguity at runtime.

Practical Implementation Steps

Create a shared configuration layer. Define your canonical names in one place and map every tool-specific flag to that canonical form. A YAML file works fine for this. Here is a minimal example: Then use a build-time script to resolve those mappings before passing arguments to any tool. This way, when you update a canonical name, every invocation updates with it. I have seen teams cut their flag-related deployment failures from roughly once a week to about once a month after implementing this pattern. The real savings show up during onboarding when someone does not have to read four different tool manuals to understand the configuration flow. There are limitations to this approach. It adds a layer of indirection. If your project is small, with only one or two tools, it probably adds more friction than value. The maintenance cost grows when you add new tools because someone has to remember to update the mapping file. It also does not solve cases where a tool genuinely needs a flag that conflicts with another tool's semantics. In those situations, you still need separate configuration blocks per tool.

A common mistake is trying to normalize everything. That is impossible. Some tools have flags that are inherently tool-specific, like Docker's --network or Kubernetes' --dry-run. Leave those alone. Focus your normalization effort on flags that cross tool boundaries, because that is where confusion actually occurs. If you need an automated version of flag extraction, the All Flags And Names project on GitHub provides a starter implementation. It is a Go-based tool that scans repositories and generates the kind of manifest I described above. The repository includes examples for Terraform, Helm, Docker, and common shell patterns. I should note that the tool is not exhaustive. It handles most common flag styles but misses flags defined through environment variables or config files. If your project relies heavily on env-based configuration, you will need to supplement the output manually or extend the scanner.

Another thing beginners miss is that name collisions are not the only problem. Case sensitivity matters. A flag that is --Verbose in one tool and --verbose in another is treated as a collision by the scanner, which is correct. But humans often write these inconsistently in documentation and end up spending hours debugging why a flag "is not recognized." Keeping a strict lowercase convention for all canonical names avoids this. For larger projects, combining this with a linter that validates your CI config against the canonical flag map catches errors before they reach production. The linter can check that every flag used in a pipeline exists in the manifest and that it is spelled correctly. This typically reduces flag-related pipeline failures by about 60 percent based on what I have seen in practice. The approach works well when the team treats the manifest as a source of truth rather than a nice-to-have reference. It fails when people update tool configurations without updating the manifest. I have watched projects abandon the practice after three months because maintaining the mapping file felt like extra work. The compromise that worked for my team was making the manifest generation part of the pre-commit hook. If the flag catalog is out of sync, the commit is rejected.

That is the core of it. Catalog your flags, resolve collisions, maintain a single source of truth, and automate the validation. Nothing dramatic about it. Just less confusion on the next release.