Metadata-Version: 2.4
Name: infra-cli
Version: 0.1.3
Summary: Pluggable Infrastructure CLI as a wrapper around DevOps tools.
Author-email: Youqing Han <ihanyouqing@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/hanyouqing/infra-cli
Project-URL: Bug Tracker, https://github.com/hanyouqing/infra-cli/issues
Project-URL: Changelog, https://github.com/hanyouqing/infra-cli/blob/main/CHANGELOG.md
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: colorama>=0.4
Requires-Dist: PyYAML>=6.0
Requires-Dist: boto3>=1.20.0
Requires-Dist: rich>=10.0.0
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-mock>=3.6.1; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Provides-Extra: dev
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pip-tools>=7.0.0; extra == "dev"
Dynamic: license-file

# infra-cli

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)

`infra-cli` is a pluggable infrastructure management tool designed to wrap common DevOps tools (Terragrunt, Ansible, Pulumi, Packer, Terraform, etc.) into a single, unified interface. It simplifies complex workflows through sensible conventions and centralized configuration, and helps learners follow **best practices** from day one (directory layout, config, and official-style docs).

## 🎓 DevOps Learning

Use `infra` to create **learning projects** that follow best-practice structure and include READMEs with official docs, tool best practices, and a **step-by-step learning path** from zero to advanced infrastructure engineer:

```bash
# Create a Python project (src layout, pyproject.toml, tests, README with learning path)
infra python -p learn-python

# Ansible: scaffold playbooks and structure
infra ansible -p learn-ansible --create

# Terragrunt: scaffold multi-env layout (account/region/env/name)
infra tg -e dev -p learn-tg -r us-east-1 -s vpc --create
```

Recommended order: **Python** → **Ansible** → **Terraform / Terragrunt** → **Packer** → **Pulumi** → (future K8s). See [docs/LEARNING_PATH.md](docs/LEARNING_PATH.md) for the full path and links to official documentation.

## 🚀 Key Features

- **Unified Interface**: A single command (`infra`) to manage multiple infrastructure tools.
- **Plugin Architecture**: Easily extensible logic for different tools.
- **Convention over Configuration**: Default directory structures that "just work."
- **Centralized Config**: Manage all tool settings in one place (`~/.infra/config.yaml`).
- **AWS SSO Integration**: Seamlessly handles authentication and profile generation.
- **Local Environment Setup**: Automate the configuration of your macOS or Ubuntu dev environment.

## 🛠 Supported Plugins

- **`python`**: Scaffold a best-practice Python project (src layout, pyproject.toml, README with official docs and learning path). Example: `infra python -p learn-python`.
- **`setup`**: Bootstrap your local development environment (macOS/Ubuntu).
- **`ansible`**: Wrapper for `ansible-playbook` with automatic project scaffolding (`--create`).
- **`aws`**: AWS subcommands: `login` (SSO, default), `sync` (sync account/role profiles), `whoami` (caller identity), `exec` (run any AWS CLI command), `env` (print `export AWS_PROFILE=...` for eval).
- **`packer`**: Build and validate machine images consistently.
- **`terragrunt`**: Manage Terraform state and deployments with Terragrunt; `--create` scaffolds AWS-style layout.
- **`terraform`**: Run native Terraform commands (plan, apply, etc.) with infra context.
- **`pulumi`**: Infrastructure as Code using Pulumi.
- **`github`**: Manage repository settings and scaffolding.
- **`slack`**: Send notifications to Slack webhooks.

## 🏁 Quick Start

### Installation

**From PyPI** (recommended):

```bash
brew install pipx
brew upgrade pipx
pipx install infra-cli
# or: pip install infra-cli
```

If you see *"No matching distribution found"* or *"Requires-Python >=3.12"*, pipx may be using a Python &lt; 3.12. Use the interpreter that satisfies the requirement:

```bash
pipx install --python python3.12 infra-cli
# or from your venv: pip install infra-cli
```

**From source** (development or unreleased version):

```bash
git clone https://github.com/hanyouqing/infra-cli.git
cd infra-cli
pipx install .
# or: pip install -e .
```

Source install uses Python 3.12+ (see `pyproject.toml`).

### Basic Usage

```bash
# Setup your local environment
infra setup

# AWS: SSO login (default), whoami, or run CLI with profile
infra aws
infra aws whoami --profile sso
infra aws exec s3 ls
eval $(infra aws env --profile sso)

# Run an Ansible playbook
infra ansible site.yml

# Check configuration
infra config
```

## ⚙️ Configuration

`infra-cli` uses a YAML configuration file located at `~/.infra/config.yaml`.

### Managing Config via CLI

You can get or set configuration values directly:

```bash
# Set a default user name for the setup plugin
infra config setup.user_name=your_name

# View current configuration
infra config
```

### Manual Configuration

The default `config.yaml` is generated on first run with sensible defaults. You can customize per-plugin settings like `region`, `env`, or `extra_args`.

### Configurable Directory Tree (Terragrunt / Terraform)

For `terragrunt` and `terraform` plugins, the directory tree used by `--create` and path resolution is configurable via `path_pattern`:

```yaml
terragrunt:
  path_pattern: ${account}/${region}/${env}/${name}   # default
  # Or your own layout, e.g.:
  # path_pattern: ${env}/${account}/${region}/${service}/${name}
```

Placeholders: `${env}`, `${account}`, `${region}`, `${service}`, `${name}`. Map to CLI: `-e`→env, `-p`→account, `-r`→region, `-s`→service/name. Empty segments are omitted.

## 👩‍💻 Development

We welcome contributions! To set up your local development environment:

1. **Clone the repo**: `git clone https://github.com/hanyouqing/infra-cli.git`
2. **Install dev dependencies**: `make dev-install` (or for a reproducible env: `pip install -r requirements.txt` then `pip install -e .`)
3. **Optional – regenerate lock file**: `make lock` (requires pip-tools; updates `requirements.txt` from `pyproject.toml`)
4. **Run linting**: `make lint`
5. **Run tests**: `make test`

For more details, see [CONTRIBUTING.md](CONTRIBUTING.md).

## 📜 License

This project is licensed under the Apache-2.0 License. See the [LICENSE](LICENSE) file for details.
