# 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 query "select instance_id, region, state from aws_ec2_instance order by region, instance_id" --all
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 query "select instance_id, region from aws_ec2_instance" --profile awspipe-test --all
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.
