Command Reference

Complete reference for all daana-cli commands.

Check

Validate configurations (model, mapping, workflow, connections)

Usage:

daana-cli check

Validate your YAML configurations without deploying to database.

When to check:

• Before deploying to catch errors early
• After editing any configuration file
• When debugging deployment issues
• In CI/CD pipelines for automated validation

What it validates:

• model: Structure, entity definitions, naming conventions
• mapping: References to model, required attributes, table configs
• workflow: Complete workflow including all mappings
• connections: Database connection profiles

Output formats: text (default) or json (for CI/CD)

Subcommands:

• daana-cli check connections
• daana-cli check mapping
• daana-cli check model
• daana-cli check workflow

Examples:

# Check model (uses model.yaml by default)
daana-cli check model

# Check all mappings in mappings/ directory
daana-cli check mapping

# Check a specific mapping
daana-cli check mapping customer-mapping.yaml

# Check workflow
daana-cli check workflow

# Check connection profiles
daana-cli check connections

# JSON output for CI/CD
daana-cli check model --format json

Connections

Validate connection profiles

Usage:

daana-cli check connections [file] [flags]

Validate connection profiles without deploying.

Arguments: [file] Path to connections YAML file (default: connections.yaml)

When to use:

• Before deploying to verify database connectivity settings
• After adding or modifying connection profiles
• When debugging database connection issues
• When setting up a new environment

What it validates:

• Profile structure and syntax
• Required fields for each SQL dialect (PostgreSQL, BigQuery, Snowflake, etc.)
• Authentication configuration
• SSL/encryption settings
• Credential file paths

Flags:

Examples:

# Check all profiles (uses connections.yaml by default)
daana-cli check connections

# Check a specific profile
daana-cli check connections --connection dev

# Strict mode (treat warnings as errors)
daana-cli check connections --connection prod --strict

# JSON output for CI/CD
daana-cli check connections --format json

Mapping

Validate mapping YAML file(s) against model and database schema

Usage:

daana-cli check mapping [path] [flags]

Validate a mapping YAML file or directory of mappings against their model and database schema.

Arguments: [path] Path to mapping file or directory (default: mappings/) If a directory, validates all .yaml/.yml files in it

When to use:

• Before deploying your mappings
• After modifying table or attribute mappings
• When validating source table configurations
• When debugging data transformation issues

What it validates: Structure (always performed):

• YAML syntax and structure
• Required fields (entity_id, mapping_groups, tables, etc.)
• Entity exists in model
• All attributes exist in model
• All required attributes are mapped
• Effective timestamp consistency
• Relationship IDs match model definitions

Schema (enabled by default, use --skip-schema-validation to disable):

• Tables exist in database
• Primary key columns exist
• Transformation expressions are valid SQL

Flags:

Examples:

# Check all mappings in mappings/ directory
daana-cli check mapping

# Check a single mapping
daana-cli check mapping customer-mapping.yaml

# Check all mappings in a specific directory
daana-cli check mapping mappings/

# Skip schema validation (structure only)
daana-cli check mapping --skip-schema-validation

# Use specific connection profile
daana-cli check mapping --connection dev

# Verbose output with details
daana-cli check mapping --verbose

# Strict mode (warnings become errors)
daana-cli check mapping --strict

Model

Validate model YAML file

Usage:

daana-cli check model [file] [flags]

Validate a model YAML file without deploying.

Arguments: [file] Path to model YAML file (default: model.yaml)

When to use:

• Before deploying your model
• After modifying entity or attribute definitions
• When validating naming conventions

What it validates:

• YAML syntax and structure
• Entity and attribute definitions
• Relationship references
• Naming conventions
• Required fields

Flags:

Examples:

# Check model (uses model.yaml by default)
daana-cli check model

# Check a specific model file
daana-cli check model my-model.yaml

# Verbose output with details
daana-cli check model --verbose

# JSON output for CI/CD
daana-cli check model --format json

Workflow

Validate complete workflow (model + mappings + references)

Usage:

daana-cli check workflow [file] [flags]

Validate entire workflow including model, mappings, and connection profiles.

Arguments: [file] Path to workflow YAML file (default: workflow.yaml)

This is the comprehensive check - it validates your complete project setup.

When to use:

• Before deploying (validates everything)
• After modifying any configuration
• When validating complete project setup
• To verify all components work together

What it validates:

• Workflow ID format (valid name: letters, digits, underscores)
• Model file exists and is valid (full model validation)
• All mapping files exist and are valid (structure + model references)
• Connection profile referenced exists and is valid
• Entity coverage (warns if model entities aren't mapped)

With --source (PostgreSQL/BigQuery), it additionally connects to the source database and validates each mapping's table, primary-key columns, and transformation expressions against the live schema. ANY source-connection failure (unreachable, bad credentials, bad DSN, missing permissions) is reported as a warning — the schema is NOT validated — so CI is not broken by a flaky source; use --strict to treat it (and other schema warnings) as an error.

Flags:

Examples:

# Check workflow (uses workflow.yaml by default)
daana-cli check workflow

# Check a specific workflow file
daana-cli check workflow my-workflow.yaml

# Validate against the live source database (PostgreSQL/BigQuery)
daana-cli check workflow --source

# Verbose output with details
daana-cli check workflow --verbose

# JSON output for CI/CD
daana-cli check workflow --source --format json

Completion

Generate the autocompletion script for the specified shell

Usage:

daana-cli completion

To load completions:

Bash: source <(daana-cli completion bash) Zsh: source <(daana-cli completion zsh) Fish: daana-cli completion fish | source PowerShell: daana-cli completion powershell | Out-String | Invoke-Expression

Deploy

Deploy workflow to database

Usage:

daana-cli deploy [workflow.yaml] [flags]

Deploy workflow to make your data model and mappings ready for execution.

Arguments: [file] Path to workflow YAML file (default: workflow.yaml)

When to deploy:

• After creating or modifying your model YAML
• After creating or modifying your mapping YAML
• After creating or modifying your workflow YAML
• When setting up a new environment

What it does:

• Sets up the transformation engine in your database
• Loads your data model structure
• Prepares your transformation mappings
• Makes everything ready for data execution
• For BigQuery with source_project_id, validates source tables against the source project

Prerequisites:

• Run 'daana-cli install' first to set up the framework

Flags:

Examples:

# Deploy a workflow (auto-detects workflow.yaml in current directory)
daana-cli deploy

# Deploy a specific workflow file
daana-cli deploy workflow.yaml

# After deploy, execute the workflow
daana-cli execute workflow.yaml --batch-start="2025-01-01" --batch-end="2025-01-31"

Doctor

Diagnose environment health and configuration issues

Usage:

daana-cli doctor

Diagnose your Daana CLI environment and configuration.

This command checks your setup and identifies potential issues before they cause problems during compilation, deployment, or execution.

What it checks:

• Config file validity (syntax and required fields)
• Database connectivity (can connect to configured databases)
• focal-cli binary availability and version compatibility
• Required paths exist (model, mappings directory, workflow)
• Project structure validity

When to use:

• After initial setup to verify everything is configured correctly
• When commands fail with unclear errors
• Before deploying to a new environment
• When troubleshooting connection issues

Flags:

Examples:

# Run all diagnostic checks
daana-cli doctor

# Check with verbose output
daana-cli doctor --verbose

Execute

Execute a workflow with data transformations

Usage:

daana-cli execute [workflow.yaml] [flags]

Execute your data transformation workflow to load data into your warehouse.

Arguments: [file] Path to workflow YAML file (default: workflow.yaml)

When to execute:

• After deploying your workflow for the first time
• On a schedule for incremental data loads
• After updating mappings (redeploy first, then execute)
• When backfilling historical data

What it does:

• Reads data from your configured source tables
• Transforms it according to your mapping definitions
• Loads the transformed data into your data warehouse
• Tracks batch progress for incremental workflows
• For BigQuery with source_project_id, uses three-part source table references for cross-project reads

Batch window flags (--batch-start / --batch-end): Both flags must be specified together OR omitted together; --batch-end must be strictly greater than --batch-start. Specifying only one of the two (or a transposed window) is rejected up front.

• No flags (default): the framework uses the per-pipeline watermark from batch_history as the lower bound and NOW as the upper bound. This is the routine incremental-loading mode.
• Both flags set: the explicit window is used and recorded in batch_history; the next run's watermark anchors at this run's --batch-end.

Aborted pipeline recovery: If batch_history has prior 'F' or 'R' rows but no successful 'C' row for an INCREMENTAL/TRANSACTIONAL pipeline, the framework aborts that pipeline (siblings continue) rather than silently rewinding to epoch. The exit code is non-zero and the error names every aborted proc_key and entity. To recover, either fix batch_history manually or run --full-refresh on the affected entity, then re-execute.

Run with --no-tui to receive an additional structured JSON diagnostic on stdout (lines with "type":"incomplete_history") for runbook tooling.

Full refresh (--full-refresh): Deletes the target-warehouse data and re-executes in one invocation. Three scopes: - --full-refresh Model level: deletes every entity's desc/idfr/focal/X tables and the entire batch_history table, then reloads from source. - --full-refresh --entity ID Entity level: deletes one entity's tables and its batch_history rows. - --full-refresh --entity ID --attribute A Attribute level: deletes one attribute's columns/data within an entity.

All three scopes preserve framework infrastructure: semantic views, functions, and metadata table structure (atom_contx_idfr, proc_inst, batch_history schema) are untouched. Recovery is data reload only; the install/deploy commands do NOT need to be re-run.

--yes bypasses the interactive confirmation prompt.

Prerequisites:

• Run 'daana-cli deploy' once before first execution
• Redeploy only when model or mappings change

Flags:

Examples:

# Execute a workflow (auto-detects workflow.yaml in current directory)
daana-cli execute

# Execute with date range (for incremental loads)
daana-cli execute --batch-start="2025-01-01" --batch-end="2025-01-31"

# Execute a specific workflow file
daana-cli execute my-workflow.yaml

# Execute with specific connection profile
daana-cli execute workflow.yaml --connection dev

Generate

Generate template files for different components

Usage:

daana-cli generate

Generate template files to accelerate your development workflow.

When to use:

• Starting to map a new entity to your model
• Setting up connection profiles for a new environment
• Creating workflow configuration from scratch

What it generates:

• mapping: Entity mapping templates from your model
• workflow: Workflow configuration templates
• connections: Database connection profile templates

Templates include helpful comments and placeholders to guide you.

Subcommands:

• daana-cli generate connections
• daana-cli generate mapping
• daana-cli generate model
• daana-cli generate workflow

Examples:

# Generate a mapping template for an entity
daana-cli generate mapping --model model.yaml --entity CUSTOMER -o customer-mapping.yaml

# Generate workflow template from model
daana-cli generate workflow --model model.yaml -o workflow.yaml

# Generate connection profiles template
daana-cli generate connections -o connections.yaml

Connections

Generate a connections template YAML file

Usage:

daana-cli generate connections [flags]

Generate a connections template YAML file with examples for all supported SQL dialects.

When to use:

• Setting up database connections for the first time
• Adding connections for a new environment (dev, staging, prod)
• Learning the connection profile format

What it generates:

• PostgreSQL connection examples
• BigQuery connection examples
• SQL Server connection examples
• Oracle connection examples
• Snowflake connection examples
• Best practices for environment variables and secrets management

Flags:

Examples:

# Generate connections template to file
daana-cli generate connections -o connections.yaml

# Generate to stdout
daana-cli generate connections

Mapping

Generate a mapping template YAML file for entities

Usage:

daana-cli generate mapping [flags]

Generate mapping template YAML files from your model.

When to use:

• After defining your model entities
• When adding new entities to map
• To scaffold mappings for all entities at once

What it generates:

• Attribute mappings based on model definitions
• Relationship mappings
• Table and column placeholders
• Transformation expression templates

Defaults:

• model: model.yaml
• output directory: mappings/

Flags:

Examples:

# Generate mapping for all entities
daana-cli generate mapping

# Generate mapping for a specific entity
daana-cli generate mapping --entity CUSTOMER -o customer-mapping.yaml

# Generate all mappings to custom directory
daana-cli generate mapping --out-dir my-mappings/

# Verbose templates with comments
daana-cli generate mapping --verbose

Model

Generate a model template YAML file

Usage:

daana-cli generate model [flags]

Generate a model template YAML file for defining business entities, attributes, and relationships.

When to use:

• Starting a new data transformation project
• Learning the model structure and syntax
• Creating a reference for your team

What it generates:

• Model metadata structure
• Example entities (CUSTOMER, ORDER)
• Attribute definitions with types
• Group attribute examples
• Relationship definitions
• Comprehensive inline documentation

Flags:

Examples:

# Generate model template to file
daana-cli generate model -o model.yaml

# Generate to stdout (for piping)
daana-cli generate model

Workflow

Generate a workflow template YAML file

Usage:

daana-cli generate workflow [flags]

Generate a workflow template YAML file for orchestrating data transformations.

When to use:

• After creating model and mappings
• When setting up a new environment
• To create workflow from existing files (smart mode)

What it generates:

• Workflow metadata structure
• Connection profile references
• Model file references
• Mapping file references
• Advanced settings with examples
• Commented instructions and explanations

Smart mode (auto-populates from existing files): Use --model and --mappings-dir to generate a workflow pre-populated with your actual model and mapping file references.

Flags:

Examples:

# Generate workflow template
daana-cli generate workflow -o workflow.yaml

# Smart mode: generate from existing model and mappings
daana-cli generate workflow --model model.yaml --mappings-dir mappings/ -o workflow.yaml

# Specify connection profile
daana-cli generate workflow --model model.yaml --connection dev -o workflow.yaml

Init

Initialize a new Daana project with template files

Usage:

daana-cli init [directory] [flags]

Initialize a new Daana project with template files and directory structure.

When to use:

• Starting a new data transformation project
• Setting up a new environment with fresh templates
• Learning Daana with the quickstart tutorial

What it creates:

• model.yaml - Data model template with example entities
• workflow.yaml - Workflow orchestration template
• connections.yaml - Database connection profiles template
• config.yaml - CLI configuration
• mappings/ - Directory for entity mapping files
• docker-compose.yml - Local database setup
• README.md - Project documentation

Config file precedence (first match wins):

1. --config flag (explicit path)
2. ./config.yaml (project-local, created by init)
3. $XDG_CONFIG_HOME/daana/config.yaml (or ~/.config/daana/config.yaml)

The init command also creates a global config at ~/.config/daana/config.yaml if it doesn't exist. This allows daana-cli to work from any directory.

Examples: --example quickstart: Book Retailer tutorial with sample data and workflow scaffold (recommended for new users)

All files follow Daana best practices and are ready for git.

Flags:

Examples:

# Create a blank project in a new directory
daana-cli init my-data-project

# Create project in current directory
daana-cli init .

# List available examples
daana-cli init --list-examples

# Start with the quickstart tutorial (recommended for new users!)
daana-cli init my-tutorial --example quickstart

Install

Install the Daana framework into a database

Usage:

daana-cli install [remote] [flags]

Install the Daana framework infrastructure into your database.

Arguments: [target] Optional positional arg. Only "remote" is meaningful — it's kept for backwards compatibility with v0.5.0+ scripts that explicitly disambiguated remote-only installs. The bare "install" form does the same thing.

When to install:

• First time setting up a new environment
• After upgrading daana-cli to a new major version
• When setting up a new database server

What it does:

• Creates database schemas and tables for metadata
• Installs functions and metadata tables
• Configures the transformation engine

Prerequisites:

• Database must be running and accessible
• User must have CREATE privileges

Flags:

Examples:

# Simple install (auto-detects connections.yaml and config)
daana-cli install

# Install with explicit connection profile
daana-cli install --connection dev

# Full manual configuration
daana-cli install \
--db-host localhost --db-port 5432 --db-name mydb \
--db-user dev --db-password devpass \
--connections connections.yaml --connection dev

Lint

Lint a data model YAML file

Usage:

daana-cli lint [model.yaml] [flags]

Validate a data model YAML file against best practices and naming conventions.

When to use:

• Before committing changes to your model
• To enforce team coding standards
• When reviewing model quality
• As part of CI/CD validation

What it checks:

• YAML syntax and structure
• Entity naming conventions
• Attribute naming conventions
• Relationship definitions
• Whitespace and formatting issues
• Required fields presence

Defaults:

• model: model.yaml (or specify via --in flag)

Flags:

Examples:

# Lint a model file
daana-cli lint model.yaml

# Lint with verbose output
daana-cli lint model.yaml --verbose

# Lint with strict mode (more rules enforced)
daana-cli lint model.yaml --strict

# Lint using input flag
daana-cli lint --in my-model.yaml

Merge

Synchronize mappings with updated model definitions

Usage:

daana-cli merge

Keep your mapping files in sync when your data model evolves.

When to use:

• After adding new attributes to your model
• After changing attribute properties (e.g., effective_timestamp)
• After adding or removing relationships
• When you want mappings to reflect the latest model structure

What it does:

• Preserves your custom transformation expressions
• Preserves table configurations and where clauses
• Adds new attributes from model (with placeholders)
• Removes attributes no longer in the model
• Creates backups before overwriting

Available subcommands: mapping Merge mapping files with an updated model

Subcommands:

• daana-cli merge mapping

Examples:

# Merge a single mapping with updated model
daana-cli merge mapping --model model.yaml --mapping customer-mapping.yaml

# Merge all mappings in a workflow
daana-cli merge mapping --workflow workflow.yaml

# Preview changes without writing
daana-cli merge mapping --model model.yaml --mapping customer-mapping.yaml --diff

Mapping

Synchronize mapping files with an updated model

Usage:

daana-cli merge mapping [flags]

Merge existing mapping files with an updated model while preserving customizations.

When to use:

• After adding new attributes to your model entities
• After changing attribute properties (e.g., effective_timestamp)
• After adding or removing relationships
• To ensure mappings reflect the latest model structure

What it preserves:

• Custom transformation expressions
• Table and connection configurations
• Where clauses and filters
• Ingestion strategies

What it updates:

• Adds new attributes from model (with placeholder transformations)
• Removes attributes no longer in model
• Updates attribute properties (like effective_timestamp changes)
• Adds new relationships (with placeholder configuration)

Safety features:

• Creates timestamped .bak backup before overwriting
• Validates output before writing
• Atomic file writes (write to temp, then rename)
• Shows diff preview with --diff flag
• Dry-run mode with --dry-run flag

Modes: Single Mapping: --model and --mapping flags Workflow Mode: --workflow flag (merges all mappings in workflow)

Note: Model files can be YAML or JSON (YAML auto-compiles internally).

Flags:

Examples:

# Basic usage - merge and update in place (creates backup)
daana-cli merge mapping --model model.yaml --mapping customer-mapping.yaml

# Preview changes without writing files
daana-cli merge mapping --model model.yaml --mapping customer-mapping.yaml --diff

# See detailed verbose output during merge
daana-cli merge mapping --model model.yaml --mapping customer-mapping.yaml --verbose

# Dry run - see complete output without writing
daana-cli merge mapping --model model.yaml --mapping customer-mapping.yaml --dry-run

# Merge to a different output file
daana-cli merge mapping --model model.yaml --mapping customer-mapping.yaml --out merged.yaml

# Merge all mappings in a workflow
daana-cli merge mapping --workflow workflow.yaml

Ui

Launch the local Daana UI in a browser

Usage:

daana-cli ui

Launch a local web UI that lets you view and edit your model YAML side-by-side with a graphical canvas. The UI talks to a small HTTP server embedded in this binary — no Node runtime is needed in production.

The server binds to localhost only. YAML files on disk remain the single source of truth: every edit in the UI writes back to the YAML, and every external edit to the YAML (vim, formatter, git checkout) is reflected in the UI via Server-Sent Events.

All four project artifacts are loaded from the standard daana config keys (app.paths.model/workflow/connections/mappings) with per-flag overrides. Each is independently optional — an artifact that doesn't exist yet is exposed as a 404 endpoint that the UI can offer to create.

When the workflow / connections / mappings paths are not set explicitly, they default to the file or directory sitting NEXT TO the model (e.g. the model's sibling workflow.yaml / connections.yaml / mappings/), so a project laid out beside its model works without extra flags — and the model↔mapping validation is workflow-scoped rather than dormant.

When to use:

• You want a visual view of your model while authoring YAML
• You are exploring a new project and prefer a canvas over scrolling

What it does NOT do (yet):

• Run compile, deploy, or execute (those remain CLI commands)

Flags:

Examples:

# Launch with all defaults (model.yaml, workflow.yaml, connections.yaml, mappings/)
daana-cli ui

# Pin the port and skip browser open (headless dev loops)
daana-cli ui --port 7788 --no-open

# Point at a different project layout
daana-cli ui --model ../proj/m.yaml --workflow ../proj/w.yaml --mappings-dir ../proj/maps