Skip to content

Command Line Interface

Codcel can be run from the command line for automated workflows, CI/CD pipelines, and scripted code generation. The CLI accepts the same configuration options available in the desktop app.

Basic Usage

codcel -e spreadsheet.xlsx -p my-project -g ./generated --table-path ./tables

Arguments

Required

Argument Short Description
--excel-path -e Path to the Excel file to transpile
--project -p Project name (used in generated code identifiers)
--generated -g Output directory for generated project files
--table-path Path where generated table files are stored

Table Format

Argument Default Description
--table-type Format for generated tables: csv or parquet

Formatting

Argument Short Default Description
--decimal-separator -d . Decimal separator character
--currency-symbol -c $ Currency symbol
--thousands-separator -t , Thousands separator character
--language en Formatting language code

Type Handling

Argument Short Default Description
--strict-type-conversion -s false Enable strict type conversion
--use-excel-rounding -u false Use Excel's 15-digit rounding

CSV Configuration

Argument Default Description
--csv-files (empty) Comma-separated list of CSV file paths
--csv-has-header false Whether CSV files have a header row
--csv-delimiter ; CSV field delimiter character

Parquet Input Configuration

Argument Default Description
--parquet-files (empty) Comma-separated list of Parquet file paths for table data input

Parquet files are self-describing, so no header or delimiter settings are needed. Multiple Parquet files can provide data for the same table using prefix naming (e.g., Sales.parquet, Sales_part1.parquet). If both Parquet and CSV files exist for the same table, the Parquet files take priority.

Date Handling

Argument Default Description
--allow-lotus-1-2-3-1900-date-bug true Replicate Excel's 1900 leap year bug

Iterative Calculation

Argument Default Description
--enable-iterative-calculation false Enable circular reference resolution
--maximum-iterations 100 Maximum iterations for convergence
--maximum-change 0.001 Convergence threshold

Advanced

Argument Default Description
--large-array-threshold 100 Row count above which array constants are externalised to separate files (prevents slow compilation)

Engine Versions

Control which versions of the Codcel engine dependencies are used in the generated code. For each engine you can specify either a git tag (for releases) or a git branch (for development/PR testing). If both tag and branch are specified for the same engine, the tag takes priority. If neither is specified, the generated code defaults to branch = "main".

Argument Default Description
--calculation-engine-tag (empty) Git tag for codcel-calculation-engine (e.g. release-0.1.5)
--calculation-engine-branch (empty) Git branch for codcel-calculation-engine (e.g. feature/my-branch)
--table-engine-tag (empty) Git tag for codcel-table-engine
--table-engine-branch (empty) Git branch for codcel-table-engine
--parquet-engine-tag (empty) Git tag for codcel-parquet-engine
--parquet-engine-branch (empty) Git branch for codcel-parquet-engine
--postgresql-engine-tag (empty) Git tag for codcel-postgresql-engine
--postgresql-engine-branch (empty) Git branch for codcel-postgresql-engine

Examples

Basic Generation

codcel \
  -e ./business_specs/mortgage.xlsx \
  -p mortgage-calculator \
  -g ./generated \
--table-path ./tables

European Number Formatting

codcel \
  -e ./specs/report.xlsx \
  -p quarterly-report \
  -g ./generated \
--table-path ./tables \
  -d "," \
  -t "." \
  -c "€"

With CSV Data Files

codcel \
  -e ./specs/analysis.xlsx \
  -p data-analysis \
  -g ./generated \
--table-path ./tables \
  --table-type parquet \
  --csv-files "T_Measurements.csv,T_Stations.csv" \
  --csv-has-header \
  --csv-delimiter ","

With Parquet Data Files

codcel \
  -e ./specs/analysis.xlsx \
  -p data-analysis \
  -g ./generated \
--table-path ./tables \
  --table-type parquet \
  --parquet-files "T_Measurements.parquet,T_Measurements_part2.parquet"

Testing a Feature Branch

Use --*-engine-branch to point generated code at a development branch. You can mix tags and branches — here the calculation engine uses a feature branch while the other engines use release tags:

codcel \
  -e ./specs/mortgage.xlsx \
  -p mortgage-calculator \
  -g ./generated \
--table-path ./tables \
  --table-type parquet \
  --calculation-engine-branch feature/new-rounding \
  --table-engine-tag release-0.1.5 \
  --parquet-engine-tag release-0.1.5 \
  --postgresql-engine-tag release-0.1.5

With Circular References

codcel \
  -e ./specs/financial-model.xlsx \
  -p financial-model \
  -g ./generated \
--table-path ./tables \
  --enable-iterative-calculation \
  --maximum-iterations 200 \
  --maximum-change 0.0001

CI/CD Integration

The CLI is well suited for automated pipelines. A typical CI/CD step:

# Example GitHub Actions step
- name: Generate code from Excel
  run: |
    codcel \
      -e ./business_specs/calculations.xlsx \
      -p my-project \
      -g ./generated \
      --table-path ./tables \
      --table-type parquet

After generation, use standard build tools to compile and test the generated code:

- name: Build and test
  run: |
    cd generated/rust-calculation
    cargo build --release
    cargo test

Relationship to codcel.toml

The CLI arguments correspond to settings in codcel.toml. The desktop app reads and writes codcel.toml, while the CLI accepts the same values as command-line flags.

CLI Argument codcel.toml Setting
--decimal-separator formatting.decimal_separator
--currency-symbol formatting.currency_symbol
--thousands-separator formatting.thousands_separator
--strict-type-conversion formatting.strict_type_conversion
--csv-has-header formatting.csv_has_header
--csv-delimiter formatting.csv_delimiter
--use-excel-rounding formatting.use_excel_rounding
--allow-lotus-1-2-3-1900-date-bug formatting.allow_lotus_1_2_3_1900_date_bug
--enable-iterative-calculation formatting.allow_circular_references
--maximum-iterations formatting.circular_max_iterations
--maximum-change formatting.circular_convergence_threshold

See Also