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
`-v, --verbose`	Enable debug logging
`-q, --quiet`	Only show warnings and errors
`--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

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"])