Quick Start

This guide builds a minimal item table, generates an Excel template, exports a runtime bundle, and generates Rust code that can load it.

Install the CLI from the GitHub Releases page by downloading the archive for your platform and placing the sora binary on your PATH.

If you already have a Rust toolchain, you can also install the published package from crates.io:

cargo install sora-cli

For local development from a checkout:

cargo install --path crates/sora-cli

1. Create a Project

The fastest path is to scaffold the same minimal project:

sora init --out my-config --schema-format toml
cd my-config

--schema-format accepts toml, yaml, json, or lua. The scaffold creates this layout:

The rest of this section shows the generated files so you can understand the project shape. project.toml looks like this:

package = "game_config"
includes = ["schema/items.toml"]

[build]
default_source_format = "xlsx"
data_root = "data"
schema_lock = "generated/schema.lock"
excel_templates = "generated/excel"

[[build.codegen]]
target = "rust"
out = "generated/rust"
format = "auto"

[[build.exports]]
format = "binary"
out = "generated/config.sora"

In this file, default_source_format = "xlsx" means table sources default to Excel. data_root = "data" means Item.xlsx is read from data/Item.xlsx during export and build. excel_templates = "generated/excel" is only the generated template output directory. It is where Sora writes fresh workbooks with schema headers; it is not the source data directory. Keep it separate from data so regenerating templates cannot overwrite edited row data. The binary export writes the runtime bundle that Rust code will load because Rust defaults to runtime_format = "sora".

Create schema/items.toml:

[[enums]]
name = "ItemType"
values = ["Weapon", "Armor", "Material", "Consumable"]

[[tables]]
name = "Item"
mode = "map"
key = "id"

[tables.source]
format = "xlsx"
file = "Item.xlsx"
sheet = "Item"

[[tables.fields]]
name = "id"
type = "i32"
comment = "Item id"

[[tables.fields]]
name = "name"
type = "string"
comment = "Display name"

[[tables.fields]]
name = "item_type"
type = "enum<ItemType>"
comment = "Item category"

[[tables.fields]]
name = "max_stack"
type = "i32"
default = "1"
range = [1, 9999]
comment = "Stack limit"

2. Generate the Excel Template

The workbook header is generated from the schema:

sora excel-template --project project.toml --out generated/excel

This creates generated/excel/Item.xlsx. Treat that file as a template artifact that can be regenerated after schema changes. For a new table, copy it to data/Item.xlsx and fill rows below the generated header:

After you have real data in data/Item.xlsx, do not run excel-template --out data unless you intentionally want to replace those files. Keep generating empty templates into generated/excel, and use excel-sync to update existing data workbooks in place when the schema changes.

For existing data workbooks, prefer syncing headers in place:

sora excel-sync --project project.toml --data-root data
sora excel-sync --project project.toml --data-root data --write

The preview command shows added fields and legacy columns. The --write command refreshes generated header rows while preserving data rows; fields removed from schema stay in Excel as legacy columns that Sora ignores.

3. Check, Export, and Generate

Validate the schema without reading row data:

sora check --project project.toml

Run every output declared in [build]. This also loads and validates source data before writing exports:

sora build --project project.toml

You can also open the project in Sora Studio, the schema editor embedded in the CLI:

sora studio --project project.toml

The command prints a local URL. Open it in a browser to visualize schema relationships, edit schema modules, preview the generated changes, and save them back to the project.

Or run the steps separately:

sora gen --target rust --project project.toml --out generated/rust

sora export \
  --format binary \
  --default-source-format xlsx \
  --project project.toml \
  --data-root data \
  --out generated/config.sora

4. Next Steps

Read Sora Studio if you want to edit schemas visually. Read First Config for the same example with the generated runtime usage, or inspect examples/showcase/project.toml for a larger multi-language setup.