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 examplesg-0123456789abcdef0) or name. A name shared by several resources makesgraph,impactandoverview --entrystop withAMBIGUOUS_REFand the candidates;resources showlists them all. When nothing matches, the error listscandidatesfrom a search.--scan <id>picks a scan ID orlatest. 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. --limitand--offsetpage through long results. The output’spagination.nextOffsetis the next--offset.
Global options
Section titled “Global options”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>) |
Setup and scanning
Section titled “Setup and scanning”awnexa init
Section titled “awnexa init”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.
awnexa scan
Section titled “awnexa scan”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) |
Querying
Section titled “Querying”awnexa status
Section titled “awnexa status”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.
awnexa coverage
Section titled “awnexa coverage”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 |
awnexa resources list
Section titled “awnexa resources list”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) |
awnexa resources show <ref>
Section titled “awnexa resources show <ref>”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) |
awnexa search <query...>
Section titled “awnexa search <query...>”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) |
awnexa relationships list
Section titled “awnexa relationships list”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) |
awnexa graph <ref>
Section titled “awnexa graph <ref>”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) |
awnexa impact <ref>
Section titled “awnexa impact <ref>”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 |
awnexa overview
Section titled “awnexa overview”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) |
Snapshots and diffs
Section titled “Snapshots and diffs”awnexa snapshot list
Section titled “awnexa snapshot list”Scans, newest first.
| Option | Description |
|---|---|
--account <id> |
Only this account |
--limit <n> |
Page size, 1–1000 (default 20) |
--offset <n> |
Page offset (default 0) |
awnexa snapshot show <scanId>
Section titled “awnexa snapshot show <scanId>”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) |
awnexa snapshot prune
Section titled “awnexa snapshot prune”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 |
Documents and export
Section titled “Documents and export”awnexa report
Section titled “awnexa report”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) |
awnexa export
Section titled “awnexa export”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 |
Claude Code
Section titled “Claude Code”awnexa mcp
Section titled “awnexa mcp”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.
awnexa skills list
Section titled “awnexa skills list”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 .) |
awnexa skills install
Section titled “awnexa skills install”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.
Information
Section titled “Information”| 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> |
Usage statistics
Section titled “Usage statistics”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 |
MCP tools
Section titled “MCP tools”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.
Settings file
Section titled “Settings file”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.
Environment variables
Section titled “Environment variables”| 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 |
Exit codes
Section titled “Exit codes”| 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.