Skip to main content
OCat gives you two ways to run code: executing a single file directly with ocat run, or working inside a managed project with ocm. Projects add structure, configuration, and logging persistence on top of the single-file workflow.

​
Single file vs. managed project

ocat runocm run
Entry pointAny .ocat filemain field in .ocat/config.json
ConfigurationNone.ocat/config.json
Log persistenceNoYes — .ocat/logs.txt on process exit
Project metadataNoName, version, description, ID
Use ocat run for quick scripts and one-off programs. Use ocm when you need repeatable builds, project metadata, or persistent logs.

​
Project types

When you run ocm initialize, you choose between two project types: App — An application with a main entry file. The project scaffolds src/main.ocat with a Hello World program and sets the main field in config.json to point to it. Running ocm run executes this file. Lib — A library intended to be imported by other files. No src/main.ocat file is created and no main field is written to config.json. Lib projects are not directly runnable via ocm run.
The project type is stored as lowercase "app" or "lib" in config.json, but you select it as App or Lib during ocm initialize.

​
Directory structure

Running ocm initialize creates the following structure: 
my-project/
├── src/
│   └── main.ocat        (App projects only)
├── connection/
└── .ocat/
    └── config.json
src/ — Source files for your project. For App projects, main.ocat is the entry point. You can add more .ocat files here and import them. connection/ — Directory for connection-related files. Created for all project types. .ocat/ — OCat’s project directory. Contains config.json for project configuration and, after a run, logs.txt with log output. You can also place a logcfg.json file here to configure the logging service.

​
Project lifecycle

1

Initialize the project

Run ocm initialize in your terminal. You will be prompted for a project name, directory, ID, and type.
ocm initialize
This creates the directory structure and writes the initial config.json.
2

Write your code

Open src/main.ocat (App projects) and replace or extend the generated Hello World program. Add more .ocat files to src/ and import them as needed.
3

Run the project

From inside your project directory, run:
ocm run
OCM reads .ocat/config.json, sets the project context, and executes the file at the main path.
You can customize log levels and add interceptors by placing a logcfg.json file in .ocat/. See the Logging page for details.

Project configuration

Full reference for the .ocat/config.json schema and all supported fields.

Logging

Configure log levels, interceptors, and understand how logs are persisted.

Build docs developers (and LLMs) love

Get started for freeTalk to us