OmniScript 2.0

Getting started

Install osf, write a document, check it, export it and ask it questions. About five minutes.

1. Install

Method	Command
npm (prebuilt binary)	`npm install -g omniscript-cli`
Cargo (from source)	`cargo install osf-cli`
Release binaries	Linux, macOS and Windows archives on the GitHub releases page

Check the installation:

$ osf --version
osf 2.0.0-alpha.3

Prefer not to install anything yet? The playground runs the same parser, linter and HTML renderer in your browser.

2. Write a document

An OSF file is a sequence of @block { … } blocks. Properties end with a semicolon (;); the rest of a block body is Markdown. Save this as hello.osf:

hello.osf

@meta {
  osf: "2.0";
  title: "Hello OmniScript";
  author: "Ada Lovelace";
}

@doc {
  # Hello
  My first **OSF 2.0** document. The main result is [F-1](#F-1).
}

@sheet {
  id: "numbers";
  name: "Numbers";
  A1 = "Item";   B1 = "Value";
  A2 = "Apples"; B2 = 3;
  A3 = "Pears";  B3 = 4;
  A4 = "Total";  B4 = =SUM(B2:B3);
}

@finding {
  id: "F-1";
  claim: "We have 7 pieces of fruit.";
  confidence: 0.95;
  evidence: [@ref("numbers")];
}

The sheet uses A1 cells and a formula (formulas start with = and are not quoted). The finding points at the sheet with @ref, and the Markdown link [F-1](#F-1) links to the finding.

3. Check it

$ osf lint hello.osf
✓ 1 file checked, no problems

Mistakes are reported with file, line and a code, and the exit status is 1:

$ osf lint bad.osf
bad.osf:21:1: error[bad-property]: confidence should be a number between 0 and 1, not 1.5
bad.osf:21:1: error[dangling-ref]: evidence: @ref("numbrs") points to no block
2 error(s), 0 warning(s)

osf lint and osf fmt accept several files and directories. osf fmt hello.osf formats in place without losing comments; osf fmt --check . is the CI version.

4. Render it

$ osf render hello.osf --target pdf -o hello.pdf
PDF written to hello.pdf

osf render hello.osf --target docx            # also pptx, xlsx
osf render hello.osf --target html -o hello.html
osf render hello.osf --target md              # text formats print to stdout
osf render hello.osf --target pdf --theme academic

Targets: html, pdf, docx, pptx, xlsx, md, json, typst. Themes: default, corporate, academic, modern, dark, minimal (osf themes lists them). The sheet shows the computed total; osf eval hello.osf prints every value.

5. Query it

$ osf query hello.osf 'finding'
F-1                  @finding      We have 7 pieces of fruit.

$ osf query hello.osf '#F-1 -> evidence'
numbers              @sheet        Numbers

$ osf graph hello.osf
F-1 --evidence--> numbers

Add --json for machine-readable output. The selector language is described in Selectors and the document graph.

Next steps

Block reference: every block and property.
CLI reference: every command and flag.
Agents: serve documents over MCP and A2A.
In JavaScript: npm install omniscript-core, then import { lint, render } from "omniscript-core".

Block reference →