OmniScript 2.0

CLI reference

One binary, osf, for everything. Every command also takes -h/--help and -V/--version; osf <command> --help prints the details shown here.

osf lint report.osf
osf render report.osf --target pdf -o report.pdf
osf query report.osf 'finding[confidence>=0.8]'
osf serve mcp .

Command	Does
`osf parse`	Parse a document and print its JSON.
`osf lint`	Check documents (files or directories) for errors and warnings. Exit status 1 on errors.
`osf fmt`	Format documents (files or directories) in place. Lossless: comments and content are kept.
`osf format`	Print a formatted document (`osf fmt` edits files in place).
`osf diff`	Semantic diff of two documents: blocks added, removed and moved, properties and content changed. Blocks are matched by id.
`osf render`	Render a document to html, pdf, docx, pptx, xlsx, md, json or typst. Alias: export.
`osf eval`	Evaluate sheet formulas and show the values.
`osf themes`	List the built-in themes with their colours and fonts.
`osf query`	Find blocks with a selector, e.g. 'finding[confidence>=0.8]'.
`osf graph`	Print the reference graph.
`osf serve mcp`	MCP server over stdio, or streamable HTTP with --listen. Serves a directory or .osf files (default: the current directory).
`osf serve a2a`	Run a document as an A2A agent. The document needs an @agent_card.
`osf serve http`	Preview the documents in a directory in a browser.
`osf card`	Print the document's A2A Agent Card. --url replaces the url in @agent_card.
`osf skill`	Install the osf Agent Skill, or print its SKILL.md.
`osf lsp`	Run the language server on stdio (used by the VS Code extension and other editors).
`osf check`	Run the conformance corpus (default spec/conformance).
`osf schema`	Print the JSON Schema of the canonical JSON.
`osf completions`	Print shell completions for bash, elvish, fish, powershell or zsh.

Check and format

`osf parse`

Parse a document and print its JSON.

osf parse [OPTIONS] <FILE>

Flag	Meaning
`-q, --quiet`	Print only diagnostics
`--spans`	Include source spans in the JSON
`--no-includes`	Do not resolve @include directives
`--max-depth <N>`	Maximum include depth (default 10)

`osf lint`

Check documents (files or directories) for errors and warnings. Exit status 1 on errors.

osf lint [OPTIONS] <FILES>...

Flag	Meaning
`--json`	Print diagnostics as JSON
`--fix`	Also format the files in place
`--deny-warnings`	Treat warnings as errors
`--no-includes`	Do not resolve @include directives
`--max-depth <N>`	Maximum include depth (default 10)

osf lint docs/ --deny-warnings

`osf fmt`

Format documents (files or directories) in place. Lossless: comments and content are kept.

osf fmt [OPTIONS] <FILES>...

Flag	Meaning
`--check`	Report files that are not formatted; change nothing
`--stdout`	Print the result instead of writing it

osf fmt --check .

`osf format`

Print a formatted document (`osf fmt` edits files in place).

osf format [OPTIONS] <FILE>

Flag	Meaning
`-o, --output <file>`	Write to this file instead of stdout
`--no-includes`	Do not resolve @include directives
`--max-depth <N>`	Maximum include depth (default 10)

`osf diff`

Semantic diff of two documents: blocks added, removed and moved, properties and content changed. Blocks are matched by id.

osf diff [--json] <OLD> <NEW>

Render

`osf render`

Render a document to html, pdf, docx, pptx, xlsx, md, json or typst. Alias: export.

osf render [OPTIONS] <FILE>

Flag	Meaning
`-t, --target <target>`	Output format (default html)
`-o, --output <file>`	Output file. Text formats go to stdout when omitted; binary formats next to the input
`--theme <name>`	default, corporate, academic, modern, dark, minimal
`--page-size <size>`	Page size for PDF and DOCX: a4 (default), letter or legal
`--landscape`	Landscape pages
`--pdf-ua`	Accessible PDF (PDF/UA-1)
`--fragment`	HTML fragment instead of a full page
`--no-metadata`	Leave out the @meta title block
`--mermaid <cmd>`	Command that renders Mermaid for print formats, called as `<cmd> -i in.mmd -o out.svg` (e.g. "mmdc")
`--allow-net[=<servers>]`	Let @data_source blocks fetch through MCP. Without a value every server is allowed; with a comma-separated list only those servers
`--mcp-config <file>`	MCP server configuration file (mcpServers JSON)
`--no-includes`	Do not resolve @include directives
`--max-depth <N>`	Maximum include depth (default 10)

osf render report.osf --target pdf --theme academic --pdf-ua -o report.pdf

`osf eval`

Evaluate sheet formulas and show the values.

osf eval [OPTIONS] <FILE>

Flag	Meaning
`--json`	JSON output
`--allow-net[=<servers>]`	Let @data_source blocks fetch through MCP. Without a value every server is allowed; with a comma-separated list only those servers
`--mcp-config <file>`	MCP server configuration file (mcpServers JSON)

`osf themes`

List the built-in themes with their colours and fonts.

osf themes

Query

`osf query`

Find blocks with a selector, e.g. 'finding[confidence>=0.8]'.

osf query [--json] <FILE> <SELECTOR>

osf query report.osf '#D-1 -> criteria' --json

`osf graph`

Print the reference graph.

osf graph [OPTIONS] <FILE>

Flag	Meaning
`--dot`	Graphviz DOT output
`--json`	JSON output: { nodes, edges }

Serve and agents

`osf serve mcp`

MCP server over stdio, or streamable HTTP with --listen. Serves a directory or .osf files (default: the current directory).

osf serve mcp [OPTIONS] [PATHS]...

Flag	Meaning
`--listen <addr>`	Serve over streamable HTTP on this address, e.g. 127.0.0.1:8091
`--write`	Allow osf.set to write files
`--allow-net[=<servers>]`	Let @data_source blocks fetch through MCP. Without a value every server is allowed; with a comma-separated list only those servers
`--mcp-config <file>`	MCP server configuration file (mcpServers JSON)

`osf serve a2a`

Run a document as an A2A agent. The document needs an @agent_card.

osf serve a2a [OPTIONS] <FILE>

Flag	Meaning
`--listen <addr>`	Address to listen on (default 127.0.0.1:8090)
`--url <url>`	Public URL to advertise in the Agent Card
`--token <token>`	Token for the security scheme declared in @agent_card (env OSF_A2A_TOKEN)
`--write`	Allow skills that change the document
`--allow-net[=<servers>]`	Let @data_source blocks fetch through MCP. Without a value every server is allowed; with a comma-separated list only those servers
`--mcp-config <file>`	MCP server configuration file (mcpServers JSON)

`osf serve http`

Preview the documents in a directory in a browser.

osf serve http [OPTIONS] [DIR]

Flag	Meaning
`--listen <addr>`	Address to listen on (default 127.0.0.1:8080)
`--allow-net[=<servers>]`	Let @data_source blocks fetch through MCP. Without a value every server is allowed; with a comma-separated list only those servers
`--mcp-config <file>`	MCP server configuration file (mcpServers JSON)

`osf card`

Print the document's A2A Agent Card. --url replaces the url in @agent_card.

osf card [--url <url>] <FILE>

`osf skill`

Install the osf Agent Skill, or print its SKILL.md.

osf skill install [--for <target>] | osf skill show

Flag	Meaning
`--for <target>`	claude (~/.claude/skills, default), project (./.claude/skills), agents (~/.agents/skills) or a directory

`osf lsp`

Run the language server on stdio (used by the VS Code extension and other editors).

osf lsp

Tooling

`osf check`

Run the conformance corpus (default spec/conformance).

osf check [DIR]

`osf schema`

Print the JSON Schema of the canonical JSON.

osf schema

`osf completions`

Print shell completions for bash, elvish, fish, powershell or zsh.

osf completions <SHELL>

Aliases

osf export is the same command as osf render, and --format is accepted for --target. Includes are resolved by default; --no-includes turns them off.

Agents: MCP and A2A →