Configuration

Daana CLI can be configured through multiple methods, giving you flexibility in how you manage your settings.

First time here? If you haven't set up your environment yet, start with the Setup Guide which walks you through creating your configuration file.

Project Structure

The easiest way to set up a new project is with the init command:

daana-cli init my-project

This creates a complete project structure:

my-project/
├── model.yaml           # Your data model definition
├── workflow.yaml        # Workflow orchestration
├── connections.yaml     # Database connection profiles
├── mappings/            # Mapping files directory
│   ├── customer-mapping.yaml
│   ├── order-mapping.yaml
│   └── product-mapping.yaml
├── docker-compose.yml   # Local database setup (optional)
└── README.md            # Project documentation

Tip: Use daana-cli init my-project --example quickstart to create a project with the tutorial example data.

Default File Paths

Daana CLI uses these default paths when you don't specify files explicitly:

These defaults can be overridden in your config file or via command-line arguments.

Configuring Default Paths

Add path configuration to your ~/.daana/config.yaml:

app:
  paths:
    model: "models/my-model.yaml"        # Custom model path
    workflow: "workflows/main.yaml"      # Custom workflow path
    connections: "config/connections.yaml"  # Custom connections path
    mappings: "mappings/"                # Mappings directory

Understanding Daana's Configuration

Daana CLI uses connection profiles to define how to connect to your target database (data warehouse). The configuration file (~/.daana/config.yaml) stores application preferences such as logging levels and default file paths.

Getting Started with Configuration

The easiest way to get started is to copy the example configuration:

mkdir -p ~/.daana && cp example-config.yaml ~/.daana/config.yaml

Then edit ~/.daana/config.yaml to match your environment (usually just the default values work for development).

Configuration Methods

Configuration File

Create a ~/.daana/config.yaml file in your home directory:

app:
  log_level: "info"

  # Default file paths (optional - these are the defaults)
  paths:
    model: "model.yaml"
    workflow: "workflow.yaml"
    connections: "connections.yaml"
    mappings: "mappings/"

Environment Variables

All configuration options can be set via environment variables with the APP_ prefix:

# File paths
export APP_PATHS_MODEL=model.yaml
export APP_PATHS_WORKFLOW=workflow.yaml
export APP_PATHS_CONNECTIONS=connections.yaml
export APP_PATHS_MAPPINGS=mappings/

# Logging
export APP_LOG_LEVEL=debug

Priority Order

Configuration is resolved in the following priority order (highest to lowest):

1. Command-line flags
2. Environment variables
3. Configuration file
4. Default values

Note: Command-line flags always take precedence over other configuration methods.

Logging Configuration

Daana CLI uses a dual-level logging system that separates user-facing output from developer debugging information:

• Console: Clean, user-friendly success messages and summaries (default: info)
• Log File: Detailed technical logs with timestamps for debugging (default: debug, saved to logs/daana-cli-YYYY-MM-DD.log)

Simple Configuration (One Log Level)

Use --log-level to set the same level for both console and file:

# Show debug messages in console and file
daana-cli check model --log-level debug

# Show only warnings and errors everywhere
daana-cli check model --log-level warn

Advanced Configuration (Separate Log Levels)

Use --log-level-console and --log-level-file for independent control:

# Clean console (info), detailed file logs (debug) - recommended
daana-cli check model \
  --log-level-console info \
  --log-level-file debug

# Quiet console (warn), normal file logs (info)
daana-cli check model \
  --log-level-console warn \
  --log-level-file info

Configuration File

Add logging configuration to ~/.daana/config.yaml:

app:
  # Simple: one level for both console and file
  log_level: "info"

  # OR Advanced: separate levels
  log_level:
    console: "info"   # User-facing output
    file: "debug"     # Developer logs in logs/daana-cli-YYYY-MM-DD.log

Environment Variables

# Simple: one level for both
export APP_LOG_LEVEL=debug

# OR Advanced: separate levels
export APP_LOG_LEVEL_CONSOLE=info
export APP_LOG_LEVEL_FILE=debug

Log Levels

Available log levels (from most to least verbose):

• trace - Very detailed technical information
• debug - Diagnostic information for troubleshooting
• info - General informational messages (default for console)
• warn - Warning messages about potential issues
• error - Error messages for failures
• fatal - Critical errors that cause termination
• panic - Severe errors with stack traces

Example Output

With default settings (console: info, file: debug):

Console output (clean and user-friendly):

Checking model: model.yaml

Model: BOOK_RETAILER_MODEL
  Entities: 2
  Relationships: 1

✓ Model valid

Log file (logs/daana-cli-2025-10-27.log with timestamps and structured data):

...
2026-01-27T20:19:54+01:00 DBG Validating model file=model.yaml
2026-01-27T20:19:54+01:00 DBG Processing model model=BookRetailerModel model_id=BOOK_RETAILER_MODEL
2026-01-27T20:19:54+01:00 DBG Processing entity entity=CUSTOMER entity_id=CUSTOMER
2026-01-27T20:19:54+01:00 DBG Generated atomic context for attribute atomic_context=CUSTOMER_CUSTOMER_ID attribute=CUSTOMER_ID entity=CUSTOMER
...

Tip: The default configuration (console: info, file: debug) is recommended for most users. It provides clean output while capturing detailed logs for troubleshooting.

File Paths Configuration

Connection Profiles

For managing connections to your data warehouse databases, see DMDL > Connections.

Connection profiles are part of the Daana Model Description Language and define how to connect to your source and destination databases.

Naming and Casing

Entity, attribute, and relationship names accept any casing in YAML — CUSTOMER, customer, and Customer_Entity all work. Names are preserved exactly as written in your model. Cross-reference lookups (e.g., mapping to model) are case-insensitive at compile time.

Framework-generated columns (eff_tmstp, ver_tmstp, type_key, data_key, inst_key, row_st, inst_row_key, popln_tmstp) and table suffixes (_idfr, _desc, _x) are always lowercase.

Migration note: If you are upgrading from a version that used UPPERCASE framework columns, audit downstream consumers (BI dashboards, dbt models, custom SQL) and update references to use lowercase. See the CHANGELOG for the full migration checklist.