Skip to main content

Getting Started

This guide takes you from zero to a working Rank program. By the end you will have installed the compiler, written a .rank file, and produced your first output.

If you want the language model before you install anything, read Introduction and Concepts. After this guide, use the CLI reference and Examples as your working reference.

Requirements​

  • Node.js 20 or newer
  • npm 10 or newer

Install​

npm install -g @rank-lang/cli

Verify it worked:

rank --help

You should see the command summary printed to your terminal.

Your first program​

Create a new project directory with a manifest and a source file:

mkdir hello-rank
cd hello-rank

Create rank.toml:

manifestVersion = 1

[package]
name = "hello-rank"
version = "0.1.0"
source = "src"

Create src/main.rank:

greeting = `Hello, Rank!`

config = {
  message: greeting,
  version: 1,
}

pub main = || config

Check the program​

Run the type-checker to validate the program without producing output:

rank check src/main.rank

No output means no errors. If there is a problem, the compiler prints a diagnostic with a source location.

Produce output​

Run the program and emit YAML, which is the default:

rank src/main.rank

You should see:

message: Hello, Rank!
version: 1

If you prefer JSON, pass --format json:

rank src/main.rank --format json
{
  "message": "Hello, Rank!",
  "version": 1
}

The primary rank command prints YAML for ordinary document results by default and supports --format json for JSON output. If you need multiple generated artifacts, return Emit::manifest(...) from pub main instead. See Output and manifests.

Add a type annotation​

Rank lets you annotate bindings with explicit types. Add a type to config in src/main.rank:

Config = Object {
  message: string,
  version: number,
}

greeting = `Hello, Rank!`

config: Config = {
  message: greeting,
  version: 1,
}

pub main = || config

Run rank check src/main.rank again — the compiler now validates that config matches the Config type.

Try introducing a type error:

config: Config = {
  message: greeting,
  version: `not a number`,
}
rank check src/main.rank

The compiler reports the mismatch with a source location before any output is produced.

Read an environment variable​

Rank reads environment variables through the Env<T> {} built-in. Update src/main.rank:

SysEnv = Object {
  APP_ENV: string,
  ...: string,
}

env = Env<SysEnv> {}

config = {
  message: `Hello, Rank!`,
  version: 1,
  env: env.APP_ENV,
}

pub main = || config

Run it with the variable set:

APP_ENV=production rank src/main.rank
message: Hello, Rank!
version: 1
env: production

The same command also accepts --format json when you need machine-readable stdout.

If APP_ENV is not set, the compiler reports a missing environment variable diagnostic.

What's next​