Skip to content

CLI reference

awnexa [global options] <command> [options]

Every command prints JSON to stdout; logs and errors go to stderr. awnexa <command> --help shows the same information as this page for the version you have installed.

Contents: Global options · Setup and scanning · Querying · Snapshots and diffs · Documents and export · Claude Code · Information · Usage statistics · MCP tools · Settings file · Environment variables · Exit codes

Common conventions:

  • <ref> is a resource’s uid, ARN, resource ID (for example sg-0123456789abcdef0) or name. A name shared by several resources makes graph, impact and overview --entry stop with AMBIGUOUS_REF and the candidates; resources show lists them all. When nothing matches, the error lists candidates from a search.
  • --scan <id> picks a scan ID or latest. Without it, commands use the latest finished scan.
  • Options that take several values (--region, --type, --service, --status, …) accept a comma-separated list or can be repeated.
  • --limit and --offset page through long results. The output’s pagination.nextOffset is the next --offset.

Put these before the command name, for example awnexa --data-dir ~/awnexa/prod status.

Option Description
--data-dir <dir> Data directory. Default: $AWNEXA_HOME, the nearest ./.awnexa (here or in a parent), or ~/.awnexa
--format <format> json (default) or table. table is available for listing commands; the others print JSON with a warning on stderr
--compact Print JSON on a single line
--no-legend Leave out legend / itemLegend / metricsLegend (the same text in every response; read them once)
--log-level <level> stderr log level: silent, fatal, error, warn (default), info, debug, trace
-V, --version Print the version number
-h, --help Show help (also awnexa help <command>)

Creates a data directory (default ./.awnexa) with a settings file and a database.

Option Description
--profile <name> Default AWS profile to save (the name only, never credentials)
-r, --region <regions> Default region(s)
--force Overwrite an existing settings file
--sample Create a separate data directory (default ./.awnexa-sample; AWNEXA_HOME is ignored) with two scans of a made-up system, to try Awnexa without an AWS account. No AWS call, no credentials

Running init again with --profile or --region changes only those settings and keeps the rest. The output lists the commands to run next (next), and a warning when no default region is saved or set for the profile.

With --sample, every output says sample: true and carries sampleWarning. Pass --data-dir ./.awnexa-sample to the other commands to read it, and scan your real account into a different data directory.

Runs a read-only scan (Describe* / List* / Get* / BatchGet* / Search* APIs only) and saves a new snapshot. Exit code 0 means everything was collected; 4 means some coverage is partial or failed (what was read is still saved). A scan that runs longer than 30 seconds writes a {"progress":{...}} line to stderr every 30 seconds (API listings done and in total, resources so far); --log-level error turns it off.

Option Description
--profile <name> AWS profile. Credentials are resolved by the AWS SDK’s default chain
-r, --region <regions> Region(s) to scan
--all-regions Scan every region enabled for the account
-s, --services <ids> Only these service plugins (IDs from awnexa plugins). Default: all
--concurrency <n> Maximum parallel API listings
--no-evidence Do not write the raw (sanitized) API responses to disk
--metrics Also read 14 days of daily usage metrics for EC2, NAT gateways, RDS, Lambda, SQS, SNS, load balancers, API Gateway, DynamoDB, ECS, S3 and CloudFront (CloudWatch GetMetricData, billed per metric; needs cloudwatch:GetMetricData)

The data directory, database statistics and the latest scans. If a newer scan failed or is still running, the output has a warning. A running scan that has made no progress for 60 minutes was most likely killed and is marked possiblyStopped. scan.ageHours is the hours since the latest scan finished, and staleWarning appears when it is 7 days old or more (query commands such as resources list and overview carry both too). Before the first scan, hint says to run awnexa scan. When the current directory has Skills installed by an older Awnexa, skillsOutdated names them.

What was — and was not — collected, per service, region and API.

Option Description
--scan <id> Scan ID or latest
--status <statuses> Filter: complete, partial, unsupported, access_denied, failed, not_applicable, skipped, unknown
-r, --region <regions> Region(s)
-s, --service <services> Service namespace(s) such as ec2, or plugin ID(s) such as ec2-network

Lists the resources of a scan. Properties are left out unless you ask for them, and items are compact: the ARN only when it differs from the uid, the account only when it is not the scan’s, and the collection status or confidence only when they are not complete / direct. When the page is empty or may be incomplete, resultCoverage says why: filter values the scan does not know (with didYouMean), types, services or regions the scan did not read, types read only in other regions, and incomplete listing APIs.

Option Description
--scan <id> Scan ID or latest
-t, --type <types> Resource type(s), for example AWS::EC2::VPC
-s, --service <services> Service namespace(s) such as ec2, or plugin ID(s) from awnexa plugins such as ec2-network (the resource types that plugin collects)
-r, --region <regions> Region(s); global for global services (IAM, CloudFront, …)
--account <id> Owner account ID
--parent <uid> Parent resource uid, id or name (for example, the subnets of a VPC)
--tag <key[=value]> Tag key, or key and value
--name <text> Part of the name
--properties Include all properties
--fields <paths> Only these property paths, for example PubliclyAccessible,MasterUserSecret.SecretArn
--where <condition> Only resources whose properties meet Path=value or Path!=value (repeat for AND; arrays are followed). where in the output counts the resources left out because the path is missing (pathMissing, unretrieved): their value is unknown
--metrics Attach usage metric summaries (scans run with scan --metrics)
--provenance Full items: service, ARN, account and provenance (by default items are compact)
--limit <n> Page size, 1–1000 (default 50)
--offset <n> Page offset (default 0)

One resource with its properties, relationships and usage metrics. With --fields, relationships and metrics are left out unless you add --relationships or --metrics (the output lists them under omitted).

Option Description
--scan <id> Scan ID or latest
--relationships Include relationships (the default unless --fields is given)
--no-relationships Leave out relationships
--metrics Include usage metrics (the default unless --fields is given)
--no-metrics Leave out usage metrics
--fields <paths> Only these property paths (dot-separated, case-insensitive)
--outline Property keys with short values inline and large values summarized
--full All properties, even large ones (by default large properties are summarized)

Full-text prefix search over uid, ARN, ID, name, type and tags. Items are ordered best match first; resultCoverage explains an empty or short result as in resources list.

Option Description
--scan <id> Scan ID or latest
-t, --type <types> Only these resource type(s)
-r, --region <regions> Only these region(s); global for global services
--provenance Full items (as resources list)
--limit <n> Page size, 1–1000 (default 20)
--offset <n> Page offset (default 0)

Relationships of a scan, optionally around one resource.

Option Description
--scan <id> Scan ID or latest
--resource <ref> Only relationships of this resource
--direction <dir> out, in or both (default)
--type <types> network, traffic, security, data, deployment, monitoring, event, association, dependency
--target-status <s> resolved, unresolved or external
--limit <n> Page size, 1–1000 (default 100)
--offset <n> Page offset (default 0)

The neighborhood of a resource in the relationship graph.

Option Description
--scan <id> Scan ID or latest
--depth <n> Hops, 1–5 (default 1)
--max-nodes <n> Node cap, 1–2000 (default 200)
--direction <dir> out, in or both (default)
--type <types> Relationship type(s)
--as <format> json (default) or mermaid (a Mermaid flowchart)

What would be affected by changing or deleting a resource: everything that references it directly or indirectly, with the path that explains each one and the coverage caveats.

Option Description
--scan <id> Scan ID or latest
--depth <n> Hops, 1–8 (default 3)
--max-nodes <n> Result cap, 1–2000 (default 200)
--type <types> Relationship type(s) to follow
--min-confidence <c> Weakest relationship to follow: direct, derived or inferred (default)
--as <format> json (default) or mermaid

A system overview: every entry point (load balancer, CloudFront, API, function URL) with the routing, compute and data stores its requests reach, the gaps in each path and the coverage caveats.

Option Description
--scan <id> Scan ID or latest
-r, --region <regions> Entry point region(s); global for CloudFront
--entry <ref> One entry point only, following every resource and relationship
--max-paths <n> Entry points to expand, 1–500 (default 50)
--max-nodes <n> Resources per path, 1–2000 (default 200)
--group-by <by> stack (CloudFormation / AppRegistry, default), tag:<key> or none
--max-groups <n> Groups listed, 1–500 (default 50)

Scans, newest first.

Option Description
--account <id> Only this account
--limit <n> Page size, 1–1000 (default 20)
--offset <n> Page offset (default 0)

Full metadata of one scan: SDK versions, options, coverage and an error summary.

awnexa snapshot diff [baseScanId] [targetScanId]

Section titled “awnexa snapshot diff [baseScanId] [targetScanId]”

Compares two scans of the same account. Without scan IDs it compares the latest finished scan (latest) with the finished scan of the same account before it (previous); either can be given as a scan ID. A missing resource is reported as deleted or created only when its listing API completed in both scans; otherwise it is unknown. The free edition compares the 3 newest scans of an account.

Option Description
--change <types> created, modified, deleted, unchanged, unknown
-t, --type <types> Resource type(s)
--include-unchanged Also list unchanged resources
--no-persist Do not save the computed changes in the database
--limit <n> Page size, 1–1000 (default 200)
--offset <n> Page offset (default 0)
--as <format> json (default) or markdown (a report for people; filters apply, paging does not)
--max-property-changes <n> Markdown: property changes listed per modified resource, 1–1000 (default 20)
--lang <lang> Markdown: en or ja (default: reportLang in config.json, else en)

Deletes old scans and their evidence files from the data directory. This cannot be undone. The newest completed or partial scan of each account, and scans running for less than 24 hours, are always kept. Asks for confirmation unless --yes.

Option Description
--keep <n> Keep the newest N scans of each account
--older-than <age> Only scans started before this (30d, 12h, 2w or an ISO date)
--scan <ids> Only these scan IDs (this lifts the newest-scan protection)
--status <statuses> Only scans with these statuses: running, completed, partial, failed, aborted
--account <id> Only scans of this account
--dry-run Show what would be deleted without deleting
-y, --yes Do not ask for confirmation
--vacuum Compact the database file afterwards

Markdown design documents with Mermaid diagrams. Writes files into --out, or prints one --doc to stdout. The documents (and the Markdown of snapshot diff --as markdown) are written in English, or in Japanese with --lang ja (or "reportLang": "ja" in config.json); the JSON output of every other command is language-neutral.

Option Description
--scan <id> Scan ID or latest
-o, --out <dir> Output directory (README.md, network.md, security.md, inventory.md, coverage.md)
--doc <names> Documents to generate: overview, network, security, inventory, coverage
-r, --region <regions> Only these regions
--max-diagram-nodes <n> Node cap per diagram, 1–2000 (default 120)
--max-inventory-rows <n> Rows per resource type in inventory.md, 1–100000 (default 300)
--lang <lang> en or ja (default: reportLang in config.json, else en)

A whole scan (header, coverage, resources, relationships, usage metrics and the evidence they come from) as JSON or NDJSON.

Option Description
--scan <id> Scan ID or latest
--as <format> json (default) or ndjson
-o, --out <path> Output file (or directory with --split). Default: stdout
--split One file per service plus _index.json in the --out directory
-s, --service <services> Only these service namespaces (ec2) or plugin IDs (ec2-network)
-r, --region <regions> Only these regions (global for global services)
-t, --type <types> Only these resource types
--no-properties Leave out resource properties

Runs a Model Context Protocol server on stdio with read-only tools over the local database. It does not call AWS. Register it with claude mcp add awnexa -- awnexa mcp. See MCP tools.

Lists the Claude Code Skills bundled with Awnexa, and whether each is installed in the project (installed: current, outdated — installed by an older Awnexa —, modified — edited since this version installed it — or not_installed).

Option Description
--project <dir> Project directory to check (default .)

Copies the bundled Skills into <project>/.claude/skills.

Option Description
--project <dir> Target project directory (default .)
--name <names> Only these Skills
--force Overwrite Skills that already exist

Skills that already exist are skipped; those an older Awnexa installed are also listed in outdated, to be updated with --force (which replaces local edits to them). When it copies any, note says that the Skills read through the Awnexa MCP server when it is registered.

Command Description
awnexa version Versions of Awnexa, the data schema, the AWS SDK packages and Node.js
awnexa plugins Service plugins, and the read-only APIs and IAM actions (requiredIamActions) each one calls
awnexa catalog Implemented and planned APIs. Options: --status implemented|planned, --service <service>

Anonymous usage statistics are on by default and never include AWS configuration data. See Data the CLI sends.

Command Description
awnexa telemetry status Whether usage statistics are sent, and why (environment, settings or default)
awnexa telemetry disable Stop sending, and delete the install ID and any unsent events
awnexa telemetry enable Send usage statistics again (with a new install ID)
awnexa telemetry show The unsent events and the last 10 sent, exactly as they are sent

awnexa mcp provides these read-only tools. Their parameters match the options of the corresponding commands.

Tool Matching command
awnexa_status status
awnexa_coverage coverage
awnexa_resources_list resources list
awnexa_resources_show resources show
awnexa_search search
awnexa_relationships_list relationships list
awnexa_graph graph
awnexa_impact impact
awnexa_overview overview
awnexa_snapshot_list snapshot list
awnexa_snapshot_diff snapshot diff
awnexa_diff_report snapshot diff --as markdown
awnexa_report report --doc …

Scanning, pruning and exporting are not available over MCP: Claude Code reads what you have scanned, and you decide when to scan.

awnexa init writes config.json in the data directory. Command-line options take precedence. AWS credentials are never stored here. See Configuration for every key, including the proxy settings.

Variable Description
AWNEXA_HOME Data directory (used when --data-dir is not given)
AWNEXA_TELEMETRY 0, off or false turns usage statistics off; debug prints events instead of sending
DO_NOT_TRACK 1 turns usage statistics off
HTTPS_PROXY, HTTP_PROXY, NO_PROXY Proxy, when network.proxy / network.noProxy are not set (Configuration)
AWS_CA_BUNDLE Extra trusted CA certificates, when network.caBundle is not set
AWS_PROFILE, AWS_REGION and other AWS SDK variables Used as in the AWS CLI when --profile / --region and the settings file do not set them
Code Meaning
0 Success
1 Error
2 Invalid arguments, or a confirmation was needed
3 AWS authentication failed (AWS_AUTH_FAILED)
4 scan finished, but some coverage is partial or failed
130 Forced quit (Ctrl+C pressed twice)
143 Forced quit (SIGTERM, 10 seconds after it was received)

Errors are printed to stderr as {"error":{"code":"…","message":"…"}}. Pressing Ctrl+C once (or sending SIGTERM) during a scan lets the API calls in progress finish and marks the scan aborted.