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 olist 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 uses a two-database architecture:

1. internaldb (Daana's internal database): Stores your models, mappings, and workflows - configured in ~/.daana/config.yaml
2. customerdb (Your data warehouse): Where source data and transformed business entities live - configured via connection profiles

The configuration file (~/.daana/config.yaml) connects to internaldb so you don't need database flags for every command. Connection profiles handle connections to your data warehouse.

Database Options

Docker (recommended for development): The docker-compose.yml created by init provides pre-configured PostgreSQL databases for both internaldb and customerdb. Just run:

docker-compose up -d

Bring Your Own Database: You can use any PostgreSQL database as internaldb. Simply configure the connection details in your config file or environment variables. This is useful for:

• Production deployments
• Shared development environments
• Cloud-hosted databases (RDS, Cloud SQL, etc.)

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/"
 
  # Internal database connection (Daana metadata)
  db:
    host: "localhost"
    port: 5434         # internaldb port
    user: "dev"
    password: "devpass"
    name: "internaldb"    # Daana's internal database name
    sslmode: "disable"

Note: The default configuration points to internaldb (port 5434) where daana-cli stores model definitions, mappings, and workflows.

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/
 
# Database connection
export APP_DB_HOST=localhost
export APP_DB_PORT=5434       # internaldb
export APP_DB_USER=dev
export APP_DB_PASSWORD=devpass
export APP_DB_NAME=internaldb
 
# Logging
export APP_LOG_LEVEL=debug

Command-Line Flags

Configuration can also be provided directly as command-line flags:

./daana-cli install \
  --db-host localhost \
  --db-port 5432 \
  --db-user dev \
  --db-password devpass \
  --db-name internaldb

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 compile model -i model.yaml -o model.json --log-level debug
 
# Show only warnings and errors everywhere
./daana-cli compile model -i model.yaml -o model.json --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 compile model -i model.yaml -o model.json \
  --log-level-console info \
  --log-level-file debug
 
# Quiet console (warn), normal file logs (info)
./daana-cli compile model -i model.yaml -o model.json \
  --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):

INF Successfully compiled model: OlistBusinessModel
Entities: 2
Attributes: 25
Relationships: 1
Output: model.json

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

2025-10-27T10:15:32+01:00 DBG Configuration loaded input_file=model.yaml output_file=model.json
2025-10-27T10:15:32+01:00 DBG Processing model entities=2 relationships=1
2025-10-27T10:15:32+01:00 INF Successfully compiled model: OlistBusinessModel
2025-10-27T10:15:32+01:00 DBG Model compilation completed input_file=model.yaml output_file=model.json

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

Database 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.