Skip to content

Everyday use

Awnexa answers from the last scan, not from AWS directly. Keeping it useful is mostly a matter of scanning again when your system changes and letting Claude Code compare the scans.

Run awnexa scan before a design review or an investigation, after a deployment, or on a regular schedule. Each scan is saved as a new snapshot; older ones are kept. When the latest scan is 7 days old or more, the outputs say so (staleWarning), so Claude Code tells you how old its answer’s data is.

Terminal window
awnexa scan
awnexa snapshot list --format table

When Claude Code (or awnexa status) reports a warning about a newer scan that failed or is still running, the data it shows is older than that scan. Scan again before relying on it.

Any scheduler that can run a command works, such as cron or a CI job. Use credentials that can only read (see AWS access) and keep the data directory where the next run can find it.

Terminal window
# crontab: every Monday at 07:00
0 7 * * 1 cd /path/to/infra && awnexa scan --log-level error

awnexa scan exits with 4 when some services could not be read, so a CI job can flag it.

This workflow scans every Monday and opens an issue listing what changed since the previous scan. The data directory is passed from one run to the next as a workflow artifact (a cache is dropped after 7 days unused, so a weekly job could lose it). Save it as .github/workflows/awnexa-weekly.yml.

name: Awnexa weekly scan
on:
schedule:
- cron: '0 22 * * 0' # Mondays 07:00 in Japan (UTC+9)
workflow_dispatch:
permissions:
contents: read
id-token: write # sign in to AWS with OIDC
actions: read # download the data directory of the previous run
issues: write # open an issue with the changes
concurrency: awnexa-weekly
jobs:
scan:
runs-on: ubuntu-latest
env:
AWNEXA_HOME: ${{ github.workspace }}/awnexa-data
GH_TOKEN: ${{ github.token }}
steps:
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm install -g awnexa@0.2.0
- name: Restore the data directory of the last successful run
run: |
run_id=$(gh run list -R "$GITHUB_REPOSITORY" --workflow awnexa-weekly.yml --status success \
--limit 1 --json databaseId --jq '.[0].databaseId // empty')
if [ -n "$run_id" ]; then
gh run download "$run_id" -R "$GITHUB_REPOSITORY" -n awnexa-data -D "$AWNEXA_HOME"
fi
- uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: ${{ vars.AWNEXA_ROLE_ARN }}
aws-region: ap-northeast-1
- name: Scan
run: |
awnexa scan --region ap-northeast-1,us-east-1 --log-level error || {
code=$?
[ "$code" -eq 4 ] || exit "$code"
echo "::warning::Some services could not be read (exit code 4)"
}
- name: Keep the 3 newest scans
run: awnexa snapshot prune --keep 3 --yes
- uses: actions/upload-artifact@v4
with:
name: awnexa-data
path: ${{ env.AWNEXA_HOME }}
retention-days: 30
- name: Open an issue when something changed
run: |
if ! awnexa snapshot diff --no-persist > diff.json 2> error.json; then
jq -e '.error.code == "NO_SCAN"' error.json > /dev/null || { cat error.json; exit 1; }
echo "First scan: nothing to compare with yet"
exit 0
fi
changes=$(jq '.summary.created + .summary.modified + .summary.deleted + .summary.unknown' diff.json)
if [ "$changes" -gt 0 ]; then
awnexa snapshot diff --no-persist --as markdown > diff.md
head -c 60000 diff.md > body.md # an issue body holds up to 65,536 characters
gh issue create -R "$GITHUB_REPOSITORY" --title "AWS changes $(date -u +%F)" --body-file body.md
fi

Before the first run:

  • Create an IAM role that GitHub Actions can assume with OpenID Connect and that has only the ReadOnlyAccess managed policy, and save its ARN as the repository variable AWNEXA_ROLE_ARN. See Configuring OpenID Connect in Amazon Web Services.
  • Set the regions in --region and aws-region, and pin the Awnexa version you have tested.
  • Use a private repository. The artifact holds the scan results and the issue lists resource names and changed settings, so everyone who can read the repository can read them. Secret values are masked before they are saved, but names, IDs and tags are not.

The first run has nothing to compare with, so it only saves the data directory. An issue is opened only when resources were created, modified, deleted or could not be compared (unknown); a very long diff is cut to fit in the issue. The free edition compares the 3 newest scans, so the workflow keeps 3. If no run succeeds for 30 days, the artifact expires and the next run starts again from a first scan.

Compare two scans of the same account. Without scan IDs, the latest scan is compared with the one before it; for other scans, take the IDs from awnexa snapshot list.

Terminal window
awnexa snapshot diff --as markdown
awnexa snapshot diff <older-scan-id> <newer-scan-id> --as markdown

Resources are reported as created, modified (with the properties that changed) or deleted. If a service could not be read completely in either scan, a missing resource is reported as unknown rather than deleted. Or ask Claude Code: “What changed since the previous scan?”

The free edition compares the 3 newest snapshots of an account. Older snapshots stay in the database and can still be read.

awnexa report writes Markdown documents with Mermaid diagrams (overview, network, security, inventory and coverage) from a scan. Commit them next to your code or share them with your team.

Terminal window
awnexa report --out docs/aws

The coverage notes (⚠) in the documents mark what could not be checked; keep them when you edit the documents.

awnexa export writes a whole scan as JSON or NDJSON, and every other command prints JSON, so you can process the results in scripts or CI.

Terminal window
awnexa export --out scan.json
awnexa export --as ndjson --split --out export/

The free edition keeps one AWS account per data directory. Give each account its own directory, and pick it with --data-dir or the AWNEXA_HOME environment variable.

Terminal window
awnexa --data-dir ~/awnexa/prod init --profile prod-readonly --region us-east-1
awnexa --data-dir ~/awnexa/prod scan

To let Claude Code read a directory other than ./.awnexa, register the MCP server with the same --data-dir (see Use with Claude Code).

Snapshots and their evidence files are never deleted automatically. To delete old ones, check the plan first, then run it:

Terminal window
awnexa snapshot prune --keep 3 --dry-run
awnexa snapshot prune --keep 3 --vacuum

The newest completed (or partial) scan of each account is always kept. Deleted snapshots cannot be restored.

Terminal window
npm install -g awnexa@latest
awnexa skills install --project ~/work/my-infra --force

The second command updates the Skills you installed into a project, so they match the new version. If you forget it, awnexa status run in that project lists the Skills an older Awnexa installed (skillsOutdated), and awnexa skills list shows the state of each. Changes are listed in the changelog.

What you see What to do
Exit code 3 (AWS_AUTH_FAILED) Check that the AWS CLI can use the profile: aws sts get-caller-identity --profile <name>
access_denied in awnexa coverage Attach ReadOnlyAccess; if it is already attached, allow the action from awnexa plugins (requiredIamActions), then scan again
unsupported in awnexa coverage The service or region is not supported yet. Treat it as “not checked”
ACCOUNT_LIMIT from awnexa scan The data directory already holds another account. Check --profile, or use another directory
SNAPSHOT_OUTSIDE_FREE_LIMIT from snapshot diff Compare scans among the 3 newest of the account

Errors are printed to stderr as JSON ({"error":{"code":…,"message":…}}). Add --log-level info (or debug) to see more of what the command is doing. If you are stuck, contact us.

The CLI sends anonymous usage statistics (on by default; never your AWS configuration data). You can check what is sent and turn them off at any time:

Terminal window
awnexa telemetry status
awnexa telemetry show
awnexa telemetry disable

See Data the CLI sends for every field.