Metadata-Version: 2.4
Name: awspipe
Version: 0.1.0
Summary: A Steampipe-style AWS SQL CLI powered by DuckDB.
Project-URL: Homepage, https://github.com/fernansd/steampipe-aws-port
Project-URL: Repository, https://github.com/fernansd/steampipe-aws-port
Project-URL: Issues, https://github.com/fernansd/steampipe-aws-port/issues
Project-URL: Documentation, https://github.com/fernansd/steampipe-aws-port#readme
Author-email: "Fernando S." <code@fernansd.dev>
Keywords: aws,cli,duckdb,sql,steampipe
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.13
Requires-Dist: awscrt>=0.23.0
Requires-Dist: boto3>=1.40.0
Requires-Dist: duckdb>=1.2.0
Requires-Dist: platformdirs>=4.3.0
Requires-Dist: prompt-toolkit>=3.0.51
Requires-Dist: rich>=14.0.0
Requires-Dist: sqlglot>=27.0.0
Requires-Dist: typer>=0.16.0
Provides-Extra: dev
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Description-Content-Type: text/markdown

# awspipe

`awspipe` is a small Python CLI that mimics the Steampipe workflow for AWS queries: point it at AWS CLI credentials, expose AWS resources as SQL tables, and execute queries against a local DuckDB cache.

## What it does today

- Uses AWS CLI-managed credentials through `boto3`
- Exposes these tables:
  - `aws_account`
  - `aws_region`
  - `aws_s3_bucket`
  - `aws_ec2_instance`
  - `aws_vpc`
  - `aws_subnet`
  - `aws_security_group`
- Provides a SQL-first CLI with `query`, `shell`, `tables`, `inspect`, `doctor`, and `cache clear`
- Stores fetched data in a local DuckDB database with a short TTL cache
- Works on Windows by default through normal Python and AWS CLI conventions

## Requirements

- Python 3.13+
- AWS CLI configured with a working profile or default credentials
- `login_session`-based AWS profiles are supported through the bundled `awscrt` dependency

## Install

Install from PyPI:

```powershell
pip install awspipe
```

Or with `uv`:

```powershell
uv tool install awspipe
```

## Quick start

Run the CLI directly after install:

```powershell
$env:AWS_PROFILE = "awspipe-test"
$env:AWS_REGION = "eu-west-1"
awspipe tables
awspipe doctor
awspipe query "select account_id, arn from aws_account"
awspipe query "select name, region from aws_s3_bucket order by name"
awspipe query "select instance_id, state, vpc_id from aws_ec2_instance"
awspipe shell
```

## Windows notes

- `awspipe` stores its DuckDB cache under the platform cache directory unless `AWSPIPE_HOME` is set.
- If that directory is not writable, `awspipe` falls back to `.awspipe` in the current working directory.
- On Windows, setting `AWSPIPE_HOME` is the easiest way to isolate test runs:

```powershell
$env:AWSPIPE_HOME = "$PWD\.awspipe-home"
```

- AWS credentials are loaded in this order:
  - `--profile`
  - `AWS_PROFILE`
  - default AWS SDK credential chain

## Command reference

```powershell
awspipe query "select * from aws_account" --profile awspipe-test --region eu-west-1
awspipe shell --profile awspipe-test --region eu-west-1
awspipe tables
awspipe inspect aws_vpc
awspipe doctor --profile awspipe-test --region eu-west-1
awspipe cache clear
```

The interactive shell supports these meta commands:

- `.tables`
- `.inspect <table>`
- `.schema <table>`
- `.connections`
- `.refresh <table>`
- `.quit`

## Project docs

- Brief contributor and agent entrypoint: [AGENTS.md](https://github.com/fernansd/steampipe-aws-port/blob/main/AGENTS.md)
- Architecture overview: [docs/architecture.md](https://github.com/fernansd/steampipe-aws-port/blob/main/docs/architecture.md)
- Codebase map: [docs/codebase-map.md](https://github.com/fernansd/steampipe-aws-port/blob/main/docs/codebase-map.md)
- Library and dependency notes: [docs/libraries-and-dependencies.md](https://github.com/fernansd/steampipe-aws-port/blob/main/docs/libraries-and-dependencies.md)
- Provider extension guide: [docs/extending-awspipe.md](https://github.com/fernansd/steampipe-aws-port/blob/main/docs/extending-awspipe.md)
- Development workflow: [docs/development-workflow.md](https://github.com/fernansd/steampipe-aws-port/blob/main/docs/development-workflow.md)
- Live AWS validation: [docs/testing-live-aws.md](https://github.com/fernansd/steampipe-aws-port/blob/main/docs/testing-live-aws.md)

## Development workflow

```powershell
$env:UV_CACHE_DIR='.uv-cache'
uv sync --extra dev
uv run pytest
```

For detailed contributor guidance, use `AGENTS.md` and the docs under `docs/`.

## Live AWS testing

Stage 1 stops before live AWS validation is considered complete. After the implementation and non-live tests are in place, provide a working AWS CLI profile and region and continue with the steps in `docs/testing-live-aws.md`.

## Current limitations

- Authentication is AWS CLI credential-chain only; custom app config is deferred.
- Multi-account aggregators and assume-role configuration are not exposed yet.
- The backend is DuckDB-only in this first implementation.
- The initial table set is intentionally small and AWS-only.
