npm package: @oml/cli
Description: The cli specific package
Latest version: 0.13.0

# OML CLI

`@oml/cli` is the command-line interface for linting, compiling, reasoning over, rendering, and validating OML workspaces.

## Package Layout

- [package.json](./package.json) - package manifest and published CLI entry
- [bin/cli.js](./bin/cli.js) - executable entrypoint used by the published `oml` command
- [src/main.ts](./src/main.ts) - TypeScript entrypoint
- [src/cli.ts](./src/cli.ts) - command registration and top-level CLI wiring
- [src/commands](./src/commands) - `lint`, `compile`, `reason`, `render`, and `validate` command implementations
- [src/backend](./src/backend) - shared RDF/reasoning and markdown execution support

## Instructions

Use the public npm registry for `@oml/*` packages:

```ini
registry=https://registry.npmjs.org/
@oml:registry=https://registry.npmjs.org/
```

From the repo:

```bash
node ./packages/cli/bin/cli.js --help
```

When installed, the command name is `oml`.

The CLI uses the built-in production OML Platform endpoint by default. Set `OML_PLATFORM_API_URL=<url>` to override it.

### Quick Start

```bash
# Lint the current workspace
node ./packages/cli/bin/cli.js lint

# Lint against a local platform dev server
OML_PLATFORM_API_URL=http://127.0.0.1:8787 \
node ./packages/cli/bin/cli.js lint

# Compile RDF output
node ./packages/cli/bin/cli.js compile -w . -owl build/owl

# Check consistency only
node ./packages/cli/bin/cli.js reason -w . -owl build/owl --check-only

# Render markdown to static HTML
node ./packages/cli/bin/cli.js render -w . -md src/md -web build/web -owl build/owl
```

### Commands

- `login`
  Runs GitHub device-flow sign-in, exchanges the GitHub token with the OML Platform, and stores the returned platform session.
- `logout`
  Removes the local sign-in session.
- `whoami`
  Prints the current sign-in session.
- `lint [-w <workspace>]`
  Validates one file, or the current workspace when no file is given.
- `compile [-w <workspace>] [-owl <dir>] [-f <ttl|trig|nt|nq|n3>] [--clean] [--only] [--pretty]`
  Compiles OML to RDF.
- `reason [-w <workspace>] [-owl <dir>] [-f <ttl|trig|nt|nq|n3>] [--clean] [--only] [--pretty] [--check-only] [-u <true|false>] [-e <true|false>] [-p <true|false>]`
  Runs consistency checking and, unless `--check-only` is used, generates entailments.
- `render [-w <workspace>] -md <dir> -web <dir> [-owl <dir>] [-f <ttl|trig|nt|nq|n3>] [-c <model-uri>] [--clean] [--only] [--pretty] [-u <true|false>] [-e <true|false>] [-p <true|false>]`
  Runs the compile/reason pipeline, then renders markdown to static HTML.
- `validate -md <dir> [-w <workspace>] [-owl <dir>] [-f <ttl|trig|nt|nq|n3>] [--clean] [--only] [--pretty] [-u <true|false>] [-e <true|false>] [-p <true|false>]`
  Validates markdown table-editor SHACL blocks against their context models.

### Notes

- Pass `--debug` with any command (for example `oml login --debug`) to print stack traces and nested error causes.
- The CLI uses `OML_PLATFORM_API_KEY` when it is set. Otherwise, operational commands use the token from `oml login` for platform authorization.
- OAuth login refresh uses built-in Supabase defaults. Set `OML_SUPABASE_URL` or `OML_SUPABASE_ANON_KEY` to override them.
- GitHub device-flow login requires `OML_AUTH_GITHUB_CLIENT_ID`, unless you embed `DEFAULT_GITHUB_CLIENT_ID` in [`src/auth.ts`](./src/auth.ts).
- `oml login` exchanges the GitHub token with the platform at `OML_PLATFORM_API_URL` or the built-in default endpoint, then stores the platform session locally.
- The CLI depends on `@oml/reasoner`.
- `reason` runs ontology consistency checks in dependency order.
- `render` runs the compile/reason pipeline unless `--only` is provided, then renders markdown, resolves `workspace:/` links, executes markdown blocks, and copies referenced non-markdown assets.
- If the reasoner reports an inconsistent ontology, the CLI exits with code `1` and prints the raw JSON result returned by the reasoner.
- When installed from npm, the CLI checks the npm registry for newer `@oml/cli` releases and prints `npm install -g @oml/cli@latest` when an update is available. Set `OML_NO_UPDATE_NOTIFIER=1` to disable the check.