Projects

A Keel project is a directory containing a keel.toml manifest file. The manifest declares your project's entry point and permissions, so you don't need to pass environment variables or flags on every invocation.

Creating a Project

Use keel init to scaffold a new project:

keel init my-project

This creates a my-project/ directory with a minimal project structure:

my-project/
  keel.toml
  src/
    main.kl
  modules/          -- user-defined file modules go here

For a data pipeline scaffold with IO and DataFrame permissions pre-configured:

keel init my-pipeline --template pipeline

Project Manifest

The keel.toml file describes your project:

[project]
name = "my-project"
version = "0.1.0"
main = "src/main.kl"

Field	Required	Default	Description
`name`	Yes	—	Project name
`version`	Yes	—	Project version
`main`	No	`src/main.kl`	Entry point for `keel run`

Permissions

Permissions sections control what capabilities your Keel code has access to. All sections are optional — missing sections keep the default behavior.

IO Permissions

[permissions.io]
enabled = true
read_only = false
sandbox = "./data"

Field	Default	Description
`enabled`	`false`	Enable file IO operations
`read_only`	`false`	Restrict to read-only file access
`sandbox`	—	Restrict IO to this directory (relative to project root)

HTTP Permissions

[permissions.http]
enabled = true
allowed_hosts = ["api.example.com"]

Field	Default	Description
`enabled`	`false`	Enable HTTP requests
`allowed_hosts`	—	Restrict requests to these hosts

DataFrame Permissions

[permissions.dataframe]
enabled = true
sandbox = "./data"
max_rows = 1_000_000

Field	Default	Description
`enabled`	`true`	Enable DataFrame operations
`sandbox`	—	Restrict DataFrame file access to this directory
`max_rows`	—	Maximum number of rows allowed

Running a Project

From anywhere inside a project directory:

keel run

This finds the nearest keel.toml by walking up from the current directory, applies permissions, and runs the entry point.

You can also run a specific file while still using the project's permissions:

keel run src/other.kl

Running without a manifest and without a file argument produces an error:

keel run
# Error: No file specified and no keel.toml found

Project Templates

Minimal (default)

The minimal template creates a simple project with just an entry point:

"Hello from my-project!"

Pipeline

The pipeline template scaffolds a data pipeline with extract/transform/load steps using tasks:

-- my-pipeline data pipeline
-- Run with: keel run

let { data } = Task.run "steps/extract.kl" ()
let { transformed } = Task.run "steps/transform.kl" (data)
Task.run "steps/load.kl" (transformed)

It also pre-configures IO and DataFrame permissions with a ./data sandbox.

Next Steps

Modules — Organize code within files
Error Handling — Handle errors in your pipelines