Command Line Interface#

Cartography uses Typer for its CLI, providing organized help output, shell autocompletion, and contextual help based on selected modules.

Shell Autocompletion#

Install completion for your shell:

# Detect your shell and install
cartography --install-completion

# Or show the completion script to customize
cartography --show-completion

After installation, restart your shell. You can then use Tab to autocomplete:

cartography --neo4j-<TAB>
# Shows: --neo4j-uri  --neo4j-user  --neo4j-password-env-var  ...

Contextual Help#

The --help output is organized into panels by category (Core, Neo4j, AWS, Azure, etc.).

When you specify --selected-modules, only relevant options are shown:

# Show all options
cartography --help

# Show only Core, Neo4j, AWS, StatsD, and Analysis options
cartography --selected-modules aws --help

# Show options for multiple modules
cartography --selected-modules aws,github --help

This makes it easier to discover relevant options without scrolling through 100+ parameters.

Option Panels#

Options are grouped into panels:

Panel

Description

Core Options

Logging, module selection, update tag

Neo4j Connection

Database URI, credentials, connection settings

AWS Options

AWS sync configuration

Azure Options

Azure subscription and authentication

GCP Options

Google Cloud Platform settings

GitHub Options

GitHub organization sync

StatsD Metrics

Metrics collection

Analysis Options

Post-sync analysis jobs

…

30+ more module-specific panels

Core, Neo4j, StatsD, and Analysis panels are always shown regardless of selected modules.

Common Options#

Core#

Option

Description

-d, --debug

Enable debug logging

-v, --verbose

Deprecated alias for --debug; scheduled for removal in v1.0.0

-q, --quiet

Only show warnings and errors

--version

Show the Cartography release version and commit revision, then exit

--log-timestamps

Prepend an ISO-8601 timestamp and level to each log line (off by default so log aggregators that add their own timestamp field don’t get a redundant one)

--selected-modules

Comma-separated list of modules to sync

--update-tag

Custom update tag (default: current timestamp)

Neo4j Connection#

Option

Description

--neo4j-uri

Connection URI (default: bolt://localhost:7687)

--neo4j-user

Username

--neo4j-password-env-var

Env var containing password

--neo4j-password-prompt

Prompt for password interactively

--neo4j-database

Database name

Advanced Common Options#

Neo4j Connection Lifecycle#

Option

Description

--neo4j-max-connection-lifetime

Maximum TCP connection lifetime in seconds before the driver replaces it. Default: 3600

--neo4j-liveness-check-timeout

Idle time in seconds before the driver checks a connection before reuse. Uses the Neo4j driver default when omitted

--neo4j-liveness-check-timeout can help with Aura or clustered deployments whose infrastructure closes idle connections.

StatsD Metrics#

Option

Description

--statsd-enabled

Enable StatsD metrics

--statsd-host

StatsD server address. Default: 127.0.0.1

--statsd-port

StatsD server port. Default: 8125

--statsd-prefix

Prefix added to emitted metric names. Default: empty

Custom Analysis Jobs#

Option

Description

--analysis-job-directory

Directory containing custom JSON analysis jobs to run at the end of the sync

Built-in enrichment uses typed analysis jobs and does not require this option. See writing analysis jobs for the typed API and the legacy custom JSON format.

Environment Variables#

Sensitive credentials are passed via environment variables. Options ending in -env-var specify which variable to read:

export NEO4J_PASSWORD="secret"
export GITHUB_CONFIG="base64-config"

cartography \
    --neo4j-uri bolt://localhost:7687 \
    --neo4j-user neo4j \
    --neo4j-password-env-var NEO4J_PASSWORD \
    --github-config-env-var GITHUB_CONFIG

Examples#

Sync specific AWS resources#

cartography \
    --neo4j-uri bolt://localhost:7687 \
    --selected-modules aws \
    --aws-requested-syncs ec2:instance,s3,iam

Sync multiple AWS profiles#

AWS_CONFIG_FILE=/path/to/config cartography \
    --neo4j-uri bolt://localhost:7687 \
    --aws-sync-all-profiles

Enable metrics#

cartography \
    --neo4j-uri bolt://localhost:7687 \
    --statsd-enabled \
    --statsd-host metrics.example.com

Programmatic Usage#

The CLI can be used programmatically for testing:

import cartography.cli
import cartography.sync

# Default sync
cli = cartography.cli.CLI(prog="cartography")
exit_code = cli.main(["--neo4j-uri", "bolt://localhost:7687"])

# Custom sync object
custom_sync = cartography.sync.build_default_sync()
cli = cartography.cli.CLI(sync=custom_sync)
exit_code = cli.main(["--neo4j-uri", "bolt://localhost:7687"])