awspipe 0.1.2

A Steampipe-style AWS SQL CLI powered by DuckDB.

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:

pip install awspipe

Or with uv:

uv tool install awspipe

Quick start

Run the CLI directly after install:

$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:

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

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

Command reference

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 shell commands and meta commands:

• quit or exit
• .quit or .exit
• .tables
• .inspect <table>
• .schema <table>
• .connections
• .refresh <table>

Project docs

• Brief contributor and agent entrypoint: AGENTS.md
• Architecture overview: docs/architecture.md
• Codebase map: docs/codebase-map.md
• Library and dependency notes: docs/libraries-and-dependencies.md
• Provider extension guide: docs/extending-awspipe.md
• Development workflow: docs/development-workflow.md
• Live AWS validation: docs/testing-live-aws.md

Development workflow

$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.