@rank-lang/cli

Node.js command-line interface for Rank.

Full documentation →

Install

npm install -g @rank-lang/cli

This installs the rank binary.

Commands

rank [entry-or-dir] [--format yaml|json] [--file-root <path>] [--http-cache <path>] [--write-http-cache <path>]
     [--allow-provider-capability <name>] [--allow-http-host <host>]
     [--provider-timeout <ms>] [--offline] [--frozen-lockfile]
rank check <entry-or-dir> [--allow-provider-capability <name>] [--allow-http-host <host>]
     [--offline] [--frozen-lockfile]
rank test <path> [--filter <pattern>] [--format text|json|yaml] [--offline] [--frozen-lockfile]
rank deps <entry-or-dir> [--format text|json] [--explain <id>]
     [--allow-provider-capability <name>] [--allow-http-host <host>]
     [--offline] [--frozen-lockfile]
rank sync <entry-or-dir> [--offline] [--frozen-lockfile]
rank serve <entry-or-dir> [--host <host>] [--port <port>] [--shutdown-grace-ms <ms>] [--dev]
     [--provider-timeout <ms>] [--allow-provider-capability <name>]
     [--allow-http-host <host>] [--allow-env <pattern>]
     [--offline] [--frozen-lockfile]

Notes

• rank [entry-or-dir] evaluates the entrypoint and prints structured output. YAML is the default; pass --format json for JSON.
• rank, when run from a directory that contains rank.toml, is equivalent to rank ..
• rank, rank check, rank deps, rank serve, and rank sync accept either a .rank entry file or a project directory.
• When a directory is provided, the CLI resolves rank.toml in that directory and uses [package].source/main.rank; if no manifest is present, it falls back to ./main.rank.
• If rank.toml exists but is invalid, the CLI surfaces manifest diagnostics instead of falling back to main.rank.
• rank check performs diagnostics-only validation.
• rank test runs fixture-style cases rooted at rank-test.json.
• rank deps explains dependency resolution for a program.
• rank sync refreshes external dependency state without running the entrypoint.
• rank serve validates a server-style entrypoint, starts the live HTTP listener, and on shutdown stops accepting new connections, closes idle keep-alives, and waits up to --shutdown-grace-ms before force-closing remaining connections.
• rank serve --dev adds verbose detail strings to runtime-generated validation and request-shape error responses; prod mode keeps the stable { code, fields } shape without those extra details.
• rank serve also honors pub config.allowedOrigins and pub config.allowCredentials by synthesizing CORS preflight OPTIONS responses and attaching matching CORS headers to ordinary responses for admitted origins.

Security flags

Security settings can be declared in rank.toml under [security] and overridden per-invocation by CLI flags. CLI flags are unioned with TOML for additive settings; scalar settings (--provider-timeout, --offline) have CLI take precedence.

| Flag | Commands | Description | |------|----------|-------------| | --allow-provider-capability <name> | rank, rank check, rank deps, rank serve | Admit providers that declare this capability. Repeatable. Standardized values: network, filesystem. | | --allow-http-host <host> | rank, rank check, rank deps, rank serve | Restrict HTTP::Fetch to this hostname. Repeatable. When absent (and no TOML default), all hosts are permitted. | | --allow-env <pattern> | rank serve | Admit runtime environment variables for zero-arg pub config and request-time providers. Repeatable. | | --provider-timeout <ms> | rank, rank serve | Kill a provider process that does not respond within this many milliseconds. | | --offline | rank, rank check, rank deps, rank test, rank sync, rank serve | Block live HTTP fetches; require cached snapshots. |

Equivalent rank.toml section:

[security]
allow-provider-capabilities = ["network", "filesystem"]
allow-http-hosts = ["api.example.com"]
provider-timeout-ms = 30000
offline = false

Development

npm run build -w @rank-lang/cli
npm run test -w @rank-lang/cli
npm run typecheck -w @rank-lang/cli

Publishing

Build the package first, then publish from the workspace root:

npm run build -w @rank-lang/cli
npm publish -w @rank-lang/cli