CLI Reference

The rank CLI compiles, checks, tests, syncs, and serves Rank programs.

If you are new to Rank, start with Getting Started first. Use this page as the command reference once you are already building configs, manifests, tests, or HTTP apps.

For generated outputs, see Output and manifests. For HTTP apps, see HTTP Server.

Synopsis

rank [entry-or-dir] [options]                 # evaluate and emit (default: YAML; use --format json for JSON)
rank check <entry-or-dir>                     # type-check only, no output
rank test <path> [options]                    # run rank-test.json cases
rank deps <entry-or-dir> [options]            # list dependencies
rank serve <entry-or-dir> [options]           # start the server runtime
rank sync <entry-or-dir> [options]            # fetch and cache registry dependencies

---

rank [entry-or-dir] — evaluate and emit

Evaluates the program at the requested entry and writes the result to stdout. This is the primary workflow for producing output.

For ordinary document results, rank emits YAML by default and accepts --format json for JSON output. If pub main returns Emit::manifest(...), stdout contains the descriptor envelope for that manifest in the selected format. See Output and manifests.

rank src/main.rank
rank examples/faker-dataset
rank examples/faker-dataset --file-root out/
cd examples/faker-dataset && rank

entry-or-dir may be either a .rank source file or a project directory.

• If you pass a file, the compiler resolves its project manifest (rank.toml) by walking up from the file's directory.
• If you pass a directory, the CLI first looks for rank.toml in that directory and resolves [package].source/main.rank.
• If the directory has no rank.toml, the CLI falls back to ./main.rank.
• If the directory has rank.toml but the manifest is invalid, the CLI surfaces manifest diagnostics instead of falling back.
• Running bare rank from a directory that contains rank.toml is equivalent to rank ..

Flags

Flag	Description
`--format yaml	json`
--file-root <path>	Root directory for materializing a multi-file Emit::manifest(...) result.
--http-cache <path>	Load HTTP snapshot cache from <path> (a rank/http-cache JSON document). Cached responses are replayed instead of making live requests.
--write-http-cache <path>	Write a new HTTP snapshot cache to <path> after evaluation. Creates or overwrites the file.
--trace-eval-log <path>	Write newline-delimited JSON evaluation trace events to <path> while keeping stdout reserved for the evaluated result. Creates parent directories and truncates the file at the start of each run.
--emit-sensitive	When trace output is enabled, allow sensitive values to appear in emitted trace diagnostics and previews instead of <sensitive>. Requires --trace-eval-log <path>. Use only in trusted local debugging environments.
--allow-provider-capability <name>	Opt in to a declared provider capability. May be repeated. Use network to allow network-capable providers.
--offline	Reuse only locally cached registry artifacts. Fails if any required package is not yet cached.
--frozen-lockfile	Refuse to resolve missing rank.lock entries. Useful in CI to enforce that the lockfile is up to date.

Examples

Emit the default YAML result:

rank src/main.rank

Emit the same result as JSON:

rank src/main.rank --format json

Emit with an HTTP snapshot cache for reproducible output:

rank src/main.rank --http-cache snapshots.json

Capture a fresh HTTP snapshot:

rank src/main.rank --write-http-cache snapshots.json

Write a structured evaluation trace to a log file without changing stdout:

rank src/main.rank --trace-eval-log .rank/eval.ndjson

Evaluate a program that uses a network-capable provider:

rank src/main.rank --allow-provider-capability network

Write a multi-file manifest to a directory:

rank src/main.rank --file-root ./output

---

rank check — type-check only

Parses, resolves, and type-checks the program. Produces no output on success. Exits with a non-zero code and prints diagnostics on failure.

rank check src/main.rank
rank check testdata/modules/package-path-import

Use this in CI or as a pre-commit step to validate programs without running them. The argument may be either an entry file or a project directory; directory inputs resolve the same way as the run command.

In the packaged CLI, this remains a compile-only command. If you are developing from this repository with npm run rank -- ..., see Development shortcut for the current caveat around external-input examples.

Flags

Flag	Description
--allow-provider-capability <name>	Same as the run command — needed when checking programs that declare provider dependencies with capabilities.
--offline	Reuse only locally cached registry artifacts.
--frozen-lockfile	Refuse to resolve missing rank.lock entries.

Exit codes

Code	Meaning
0	No errors
1	One or more diagnostics

---

rank test — run lightweight unit tests

Runs one public-style test case directory or recursively discovers all rank-test.json cases under a suite directory.

rank test examples/tests
rank test examples/tests --filter env
rank test examples/tests/external-inputs --format json
rank test examples/tests/yaml-expected --format yaml

Each case directory contains a rank-test.json manifest plus an entry module and optional deterministic input snapshots such as env.json or http.json.

Flags

Flag	Description
--filter <pattern>	Run only cases whose discovered name or path contains <pattern>.
--format text|json|yaml	Output format. text (default) prints pass/fail lines. json and yaml emit a structured rank/test-report document.
--offline	Reuse only locally available registry artifacts while loading any package dependencies used by test cases.
--frozen-lockfile	Refuse to resolve missing registry lock entries while loading any package dependencies used by test cases.

Examples

Run the full sample suite:

rank test examples/tests

Run only the env-focused cases:

rank test examples/tests --filter env

Get a machine-readable report for one case:

rank test examples/tests/external-inputs --format json

Get the same structured report as YAML:

rank test examples/tests/yaml-expected --format yaml

Case layout

Minimal pure value case:

examples/tests/pure-addition/
	rank-test.json
	expected.json
	src/
		main.rank

Minimal manifest:

{
	"kind": "rank/test-case",
	"version": 1,
	"entry": "src/main.rank",
	"expectedValue": "expected.json"
}

expectedValue may point to expected.json, expected.yaml, or expected.yml.

Cases may also include:

• env.json for deterministic Env<T> {} inputs
• http.json for deterministic HTTP::Fetch<T> {} inputs
• a local rank.toml plus providers/ directory for deterministic path-based provider imports
• provider-stubs.json plus "providerStubs": "provider-stubs.json" for deterministic backend provider outputs keyed by public export name and exact full input
• expectedDiagnostics arrays instead of expectedValue, where each matcher uses code plus either exact message or partial messageContains

When pub main returns Emit::manifest(...), expectedValue should contain the descriptor envelope in JSON form:

{
	"kind": "rank/output-manifest",
	"version": 1,
	"entries": [
		{
			"path": "README.md",
			"format": "text",
			"value": "# api\n"
		}
	]
}

Backend provider stubs use a small JSON object keyed by public provider export name:

{
	"api::users::lookup": [
		{
			"input": {
				"id": "123",
				"cacheKey": "lookup-123"
			},
			"output": {
				"name": "stubbed-user-123"
			}
		}
	]
}

Each stub entry matches the backend provider call by exact full input. Backend provider invocations without a matching stub fail inside rank test instead of falling through to a live runtime call.

The sample cases under examples/tests/ show pure-value, YAML-expected, manifest-output, local provider, backend-provider-stub, diagnostic, environment, and combined file plus HTTP snapshot workflows.

For a more complete testing workflow guide, including provider stubs and suite layout, see Unit Testing.

---

rank deps — list dependencies

Reports all static dependencies of the program: imported modules, provider namespaces, environment variable reads, file reads, and HTTP fetch nodes.

rank deps src/main.rank
rank deps testdata/modules/provider-function-import
rank deps src/main.rank --format json
rank deps src/main.rank --format json --explain <id>

The argument may be either an entry file or a project directory; directory inputs resolve the same way as the run command.

Flags

Flag	Description
--format text|json	Output format. text (default) prints a human-readable report. json emits a rank/dependency-report document.
--explain <id>	Resolve a single graph node or dependency ID back to its dependency path from the entry node. Requires --format json.
--allow-provider-capability <name>	Same as the run command — needed when checking programs that declare provider dependencies with capabilities.

Examples

Print a human-readable dependency report:

rank deps src/main.rank

Get a structured JSON report:

rank deps src/main.rank --format json

Explain why a specific node is a dependency:

rank deps src/main.rank --format json --explain env:APP_ENV

---

rank serve — server runtime

Starts the HTTP server runtime for a Rank app. The server compiles the entry module and evaluates pub main for each inbound request.

rank serve src/handler.rank
rank serve examples/serve-docker
rank serve src/handler.rank --port 3000
rank serve src/handler.rank --host 0.0.0.0 --port 8080
rank serve src/handler.rank --dev

The argument may be either an entry file or a project directory; directory inputs resolve the same way as the run command.

See the HTTP Server guide for a full walkthrough of routes, responses, auth, and deployment.

Flags

Flag	Description
--host <host>	Interface to bind. Defaults to 127.0.0.1. Use 0.0.0.0 to listen on all interfaces (required in Docker).
--port <port>	Port to listen on. Defaults to 3000.
--shutdown-grace-ms <ms>	Grace period in milliseconds after receiving SIGINT/SIGTERM before forcibly closing connections. Defaults to 0.
--dev	Enable development mode.
--trace-eval	Stream newline-delimited JSON evaluation trace events to stdout for startup and request-time evaluation.
--emit-sensitive	When trace output is enabled, allow sensitive values to appear in emitted trace diagnostics and previews instead of <sensitive>. Requires --trace-eval. Use only in trusted local debugging environments.
--provider-timeout <ms>	Timeout in milliseconds for provider invocations.
--allow-provider-capability <name>	Opt in to a declared provider capability. May be repeated. Use network to allow network-capable providers.
--allow-http-host <host>	Allowlist a specific host for outbound HTTP::Fetch calls made at serve time. May be repeated.
--allow-env <pattern>	Allowlist an environment variable name or glob pattern for Env<T> reads. May be repeated.
--offline	Reuse only locally cached registry artifacts.
--frozen-lockfile	Refuse to resolve missing rank.lock entries.

Examples

Start with default host and port:

rank serve src/handler.rank

Bind to all interfaces on port 8080 (typical inside Docker):

rank serve . --host 0.0.0.0 --port 8080

Allow outbound HTTP fetches to a specific host and read an environment variable:

rank serve . --allow-http-host api.example.com --allow-env API_KEY

Allow a network-capable provider and set a graceful shutdown window:

rank serve . --allow-provider-capability network --shutdown-grace-ms 5000

Stream structured evaluation traces for live requests:

rank serve . --trace-eval

For guidance on reading trace output and combining it with request-time failures, see Debugging.

Built-in readiness endpoint

The server exposes /.well-known/rank/ready independently of the application route table. It returns 200 OK once the runtime is ready to accept traffic. Use this path for load balancer health checks or the Lambda Web Adapter READINESS_CHECK_PATH configuration.

---

rank sync — fetch and cache external dependencies

Resolves external dependencies declared in rank.toml, materializes any missing registry artifacts or git snapshots, and writes or updates rank.lock. No program is evaluated — this command only performs dependency materialization.

In the current slice, this includes registry-backed dependencies, registry-backed providers, and git-backed dependencies. Providers remain path- or registry-backed only.

rank sync src/main.rank
rank sync path/to/project

This is useful as an explicit pre-fetch step in CI or Docker builds before running in offline mode. For { git, tag } dependencies, rank sync resolves the tag to a commit and records that commit in rank.lock. The argument may be either an entry file or a project directory; directory inputs resolve the same way as the run command.

Flags

Flag	Description
--offline	Reuse only locally cached registry artifacts and git snapshots. Fails if any required package or snapshot is missing.
--frozen-lockfile	Refuse to resolve missing rank.lock entries. Useful for verifying that rank.lock is committed and up to date.

Examples

Pre-fetch registry packages and git-backed dependencies:

rank sync src/main.rank

Verify the lockfile is up to date without fetching:

rank sync src/main.rank --frozen-lockfile

Run subsequent commands offline after a successful sync:

rank sync src/main.rank
rank src/main.rank --offline

---

Global behavior

Diagnostics

All diagnostic output goes to stderr. On success, stdout contains only the command result: YAML for rank, the manifest descriptor envelope for Emit::manifest(...), or the selected text/JSON/YAML format for commands such as test and deps. This makes it safe to pipe command output directly:

rank deps src/main.rank --format json | jq '.'

Entry resolution

When the CLI receives a file entry, the compiler locates the project manifest by walking up from that file's directory until it finds a rank.toml. The manifest's source field determines the module root.

When the CLI receives a directory entry, it resolves that directory first:

• if rank.toml is present, the CLI resolves [package].source/main.rank
• if rank.toml is absent, the CLI falls back to ./main.rank
• if rank.toml is present but invalid, the CLI reports manifest diagnostics instead of falling back

Bare rank uses the same directory resolution as rank . when the current working directory contains rank.toml.

Provider capabilities

Provider capability enforcement is a compile-side allowlist check. A provider that declares the network capability requires --allow-provider-capability network at the call site or the invocation is blocked. This makes capability use explicit and auditable in CI scripts.

---

Development shortcut

When working from the repository source tree, run the CLI without a prior build:

npm run rank -- check src/main.rank
npm run rank -- src/main.rank

:::note Repository source-tree caveat npm run rank -- check <entry> is still the fastest syntax and type pass while developing inside this repo, but examples that use Env<T>, File::Read, HTTP::Fetch, or providers should also be confirmed with npm run rank -- <entry> or npm run rank -- serve <dir>.

The current dev-path check command can still surface browser-host external-input errors such as Browser evaluation does not support std::Env even when the packaged CLI and real serve runtime compile the same program successfully. :::