janus CLI

The janus binary groups compiler, package, documentation, cache, and inspection tools behind one command surface.

janus <command> [args...]
janus help <command>
janus commands

Run janus commands to print the current command surface grouped by domain. Run janus help build, janus help query, or any other command name for command-specific usage.

Build and Run

Command	Purpose
`janus run <source.jan> [args...]`	Execute a Janus script through the `:script` JIT path.
`janus build <source.jan> [output]`	Compile a Janus source file through the QTJIR pipeline.
`janus test <source.jan>`	Run Janus test declarations via the script runner.
`janus fmt <files...>`	Format Janus source files.
`janus lint --stdlib-boundaries`	Verify the `std.mem`, `std.alloc`, and `std.conv` doctrine border.
`janus lint --ambient-authority`	Verify that resource APIs expose capability-token variants.
`janus lint --zigisms`	Verify that `.jan` and `.jans` files avoid Zig heritage syntax.
`janus lint --haiku`	Run the Janus Haiku doctrine profile.
`janus parse <source.jan>`	Run parser-only diagnostics.
`janus validate --promotable <file.jans>`	Check whether a `:script` file can be promoted to `:core`.
`janus desugar <file.jans>`	Desugar script syntax into canonical Janus source.
`janus translate-c <header.h>`	Translate C headers into Janus extern declarations.

Inspect and Query

Command	Purpose
`janus cid <file.jan>`	Compute a content identifier for a module.
`janus cid --expr "<expression>"`	Compute a content identifier for an expression.
`janus inspect <source.jan>`	Inspect AST and symbol information.
`janus query ...`	Query semantic indexes, docs, logs, and module function CIDs.
`janus diff <old> <new>`	Run semantic diff analysis.
`janus oracle <mode>`	Access lower-level semantic analysis tools.
`janus demangle <name>`	Convert generated symbols into readable names.

Project and Packages

Command	Purpose
`janus init [name]`	Scaffold a new Janus project.
`janus doc <source.jan>`	Generate or validate API documentation.
`janus profile show`	Show active profile information.
`janus profile explain <feature>`	Explain the profile that owns a feature.
`janus resolve <name>[@<constraint>]`	Resolve package dependencies through Hinge.
`janus pkg <subcommand>`	Delegate package operations to Hinge.

Maintenance and Release

Command	Purpose
`janus cache <stats	ls
`janus doctor tmp`	Diagnose and reap temporary or scratch directories.
`janus test-cas`	Run the Content-Addressed Storage smoke check.
`janus release [--dry-run]`	Build, sign, and publish a release.
`janus version`	Show compiler version and feature summary.

Terminal Output

The CLI uses grouped help, command-specific help, typo suggestions, and terminal-aware styling. Set NO_COLOR=1 to disable ANSI colors. Set JANUS_ASCII=1 to force ASCII markers instead of Unicode symbols.

Unicode braille markers are ordinary terminal text, not a Python-only TUI feature. Janus can render the same style from Zig by writing braille frames such as ⠋, ⠙, ⠹, ⠸, ⠼, ⠴, ⠦, ⠧, ⠇, and ⠏ with carriage-return updates. Long-running commands should gate animated progress behind terminal detection and fall back to plain logs in CI, pipes, or JANUS_ASCII=1.

Standard library boundary lint

janus lint --stdlib-boundaries enforces the standard library ownership border:

std.mem owns raw address and byte operations.
std.alloc owns allocation and memory ownership APIs.
std.conv owns value conversions.

The lint fails if allocator APIs are exposed through std.mem, raw pointer reinterpretation appears in std.alloc, or value conversion helpers live in std.mem. The build step check-stdlib-boundaries runs the same check, and ./scripts/zb test depends on it.

Ambient authority lint

janus lint --ambient-authority checks standard library resource APIs for explicit capability-token variants.

The lint covers the current public OS, network, and executor facades. A resource-touching public function such as std.os.fs.open, std.net.tcp.connect, or std.exec.spawn must expose a matching capability form such as open_sovereign, connect_cap, or spawn_cap.

The build step check-ambient-authority runs this lint, and ./scripts/zb test depends on it.

Zig-isms lint

janus lint --zigisms checks Janus source for Zig syntax that must stay out of ordinary .jan and .jans files. It skips graft zig do ... end blocks, where the syntax is intentionally Zig.

The lint rejects common drift patterns such as fn, &&, ||, ::, &mut, comptime { ... }, Zig-style pub const Name = struct { ... } declarations, and Zig expression builtins like @ptrCast, @intCast, and @sizeOf.

The build step check-zigisms runs this lint, and ./scripts/zb test depends on it.

Janus Haiku lint

janus lint --haiku is the umbrella doctrine profile. It runs the Zig-isms, standard library boundary, and ambient authority checks together.

Files can opt into stricter Haiku shape checks with either marker:

//! haiku: strict

or:

{.profile: haiku.}

In strict files, the lint also enforces snake_case functions, PascalCase types, UPPER_SNAKE_CASE top-level constants, explicit tags for public raw pointer signatures, and std.mem use only for raw memory operations.

The build step check-haiku runs this lint, and ./scripts/zb test depends on it.