CLI Usage¶

The ifc-graph command-line interface provides a convenient way to process IFC files and store them in Neo4j without writing any Python code.

Basic Usage¶

ifc-graph --ifc-file path/to/model.ifc

This command will:

Load the IFC file
Extract building elements based on default or configured types
Connect to Neo4j using credentials from environment variables
Store the elements as a graph in the database

Command Reference¶

Synopsis¶

ifc-graph [OPTIONS]

Options¶

Option	Description	Default
`--ifc-file PATH`	Path to the IFC file to process	`IFC_FILE_PATH` env var
`--config PATH`	Path to YAML configuration file	`config.yaml`
`--neo4j-uri URI`	Neo4j connection URI	`NEO4J_URI` env var
`--neo4j-user USER`	Neo4j username	`NEO4J_USER` env var
`--neo4j-password PASS`	Neo4j password	`NEO4J_PASSWORD` env var
`--clear-db`	Clear database before import	`false`
`--dry-run`	Preview import without database changes	`false`
`--log-level LEVEL`	Logging level (DEBUG, INFO, WARNING, ERROR)	`INFO`
`--version`	Show version and exit	-
`--help`	Show help message and exit	-

Examples¶

Process a Single IFC File¶

ifc-graph --ifc-file building.ifc

Clear Database Before Import¶

Data Loss

The --clear-db flag will delete all existing nodes and relationships in your Neo4j database.

ifc-graph --ifc-file building.ifc --clear-db

Preview Import (Dry Run)¶

See what would be imported without making any database changes:

ifc-graph --ifc-file building.ifc --dry-run

Output:

=== DRY RUN - No database changes made ===
IFC File: building.ifc
Total elements: 245

Elements by type:
  IfcWall: 45
  IfcDoor: 28
  IfcWindow: 52
  IfcColumn: 30
  IfcBeam: 40
  IfcSlab: 50

Use Custom Configuration¶

ifc-graph --ifc-file building.ifc --config my_config.yaml

Override Neo4j Connection¶

ifc-graph \
  --ifc-file building.ifc \
  --neo4j-uri bolt://production-server:7687 \
  --neo4j-user admin \
  --neo4j-password secret123

Enable Debug Logging¶

ifc-graph --ifc-file building.ifc --log-level DEBUG

Environment Variables¶

The CLI reads connection settings from environment variables. Create a .env file in your working directory:

# Neo4j Connection
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password_here

# Default IFC file path
IFC_FILE_PATH=./model.ifc

Priority Order¶

Settings are applied in this order (later overrides earlier):

Default values - Built-in defaults
Environment variables - From .env file
Configuration file - From config.yaml
CLI arguments - Command-line options

Configuration File¶

Create a config.yaml file to customize which element types to extract:

# Element types to extract
element_types:
  - IfcWall
  - IfcWallStandardCase
  - IfcDoor
  - IfcWindow
  - IfcColumn
  - IfcBeam
  - IfcSlab
  - IfcStair
  - IfcRoof

# Extraction options
extraction:
  include_property_sets: true
  include_materials: true
  max_properties_per_element: 50

# Logging settings
logging:
  level: INFO

See the Configuration Guide for more details.

Exit Codes¶

Code	Meaning
0	Success
1	Error (file not found, connection failed, etc.)

Troubleshooting¶

"No IFC file specified"¶

Either provide the --ifc-file argument or set IFC_FILE_PATH in your .env file:

# Option 1: CLI argument
ifc-graph --ifc-file model.ifc

# Option 2: Environment variable
export IFC_FILE_PATH=./model.ifc
ifc-graph

"Missing Neo4j connection settings"¶

Ensure all three Neo4j settings are provided via CLI arguments or environment variables:

export NEO4J_URI=bolt://localhost:7687
export NEO4J_USER=neo4j
export NEO4J_PASSWORD=your_password

"Failed to connect after X attempts"¶

Verify Neo4j is running: docker ps or check Neo4j Desktop
Check the URI is correct (default: bolt://localhost:7687)
Verify credentials are correct
Check firewall settings if connecting to a remote server

"Authentication failed"¶

Double-check your username and password. The default Neo4j username is neo4j.