Skip to main content

Construct the client

Both options are optional. Engine resolution is strict: bin, then NIKA_BIN, then the platform package npm installed with the SDK (@nika-open/nika-<os>-<arch>). bin and NIKA_BIN must be absolute paths: a bare name or a relative path throws NikaConfigurationError, and a missing file fails the engine’s identity probe with NikaCompatibilityError. A nika on your PATH is never used. cwd anchors relative workflow paths, project-file discovery and the .nika/ state directory. On a platform without a bundled engine (Windows, Alpine or another musl Linux), new Nika() with neither bin nor NIKA_BIN throws NikaEngineUnavailable. Point bin at a compatible engine, or use a nika serve by URL.

Probe compatibility with a check

The client has no separate version method: before any operation it probes the engine’s identity (nika --sdk-identity) and refuses an engine of another machine protocol with NikaCompatibilityError. Make a real, read-only check at startup when the application cannot operate without Nika:
The engine owns the open report shape. Known fields aid TypeScript completion; future engine fields pass through unchanged.

Native method boundary

Local mode supports check, compile, run, run.events(), run.result(), run.cancel() and traceVerify. attachRun, run.status(), workflow discovery and schedules need a server that owns durable state; on the local transport they throw NikaCompatibilityError.
The client spawns the engine with an argv array (nika run <file> --json), never through a shell, so a workflow path cannot inject a command. Literal inputs travel on the engine’s standard input, never in argv. The engine still enforces permits, secrets, spend and its runtime floor.

Check

Read the engine-owned admission report.

Run lifecycle

Observe, settle and cancel without conflating them.