Chapter 3 of 14

Project folders

A Creole project keeps its main program, connected modules, and saved data inside one clear folder.

Small programs can use one .crlo file. When a program grows, a project folder gives every part a known place and lets you run everything with one command:

creole run
A folder becomes a Creole project when it contains an @.crlo project-information file.

Why projects use folders

A project folder helps you:

  • keep related .crlo files together
  • choose one file as the starting program
  • connect reusable modules
  • keep program data in a known location
  • move the complete project without breaking its internal paths
  • run the project without typing the starting file name

Creole keeps this structure simple. You do not need a package manifest written with JSON symbols.

Create your first project

Create a folder named hello-project with this structure:

hello-project/
  @.crlo
  main.crlo
  data/

The names have different purposes:

  • @.crlo contains the project information.
  • main.crlo is the first source file Creole runs.
  • data/ is the folder for information created or used by the program.

Add the project information

Open @.crlo and write:

Make project Hello Project.
  Start is "main.crlo".
  Data folder is "data".
End.

This block tells the Creole Handler how the project is organized.

  • Make project Hello Project. gives the project a readable name.
  • Start is "main.crlo". chooses the first file to run.
  • Data folder is "data". identifies the project data folder.
  • End. closes the project-information block.

The @.crlo file is not a second source format. It is still a native Creole .crlo file with a special project name.

Add the starting program

Open main.crlo and add:

Show "Hello from my Creole project".
Show "The project is ready.".

Your complete folder should now be:

hello-project/
  @.crlo
  main.crlo
  data/

Run the complete project

Open a terminal inside hello-project and run:

creole run

Creole finds @.crlo, reads the project information, and runs main.crlo.

You do not need to write this every time:

creole main.crlo

Running the file directly is still useful for a small test, but creole run is the normal command for a complete project.

How Creole starts a project

When you use creole run, the runtime follows a clear order:

  1. find @.crlo in the current folder
  2. read the project name and folder information
  3. confirm that the starting file exists
  4. prepare the project and data paths
  5. run the selected starting file
  6. load connected modules when the program uses them

If important project information is missing, Creole stops with a clear error instead of guessing which file should run.

Use project information

A running project can read its own known values:

  • project name
  • project folder
  • project data folder

These values help your program find its own files without depending on the folder from which Windows started the command.

For example, the project data folder always points to the data location declared in @.crlo.

Keep project paths inside the project folder. Creole prevents project paths from leaving that folder.

Add connected modules

As a project grows, separate different kinds of work into connected .crlo files.

assistant/
  @.crlo
  main.crlo
  chat.crlo
  request.crlo
  memory.crlo
  tools.crlo
  data/

A clear separation could be:

  • main.crlo starts and controls the program
  • chat.crlo handles the conversation flow
  • request.crlo sends provider requests
  • memory.crlo reads and saves memory
  • tools.crlo contains reusable tools

Connect a local module with Use:

Use "chat.crlo".
Use "request.crlo".

A connected module is loaded once. Creole also rejects circular connections so two files cannot endlessly load each other.

Make a reusable module

Create message.crlo:

To welcome using name.
  Return "Welcome, " followed by name.
End.

Use it from main.crlo:

Use "message.crlo".

Ask "What is your name? " and store the answer in name.
Run welcome with name into message.
Show message.

The main file controls the program while the connected file keeps the reusable work separate.

Keep developer settings private

Do not place API tokens or private company values directly in a .crlo file.

Keep these developer-controlled:

  • API addresses
  • provider names
  • access tokens
  • model names
  • request limits
  • private company data
  • memory storage settings

Use environment values or future native secret storage for private information.

Do not save real API keys in @.crlo, main.crlo, or connected modules.

The project file describes the project. It should not become a public secret store.

Choose simple file names

Use short names that explain the file's work:

main.crlo
chat.crlo
request.crlo
memory.crlo
tools.crlo

Avoid names that are hard to understand later:

final2.crlo
new-file.crlo
test-copy-last.crlo

Clear file names make connected programs easier to maintain.

This is a practical base for a larger Creole program:

my-project/
  @.crlo
  main.crlo
  modules/
    request.crlo
    memory.crlo
    tools.crlo
  data/
  tests/

Start with only the folders you need. A small project does not need empty folders or unnecessary modules.

Project safety

Creole project paths cannot escape the project folder. This keeps project-managed files inside the expected location.

A project should also follow these rules:

  • keep @.crlo in the project root
  • keep the declared starting file inside the project
  • use one clear starting file
  • connect only the modules the program needs
  • keep private keys outside source files
  • check the project after changing its structure

Check the starting file

Before running the complete project, check its main file:

creole --check main.crlo

Then run the project:

creole run

If a connected file contains a problem, Creole reports the file and source location that needs attention.

Common project problems

Creole cannot find @.crlo

Make sure the terminal is open inside the project folder:

hello-project/
  @.crlo
  main.crlo

Then run creole run again.

The starting file is missing

Confirm that the value in @.crlo exactly matches the file name:

Start is "main.crlo".

File names and extensions must be correct.

A module cannot be found

Confirm that the connected file exists and that its path is correct:

Use "request.crlo".

If the file is inside another folder, use the correct project-relative location supported by your project structure.

A circular connection is reported

Check whether one module uses another module that eventually connects back to the first one. Move shared work into a separate module that both files can use.

Project checklist

  • The project root contains @.crlo.
  • @.crlo declares the correct starting file.
  • The starting .crlo file exists.
  • The data folder is inside the project.
  • Connected modules have clear responsibilities.
  • File names explain their purpose.
  • API keys are not stored in source files.
  • The main file passes creole --check.
  • The complete project runs with creole run.

Next step

You now know how a Creole project is formed, how @.crlo describes it, how the Handler finds the starting file, and how connected modules keep larger programs organized.

Continue to Values and variables to learn how Creole stores text, numbers, true or false values, and other program data.