Skip to content

getting-started.md

Latest commit

 

History

History
94 lines (54 loc) · 3.6 KB

getting-started.md

File metadata and controls

94 lines (54 loc) · 3.6 KB
Raw

Getting started

Install ignatius, then point it at a folder of entity files and open the graph it serves.

Install

Install script (recommended)

The install script detects your operating system and architecture, downloads the matching binary from the latest GitHub release, verifies its checksum, and puts it on your $PATH:

curl -fsSL https://raw.githubusercontent.com/noormdev/ignatius/main/install.sh | sh

It installs to /usr/local/bin when that directory is writable, otherwise $HOME/.local/bin (add that to your PATH if it isn't already). Two environment overrides:

  • IGNATIUS_INSTALL_DIR=/some/dir — install somewhere else.
  • IGNATIUS_VERSION=v0.2.0 — pin a specific release tag instead of the latest.

Verify with ignatius --help. The binary is self-contained: it has no runtime dependency and works on machines without Bun installed.

Once installed, ignatius version prints the current version and ignatius update checks for a newer release and installs it in place. See Commands.

Download a release manually

Prefer to do it by hand, or on Windows? Pick the binary for your platform from the latest GitHub release and put it on your $PATH:

# macOS arm64
curl -L -o ignatius https://github.com/noormdev/ignatius/releases/latest/download/ignatius-darwin-arm64
chmod +x ignatius
sudo mv ignatius /usr/local/bin/

# Linux x64
curl -L -o ignatius https://github.com/noormdev/ignatius/releases/latest/download/ignatius-linux-x64
chmod +x ignatius
sudo mv ignatius /usr/local/bin/

Windows users download ignatius-windows-x64.exe from the same page. Releases include checksums.txt if you want to verify a download with shasum -a 256 -c.

From source

ignatius is built with Bun. Install Bun first, then clone and build:

git clone https://github.com/noormdev/ignatius.git
cd ignatius
bun install
bun run build:cli

That produces ./dist/ignatius. See Building from source for what each build stage does.

Quick start

Point the dev CLI at the bundled reference schema and open the page it serves:

bun run dev:cli

That serves the models/ reference schema (three variants of the same data model: key-inherited, orm-hybrid, orm-pure) at http://localhost:3000. Edit any file under models/ and the graph reloads in the browser without a refresh.

To run against your own folder, call the CLI directly with the serve subcommand:

ignatius serve path/to/your/models --port 3000

Add -o (or --open) to launch the graph in your default browser as soon as the server starts.

If the path contains multiple model folders, ignatius lists them and prompts you to pick one. Pass --model <key> to skip the prompt. See Commands for the full discovery rules.

Next steps

  • The folder format — how to structure entity files, groups, and ignatius.yml.
  • What gets derived — cardinality, classification, and subtype clusters come from the structure, not from labels you set.
  • Process flows — add data flow diagrams that show how processes move the data.
  • Commands — serve, export, validate, index, and approve in full.
  • Change review — see what changed since you last approved the model, with the notes that explain it.
  • Authoring with the modeling skill — let /ignatius-modeling write entity and flow files for you.