Command line

vpcatlas is one command with five subcommands. Everything it does against AWS is read-only.

vpcatlas [GLOBAL OPTIONS] COMMAND [OPTIONS]

Command	What it does	Page
discover	Scans the account(s), then writes the graph, the inventory and the diagrams.	discover
inventory	Writes only the inventory: JSON (vpcatlas-inventory/1), Markdown and HTML.	inventory
diagram	Writes only the draw.io and Lucid diagrams.	diagram
serve	Starts the dashboard: live diagrams, inventory, history, diff and downloads.	serve
iam-policy	Prints the minimal read-only IAM policy for the auditor role.	iam-policy

Run vpcatlas --help for the list and vpcatlas COMMAND --help for the options of one command. Importing the AWS client, the collectors and the dashboard happens inside each command, so --help and iam-policy start fast and never touch AWS. Exit codes are listed on one page.

The same commands run in the three distributions: the installed binary, the Python package and the Docker image. The image uses vpcatlas as its entrypoint and serve --host 0.0.0.0 --port 8080 as its default command, so docker run vpcatlas/vpcatlas discover ... runs any command. The dashboard is part of all three.

Global options

They go before the command name: vpcatlas -vv discover ..., not vpcatlas discover -vv.

Flag	Environment variable	Default	Description
--version	none	off	Show the version and exit. Prints vpcatlas <version>.
--verbose, -v	none	0	More logging: -v info, -vv debug. Repeat the flag to raise the level; -vv also turns on the botocore, boto3, urllib3 and s3transfer loggers.
--quiet, -q	none	off	Only log errors. It wins over -v.

Logs, the progress bar, the summary table and error messages go to standard error. The only thing written to standard output is the list of files the command created, one path per line, so vpcatlas discover ... > files.txt keeps just the paths. iam-policy without --output prints the policy to standard output.

Credentials

discover, inventory, diagram and serve read the account with the standard AWS credential chain. Nothing about credentials is stored by vpcatlas, and secret keys are never command line flags. Access keys reach the tool the way they reach the AWS CLI and every SDK:

You have	How to give it to vpcatlas
A named profile in ~/.aws/config or ~/.aws/credentials	--profile NAME, or AWS_PROFILE=NAME.
Access keys	AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and, for temporary keys, AWS_SESSION_TOKEN in the environment, or a profile in the shared credentials file.
AWS IAM Identity Center (SSO)	A profile configured for SSO and a current aws sso login; pass it with --profile.
A role in another account	--role-arn ARN, with --external-id, --session-duration, --role-session-name and, if the role requires it, --mfa-serial with --mfa-token.
A profile that already defines role_arn or source_profile	--profile NAME; it keeps working as the AWS config describes it.
An EC2 instance role	Nothing: the chain finds the instance metadata credentials.
An ECS task role	Nothing: the chain uses the container credentials endpoint that ECS sets.
An EKS pod role (IAM roles for service accounts)	Nothing: the chain uses the web identity token file the pod gets (AWS_ROLE_ARN, AWS_WEB_IDENTITY_TOKEN_FILE).

When no --profile is given, the default chain applies, including AWS_PROFILE. If it finds no credentials the command stops with exit code 3.

Credential and scope options

These options exist on discover, inventory and diagram. serve takes the same ones except --mfa-serial, --mfa-token, --format, --output-dir, --strict and --level.

Flag	Environment variable	Default	Description
--profile, -p	none for the three scanning commands (VPCATLAS_PROFILE for serve)	standard credential chain	AWS profile. Repeat it to scan several accounts into one graph.
--role-arn	none for the three scanning commands (VPCATLAS_ROLE_ARN for serve)	none	Role to assume (ARN). Repeat it to scan several accounts.
--external-id	VPCATLAS_EXTERNAL_ID	none	ExternalId required by the role. One value is sent to every role.
--mfa-serial	none	none	MFA device serial or ARN, when the role requires MFA.
--mfa-token	none	none	Current MFA code. Used together with --mfa-serial.
--session-duration	VPCATLAS_SESSION_DURATION	3600	Duration of the assumed-role session, in seconds (900 to 43200).
--role-session-name	VPCATLAS_ROLE_SESSION_NAME	vpcatlas	RoleSessionName used when assuming the role.
--regions, -r	none for the three scanning commands (VPCATLAS_REGIONS for serve)	every enabled region	Regions to scan, comma separated.
--exclude-regions	none for the three scanning commands (VPCATLAS_EXCLUDE_REGIONS for serve)	none	Regions to leave out, comma separated.
--concurrency, -c	none for the three scanning commands (VPCATLAS_CONCURRENCY for serve)	8	Regions scanned in parallel (1 to 32).
--cache	none for the three scanning commands (VPCATLAS_GRAPH_FILE for serve)	none	Read this graph file (vpcatlas-graph.json) instead of calling AWS.
--account-names	none for the three scanning commands (VPCATLAS_ACCOUNT_NAMES_FILE for serve)	none	JSON file that maps account ids to labels, for accounts the API cannot name.

How the credential options combine:

• No --profile and no --role-arn: one account, from the default chain.
• Several --profile: one account per profile, merged into one graph.
• One or more --role-arn: one account per role, merged into one graph. The first --profile, if any, is the identity that assumes the roles; without it the default chain is.
• Several --profile together with --role-arn is refused (exit 2): use several profiles, or several roles.
• --profile and --role-arn also accept comma separated values (--role-arn arn1,arn2).
• --mfa-serial and --mfa-token go together; giving only one is refused (exit 2). They only matter when a role is assumed. A one-time code cannot be reused, so credentials obtained with it are not refreshed: the scan has to finish inside --session-duration.
• Without MFA, assumed-role credentials refresh by themselves before they expire.
• --session-duration outside 900 to 43200, or a --role-session-name that is not 2 to 64 characters from letters, digits and + = , . @ _ -, is refused (exit 2). The session name shows up in CloudTrail of the audited account.
• A region must look like eu-west-1; anything else is refused (exit 2).
• --cache must be an existing file. With it there are no AWS calls and no credentials are needed.
• --account-names points to a JSON object such as {"111122223333": "prod", "444455556666": "shared"}.

Environment variables as alternatives to flags

Three variables are read by every command that scans, because they are declared on the option itself; a fourth, VPCATLAS_REFRESH_SECONDS, belongs to serve. A flag on the command line wins over its variable.

Variable	Same as	Applies to
VPCATLAS_EXTERNAL_ID	--external-id	discover, inventory, diagram, serve
VPCATLAS_SESSION_DURATION	--session-duration	discover, inventory, diagram, serve
VPCATLAS_ROLE_SESSION_NAME	--role-session-name	discover, inventory, diagram, serve
VPCATLAS_REFRESH_SECONDS	--refresh-seconds	serve

The other VPCATLAS_* variables configure the dashboard only. serve reads them when the matching flag is absent, and the container and Lambda entry points read them to start the dashboard without flags. They have no effect on discover, inventory or diagram, which take --profile, --regions and the rest as flags (or AWS_PROFILE for the profile). The full list is on the serve page.

The standard AWS variables are read by the AWS SDK under all commands: AWS_PROFILE, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_CONFIG_FILE, AWS_SHARED_CREDENTIALS_FILE, AWS_ROLE_ARN and AWS_WEB_IDENTITY_TOKEN_FILE, and the container credential variables set by ECS.

Files the commands write

Command	Writes
discover	vpcatlas-graph.json, vpcatlas-inventory.json, .md, .html, and diagrams/vpcatlas-<page>.drawio / .lucid
inventory	vpcatlas-graph.json and vpcatlas-inventory.json, .md, .html
diagram	vpcatlas-graph.json and diagrams/vpcatlas-<page>.drawio / .lucid
serve	Nothing on the command line; with VPCATLAS_SNAPSHOT_URI the dashboard keeps its snapshots and history there
iam-policy	Standard output, or the file given with --output

vpcatlas-graph.json is written only when the data came from AWS. A run with --cache never rewrites it. The formats are described in graph, inventory and diagrams.