tronador-cli

A cross-platform CLI for CloudOps Works Tronador workflows, AWS resource automation, IaC module auditing, and repository template lifecycle management.

This project is part of our comprehensive approach towards DevOps Acceleration.

It's 100% Open Source and licensed under the APACHE2.

Introduction

AWS resource automation: Apply consistent organization metadata, remediate S3/EC2 security controls, copy Secrets Manager secrets, and remove default VPCs.
Infrastructure-as-code module auditing: Run tronador iac module in .cloudopsworks/.iac workspaces to report Terragrunt module source pins, list available patch/minor/major targets, detect missing Terraform git:: prefixes, and optionally update module refs safely.
Binary naming: Published release automation produces the clean tronador executable; plain local go build from this repository still emits tronador-cli unless -o tronador is passed.
Repository template lifecycle: Run the Tronador make repos/* workflow from the CLI with tronador repos, including template detection, latest-tag upgrades, explicit version upgrades, recovery, migration, CICD metadata updates, and push helpers.
README and docs generation: Port Tronador readme/* and docs/* Makefile targets into the CLI with tronador readme and tronador docs, including GitHub-backed runtime template asset sync.
Implicit project capabilities: Detect implementation markers and run namespace-free init, version, lint, format, and cleanup capabilities through CLI-native typed pipelines with tronador project.
Command documentation: Public command surfaces are documented in docs/commands.md, with dedicated guides for AWS automation, IaC module checks, project capabilities, repository lifecycle commands, branching and GitVersion workflows, and README/docs commands.
Config-driven upgrade paths: Repository templates and migration plans are loaded from JSON, so future upgrade paths such as 5.11 and 5.12 can be added without rewriting command dispatch code.
Release packages: GoReleaser publishes archives plus native Linux packages (.deb, .rpm, .apk), Homebrew casks, Chocolatey packages, and shell/PowerShell installers from the same release pipeline; release package names remain tronador-cli while the executable is tronador.
Cross-platform support: Linux, macOS, Windows, and FreeBSD builds are produced from a static CGO_ENABLED=0 binary.

Usage

Command Documentation

Start with the command index in docs/commands.md. Dedicated operator guides are available for:

AWS command — tagging, secret copy, default VPC removal, and security remediation.
IaC command — .cloudopsworks/.iac-guarded module source version checks and updates.
Project command — detection-driven, namespace-free capabilities and typed tool pipelines.
Repos command — repository template lifecycle workflows.
Versions command — branching workflows, GitVersion configuration, and guarded tags.
README/docs command — generated README files, Make target docs, Terraform docs, copyright headers, and runtime template assets.

Binary Names

Published releases expose the executable as tronador. The repository and package name remains tronador-cli. A plain local go build from the repository root creates ./tronador-cli; use go build -o tronador . when you want a local binary that matches release automation.

Global flags available from the root command:

--dry-run — show supported changes without applying them.
-v, --verbose — enable verbose output.

AWS Commands

tronador aws provides AWS automation subcommands. All AWS subcommands share profile, region, and assume-role flags documented in docs/aws-command.md.

aws tag — tag supported AWS resources with organization metadata.
aws copysecret — copy Secrets Manager secrets within an account, across regions, or across accounts.
aws remove-default-vpc — remove default VPCs across regions, with optional region exclusions.
aws remediation s3 — enforce SSL/TLS-only S3 bucket access.
aws remediation ec2 — remove unrestricted rules from default security groups.

Infrastructure-as-Code Commands

tronador iac commands run only when --workdir contains .cloudopsworks/.iac.

iac module — scan terragrunt.hcl files for direct GitHub module sources with ?ref= pins, report available patch/minor/major targets, flag missing git:: prefixes, and optionally mutate the selected tier.
Compatibility aliases: iac module-versions and iac module_versions.
--path limits module discovery without changing marker validation; relative paths resolve under --workdir and paths outside --workdir are rejected.

See docs/iac-command.md for supported source forms, mutation flags, dry-run behavior, and CI reporting options.

Repository Template Commands

tronador repos ports the supported public Tronador make repos/* targets into the CLI. tronador repo is an alias for the same command tree.

repos available / repos avail — list latest compatible template tags.
repos template init and repos template <kind> — pull configured template repositories.
repos clean, repos clean template, and repos template clean — clean generated or temporary template files.
repos upgrade [version] — run the full template upgrade workflow; [version] is optional.
repos recover — overlay template files without committing.
repos push — commit the changes already staged by the caller.
repos cicd update — update the workflow-version metadata footer.

repos upgrade preserves implementation-owned GitHub templates: issue templates including config.yml and .github/PULL_REQUEST_TEMPLATE.md are copied only when missing; .github/dependabot.yml is copied only when the template has it and the implementation repository does not; reserved 98_* and 99_* template-only issue forms are never propagated. Target generation is detected from active CloudOps workflow blueprint references (not application _VERSION); missing or mixed references stop the upgrade. For v5.10 targets, all .cloudopsworks configuration YAML uses the template as a documented/default baseline while retaining active repository values. This includes root policy YAML such as cloudopsworks-ci.yaml, labeler, GitVersion, and auto-assignment configuration, plus applicable vars, Helm, API-gateway, and preview configuration; local-only YAML paths are preserved with warnings. Only an explicitly configured opaque boilerplate subtree is byte-for-byte exact-refreshed; root policy YAML is value-aware merged, not treated as opaque. Input scaffold selection first treats any local # Agents: declarations as authoritative. Declarations may use | alternatives for cloud or cloud_type; every declared combination must resolve to exactly one same template baseline. Otherwise, the file is preserved with a warning and Tronador does not fall back to an exact filename, mobile, or global selection. Without local Agents metadata, it prefers an exact relative filename, then one active Android/XCode/Flutter mobile family, and finally cloud/cloud_type from vars/inputs-global.yaml (including Kubernetes, Lambda, Beanstalk, App Engine, Cloud Run, and library targets). Exact or custom dev/uat/prod files retain their local names; missing or ambiguous baselines preserve the local file with a warning. Unsafe duplicate, alias/anchor, or multi-document YAML stops the upgrade before _VERSION changes; --dry-run reports the plan without mutation. v5.9-layout upgrades migrate and merge only target-matching legacy root CloudOps YAML (including auto-assignment); arbitrary GitHub operational YAML is not migrated as configuration. Targets that remain pre-v5.10 copy auto-assign files only when missing. The template .gitignore content is managed in a marker-delimited block while user content outside the block is preserved; an unmarked or malformed file is treated as user-owned and receives a fresh managed block.

The command uses the embedded JSON catalog at internal/repos/default_config.json by default. Override it with --config path/to/repos-config.json when testing new repository types or future migration plans.

For the full command mapping and architecture notes, see docs/repos-command.md.

Implicit Project Capabilities

tronador project detects a supported implementation from .cloudopsworks/ and runs namespace-free capabilities such as init, version, lint, and format through CLI-native typed tool pipelines. project version --generate --yes is reserved for catalog-managed, versioned template-derived repositories: it updates the legacy blueprint _VERSION marker, warns on replacement, and never tags, commits, or pushes. See docs/project-command.md for detection, tool flags, and safety behavior.

Repository Branching and GitVersion Workflows

tronador versions configures GitFlow, GitHub Flow, or trunk-based GitVersion behavior and runs guarded feature, hotfix, release, support, and tag workflows. gitflow, gf, githubflow, and flow are aliases for the same command tree.

versions init --gitflow|--githubflow|--trunkbased — install a checked-in GitVersion workflow; an unset workflow can be selected interactively when CI explicitly disables GitFlow. GitFlow alone creates and publishes develop.
versions feature — start, publish, finish, or purge feature branches; publish, finish, and purge infer a missing name from the current feature branch.
versions hotfix — start the next patch, publish or finish the current hotfix, or purge a named/current hotfix.
versions release — start a patch, minor, or major release; publish or purge a named/current release, or finish the current release.
versions support — manage persistent maintenance branches in GitFlow only.
versions tag [qualifier] --publish — create the legacy GitVersion tag and optionally push it.

GitVersion and gh use the same local-first tool provisioner as project: --tool-path, PATH, the existing --tools-dir cache, then an opt-in download. --allow-network permits only a missing-tool download; --no-install-tools remains an absolute veto, and --tool-version name=version selects a download version without overriding a usable local executable. Git remains controlled separately by --git and is never provisioned. GitVersion is resolved only for version-calculating hotfix/release starts and tags; gh is resolved only for pull-request finishes, never for local finishes or already-contained releases. Downloading gh does not authenticate it. CLI --dry-run does not resolve tools, load tool configuration, create a cache, or execute external commands.

Finishes and tags require the named local branch to exactly match its origin branch. --main-branch must name a safe branch available at origin; --dry-run is mutation-free for all workflow actions. Purges prove the branch is merged before safe deletion. Local hotfix/release finishes use a schema-v4 journal: after local merge/tag work, they publish every required target, the exact annotated tag, and source deletion in one lease-protected atomic server push. Unsupported atomic remotes and prepublished/no-op state fail closed with the journal and source preserved; a retry after an unacknowledged transaction verifies remote target ancestry and exact tag identity before local cleanup. See docs/versions-command.md for workflow-sensitive bases, all flags, and safety guards.

README and Documentation Commands

tronador readme and tronador docs port the Tronador readme/* and docs/* Makefile targets into the release binary.

readme build — prepare each file listed in README.yaml.include, then generate README.md with gomplate. Built-in handlers generate docs/terraform.md with terraform-docs and docs/targets.md with Make.
readme build terraform — generate only docs/terraform.md; tf and tofu are concise aliases.
readme init — create README.yaml from the selected runtime template when missing.
readme lint — fail when README.md is not up to date.
readme assets sync — explicitly download canonical README templates from GitHub into the local cache or project override directory.
docs targets — generate docs/targets.md from make help output.
docs terraform — generate docs/terraform.md from terraform-docs.
docs copyright-add — run the configured copyright-header command.

README include preparation is registry-driven and extensible. Unknown include entries are passed unchanged to Make. A failed unknown target does not fail the README build: Tronador writes a warning to stderr and creates a comment-only Markdown placeholder explaining that the target is not supported yet. --make selects the Make executable.

README tool provisioning is per-tool and on-demand: readme build, readme lint, and readme deps resolve gomplate and, when docs/terraform.md is requested, terraform-docs from explicit flags, PATH, then ~/.cloudopsworks/tronador/. Only a requested missing tool is downloaded. The provisioner downloads direct upstream GitHub release assets and does not use tronador-packages.

Tool metadata is JSON-driven instead of hardcoded in Go. The binary ships an embedded tools.json with default definitions for gomplate, terraform-docs, gh, boilerplate, gitversion, yq, go, git, terraform, tofu, and terragrunt. Runtime overrides can be supplied from ~/.cloudopsworks/tronador/tools.json, project .cloudopsworks/tronador/tools.json, project .tronador/tools.json, TRONADOR_TOOLS_CONFIG, or --tools-config; overrides merge field-by-field by tool name.

README generator assets resolve in this order: flags, environment variables, project-local .tronador/readme, user config, GitHub sync cache, shared install paths, then embedded fallback assets. Template refresh remains explicit through readme assets sync when you want to refresh templates from GitHub.

See docs/readme-docs-command.md for full flags, dependency expectations, and cache behavior.

Version and Completion

tronador version — print the release binary version.
tronador completion <shell> — generate Cobra shell completion scripts.

Make Command Support

The project includes make command support that works with both make and gmake where the Tronador Makefile provides the target:

# Build the application
make build

# Build for all platforms
make build-all

# Run tests with coverage
make test-cover

# Clean build artifacts
make clean

Development

Building

# Build for current platform
make build

# Plain Go source build; outputs ./tronador-cli because of the module directory name
go build .

# Local build matching the release executable name
go build -o tronador .

# Build for all platforms
make build-all

# Run tests
make test

# Run tests with coverage
make test-cover

Release validation

# Validate installer scripts
scripts/validate-installers.sh

# Validate GoReleaser config, including archives, Homebrew, Chocolatey, and nFPM packages
goreleaser check

# Build a local snapshot without publishing
goreleaser release --snapshot --clean --skip=before --skip=publish --skip=sign

Contributing

Fork the repository.
Create a feature branch.
Make your changes.
Run tests: make test.
Submit a pull request.

Quick Start

Prerequisites

For installed binaries:

AWS credentials with the required permissions for tronador aws ... commands.
GitHub authentication through GH_TOKEN, GITHUB_TOKEN, or gh auth login when running tronador repos commands or tronador iac module version checks that query GitHub tags.
IaC workspaces must contain .cloudopsworks/.iac before tronador iac ... commands will run.

For source builds:

Go 1.26.5 or later, matching the module toolchain target.
make or gmake if you use the repository Makefile targets.

Installation

Install from published GitHub Release artifacts. The release pipeline publishes shell and PowerShell installers, Homebrew and Chocolatey metadata, native Linux packages, and zip archives. See docs/installation.md for version pinning, upgrade, uninstall, and maintainer workflow details.

Platform / manager	Install command
Linux/macOS shell	`curl -fsSL https://raw.githubusercontent.com/cloudopsworks/tronador-cli/master/scripts/install.sh \| sh`
Windows PowerShell	`iwr https://raw.githubusercontent.com/cloudopsworks/tronador-cli/master/scripts/install.ps1 -UseB \| iex`
Homebrew	`brew install cloudopsworks/tap/tronador-cli`
Chocolatey	`choco install tronador-cli`

Native Linux packages are attached to each release. Download the asset for your version and architecture, then install it locally:

# Debian / Ubuntu
sudo apt install ./tronador-cli_<version>_<arch>.deb

# RHEL / Fedora / CentOS
sudo dnf install ./tronador-cli-<version>-1.<arch>.rpm
# or: sudo rpm -i ./tronador-cli-<version>-1.<arch>.rpm

# Alpine Linux
sudo apk add --allow-untrusted ./tronador-cli_<version>_<arch>.apk

Direct zip archives remain available for every supported OS/architecture through GitHub Releases. Release archives contain the tronador executable.

For development builds from source:

git clone https://github.com/cloudopsworks/tronador-cli.git
cd tronador-cli
make build

# Plain Go output name from this checkout
go build .          # ./tronador-cli

# Release-style executable name
go build -o tronador .

Examples

Audit IaC module sources

# Report module versions in an IaC workspace
tronador iac module --workdir ../my-iac-workspace

# Report available patch, minor, and major targets for one environment path
tronador iac module --workdir ../my-iac-workspace --path env/dev

# Preview default patch upgrades and missing git:: prefix normalization
tronador iac module --workdir ../my-iac-workspace --path env/dev --upgrade --dry-run

# Apply the default patch target and git:: prefix fixes
tronador iac module --workdir ../my-iac-workspace --path env/dev --upgrade

# Select a broader release tier instead of the default patch target
tronador iac module --workdir ../my-iac-workspace --path env/dev --upgrade --minor
tronador iac module --workdir ../my-iac-workspace --path env/dev --upgrade --major

# Allow alpha and beta prereleases when selecting updates
tronador iac module --workdir ../my-iac-workspace --upgrade --alpha --beta

Tag AWS Resources

tronador aws tag \
  --organization "MyOrg" \
  --organization-unit "DevOps" \
  --application-name "WebApp" \
  --application-type "Service" \
  --target resources

Copy an AWS secret

# Copy within the same account and region
tronador aws copysecret --source my-secret --dest my-secret-copy

# Copy to another region
tronador aws copysecret --source my-secret --dest my-secret-copy --dest-region us-west-2

Remove Default VPCs

tronador aws remove-default-vpc \
  --exclude-regions "us-west-2,eu-west-1"

Remediate AWS security controls

# Preview S3 SSL/TLS enforcement policy changes
tronador aws remediation s3 --dry-run

# Preview EC2 default security group remediation in a region
tronador aws remediation ec2 --region us-east-1 --dry-run

Upgrade repository templates

# Show available template versions for the detected repository type
tronador repos available --workdir ../my-service

# Run the default full upgrade workflow using the latest tag in the current major/minor line
tronador repos upgrade --workdir ../my-service

# Run the same full workflow against an explicit tag or branch
tronador repos upgrade v5.10.12 --workdir ../my-service

# Run the same full workflow against the latest tag in the current major line
tronador repos upgrade major --workdir ../my-service

# Run the same full workflow from the template repository master branch tip
tronador repos upgrade master --workdir ../my-service

repos upgrade intentionally exposes a single public workflow. Internal Makefile stages such as fetch, eval, migrate, and stack are handled inside the command instead of being separate subcommands. Public workflows clean up their temporary .template checkout when they finish or fail.

Generate README and docs

# Create README.yaml when missing
tronador readme init --workdir ../my-service

# Sync editable README generator templates from GitHub into the project
tronador readme assets sync --project --workdir ../my-service

# Build and validate README.md; README.yaml.include controls generated dependencies
tronador readme build --workdir ../my-service
tronador readme lint --workdir ../my-service

# Generate only Terraform/OpenTofu module docs (tf and tofu are aliases)
tronador readme build terraform --workdir ../my-terraform-module

# Generate Make target docs, or use the standalone Terraform docs command
tronador docs targets --workdir ../my-service --all
tronador docs terraform --workdir ../my-terraform-module

# Preview copyright-header execution
tronador docs copyright-add --workdir ../my-service --software-description "My service" --dry-run

Version and help

tronador version
tronador iac module --help
tronador aws remediation --help

Help

Got a question? We got answers.

File a GitHub issue, send us an email or join our Slack Community.

DevOps Tools

Our Products CI/CD Blueprint Open Source

Slack Community

Newsletter

Resources Directory

Bug Reports & Feature Requests

Please use the issue tracker to report any bugs or file feature requests.

Copyrights

License

See LICENSE for full details.

Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.

Trademarks

All other trademarks referenced herein are the property of their respective owners.

About

This project is maintained by Cloud Ops Works LLC.

Contributors

Cristian Beraha

Name		Name	Last commit message	Last commit date
.cloudopsworks		.cloudopsworks
.github		.github
apifiles		apifiles
docs		docs
integration		integration
internal		internal
packaging		packaging
scripts		scripts
.dockerignore		.dockerignore
.gitignore		.gitignore
.goreleaser.yml		.goreleaser.yml
.helmignore		.helmignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CNAME		CNAME
CONTRIBUTING.md		CONTRIBUTING.md
DESIGN.md		DESIGN.md
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
LICENSE		LICENSE
Makefile		Makefile
README-TEMPLATE.md		README-TEMPLATE.md
README.md		README.md
README.yaml		README.yaml
go.mod		go.mod
go.sum		go.sum
main.go		main.go
version.go		version.go

Latest commit

History

Folders and files

Repository files navigation

tronador-cli

Introduction

Usage

Command Documentation

Binary Names

AWS Commands

Infrastructure-as-Code Commands

Repository Template Commands

Implicit Project Capabilities

Repository Branching and GitVersion Workflows

README and Documentation Commands

Version and Completion

Make Command Support

Development

Building

Release validation

Contributing

Quick Start

Prerequisites

Installation

Examples

Audit IaC module sources

Tag AWS Resources

Copy an AWS secret

Remove Default VPCs

Remediate AWS security controls

Upgrade repository templates

Generate README and docs

Version and help

Help

DevOps Tools

Slack Community

Newsletter

Bug Reports & Feature Requests

Copyrights

License

Trademarks

About

Contributors

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages