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.
Scan again when things change
Section titled “Scan again when things change”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.
awnexa scanawnexa snapshot list --format tableWhen 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.
Scheduled scans
Section titled “Scheduled scans”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.
# crontab: every Monday at 07:000 7 * * 1 cd /path/to/infra && awnexa scan --log-level errorawnexa scan exits with 4 when some services could not be read, so a CI job can flag it.
Weekly scans in GitHub Actions
Section titled “Weekly scans in GitHub Actions”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 scanon: 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 changesconcurrency: awnexa-weeklyjobs: 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 fiBefore the first run:
- Create an IAM role that GitHub Actions can assume with OpenID Connect and that has only the
ReadOnlyAccessmanaged policy, and save its ARN as the repository variableAWNEXA_ROLE_ARN. See Configuring OpenID Connect in Amazon Web Services. - Set the regions in
--regionandaws-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.
See what changed
Section titled “See what changed”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.
awnexa snapshot diff --as markdownawnexa snapshot diff <older-scan-id> <newer-scan-id> --as markdownResources 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.
Write design documents
Section titled “Write design documents”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.
awnexa report --out docs/awsThe coverage notes (⚠) in the documents mark what could not be checked; keep them when you edit the documents.
Use the data in your own tools
Section titled “Use the data in your own tools”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.
awnexa export --out scan.jsonawnexa export --as ndjson --split --out export/Several AWS accounts
Section titled “Several AWS accounts”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.
awnexa --data-dir ~/awnexa/prod init --profile prod-readonly --region us-east-1awnexa --data-dir ~/awnexa/prod scanTo let Claude Code read a directory other than ./.awnexa, register the MCP server with the same
--data-dir (see Use with Claude Code).
Free up disk space
Section titled “Free up disk space”Snapshots and their evidence files are never deleted automatically. To delete old ones, check the plan first, then run it:
awnexa snapshot prune --keep 3 --dry-runawnexa snapshot prune --keep 3 --vacuumThe newest completed (or partial) scan of each account is always kept. Deleted snapshots cannot be restored.
Update Awnexa
Section titled “Update Awnexa”npm install -g awnexa@latestawnexa skills install --project ~/work/my-infra --forceThe 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.
When something goes wrong
Section titled “When something goes wrong”| 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.
Usage statistics
Section titled “Usage statistics”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:
awnexa telemetry statusawnexa telemetry showawnexa telemetry disableSee Data the CLI sends for every field.