CLI Commands

The gray command-line tool provides the following commands:

Command	Description
gray <file.gray>	Compile and run a source file
gray build <file.gray>	Compile to a distributable binary
gray check <file.gray>	Type-check without compiling
gray test [path...]	Compile and run #test functions
gray watch <file.gray>	Watch for changes and re-run on save
gray fmt <path>	Format source files
gray doc <path>	Generate documentation from #doc attributes
gray new <name>	Scaffold a new project
gray man <name>	Show documentation for builtins, stdlib, and language reference
gray report	Print system info for bug reports
gray verify	Run the built-in language verification test suite
gray update	Check for updates and upgrade
gray install <version>	Install a specific version by exact semver
gray version	Show version information
gray cross build <file.gray>	Cross-compile for another platform via Zig
gray cross targets	List supported cross-compilation targets

Global Flags

These flags are available on gray <file>, build, check, and watch:

Flag	Description
-q, --quiet <codes>	Suppress warnings. Use all to suppress all, or a comma-separated list of codes (e.g. W1001,W1003).
--no-color	Disable colored diagnostic output.
--arena-limit=<size>	Maximum arena memory per program. Accepts a size with unit suffix: KB, MB, or GB (e.g. 512MB, 1GB). Defaults to 1GB. When exceeded at runtime, the program panics with P0104.

C Compiler

gray compiles the generated C with the first of $GRAY_CC, $CC, cc, gcc or clang found on PATH. GCC, Clang and TinyCC (tcc) are supported. TinyCC compiles much faster, which suits the edit-run loop; it builds the runtime from source on every compile instead of linking libgrayrt.a.

GRAY_CC=tcc gray main.gray

gray <file.gray>

Compile and run a source file in one step.

gray <file.gray> [flags] [-- args...]

Arguments after -- are forwarded to the compiled program.

gray main.gray
gray main.gray -q all
gray main.gray -- --port 8080

gray build

Compile a source file to a native binary.

gray build <file.gray> [flags]

Flag	Description
-o, --output <name>	Output binary name. Defaults to the input filename without .gray.
--emit-c	Emit the generated C source to a file without compiling to a binary. No binary is produced. Uses -o for the output path, or defaults to <input>.c (e.g., main.gray → main.c).
--time	Show compilation timing.
-q, --quiet <codes>	Suppress warnings.
--no-color	Disable colored output.
--arena-limit=<size>	Cap arena memory (e.g. 512MB, 1GB). Default: 1GB.

gray build main.gray -o myapp
gray build main.gray --emit-c
gray build main.gray --emit-c -o output.c
gray build main.gray --time -q all
gray build main.gray --arena-limit=256MB

gray check

Type-check a file or project without compiling. Returns a non-zero exit code if errors are found.

gray check <file.gray | directory> [flags]

Flag	Description
-q, --quiet <codes>	Suppress warnings.

gray check main.gray
gray check src/

gray test

Compile and run every function marked with the #test attribute.

gray test [path...] [flags]

With no path, gray test scans the current directory recursively for .gray files containing a #test function (the same as gray test ./...). Paths follow the same patterns as gray fmt (see gray fmt): a single file, a directory (non-recursive), or dir/... (recursive). Each source file is compiled to its own temporary test binary and run.

Flag	Description
--no-color	Disable colored output.

A failed assert or runtime panic inside a #test function is reported as a failure and the runner continues. The exit code is non-zero if any test fails or any file fails to compile.

gray test
gray test math_test.gray
gray test ./src/...

gray watch

Watch a file or directory for changes and re-run on save. Automatically discovers and watches imported files.

gray watch <file.gray | directory> [flags]

Flag	Description
-q, --quiet <codes>	Suppress warnings.
--no-color	Disable colored output.

When watching a directory, Grayscale finds the file containing main() and watches all .gray files in the directory.

gray watch main.gray
gray watch src/

gray fmt

Format .gray source files in place. Normalizes indentation to 4 spaces, removes trailing whitespace, ensures a final newline, and collapses runs of more than 2 blank lines.

gray fmt <path> [flags]

Flag	Description
--check	Check formatting without modifying files. Exits non-zero if any file would change. Intended for CI.

Supported path patterns:

Pattern	Scope
file.gray	Single file
dir	All .gray files in directory (non-recursive)
..., ./..., or dir/...	Recursive walk for all .gray files

A file named more than once is processed once. A path that does not exist, or is neither a .gray file nor a directory, is reported and skipped; the command still processes the remaining paths and then exits non-zero. gray doc and gray test accept the same patterns.

gray fmt main.gray
gray fmt src/
gray fmt ./...
gray fmt --check ./...

gray doc

Generate markdown documentation from #doc attributes in source files.

gray doc <path> [flags]

Flag	Description
-o, --output <path>	Output file path. Defaults to DOCS.md.

Supports the same path patterns as gray fmt (single file, directory, ./... recursive).

gray doc main.gray
gray doc ./...
gray doc src/ -o API.md

gray new

Scaffold a new Grayscale project.

gray new [project-name] [flags]

Flag	Description
-t, --template <name>	Template to use. One of: basic, cli, lib, multi, server, client. Defaults to basic.
-s, --server-type <type>	minimal or normal. Only applies to server and client templates. Defaults to normal.
-c, --comments	Include a quick-reference comment block in the entry file.
-f, --force	Overwrite an existing directory.

Running gray new with no arguments enters interactive mode, which prompts for the project name, template, and options.

gray new myapp
gray new myapp -t cli
gray new myapi -t server -s minimal
gray new myapp -t basic -c
gray new                          # interactive mode

gray man

Show documentation for builtin functions, stdlib modules, stdlib types, and language reference (keywords, types, symbols, attributes).

gray man [name]

Argument	Result
(none)	Show usage and list available stdlib modules.
builtins	List all builtin functions by category.
<module>	List all functions and types in a stdlib module.
<name>	Show documentation for a specific function or type.
<module>.<name>	Qualified lookup to resolve ambiguity.
lang	Overview of all language reference categories.
keywords	List all keywords by category.
types	List all types by category.
symbols	List all symbols.
attributes	List all attributes.

gray man
gray man builtins
gray man math
gray man println
gray man strings.contains
gray man lang
gray man keywords
gray man struct
gray man i8
gray man flags

Leave the () off the name: the shell interprets bare parentheses as a function definition before gray sees them. Use the name alone, gray man println, not gray man println().

For attributes, leave off the # prefix, because the shell treats # as a comment. Use gray man flags, not gray man #flags.

gray report

Print system information for filing bug reports.

gray report

Output includes Grayscale version, commit hash, OS, CPU, RAM, C compiler version, and target triple.

gray update

Check for updates and upgrade to a newer version.

gray update [flags]

Flag	Description
--pre	Install the latest pre-release (alpha/beta/rc) instead of latest stable.

gray update
gray update --pre

gray install

Install a specific Grayscale version by exact semver, replacing the current installation. Supports downgrades and pre-release tags.

gray install <version>

gray install 3.0.0
gray install 3.1.0-beta.2

gray version

Show the installed version, build commit, build timestamp, and whether newer versions are available.

gray version

gray verify

Run the built-in language verification suite. Compiles and runs an embedded Grayscale test program to confirm the toolchain (compiler, runtime, C backend) is working. Exits non-zero on failure.

gray verify

Not available on Windows, which has no runtime yet.

gray cross build

Cross-compile a Grayscale source file for another platform using Zig as the C cross-compiler backend.

gray cross build <file.gray> --target <target> [flags]

Flag	Description
--target <target>	Target platform (required)
-o, --output <name>	Output binary name
--emit-c	Emit generated C source to a file (no binary)
--time	Show compilation timing
-q, --quiet <codes>	Suppress warnings (all or comma-separated codes)
--no-color	Disable colored output

Supported targets:

Target	Zig Triple
linux-amd64	x86_64-linux-gnu
linux-arm64	aarch64-linux-gnu
windows-amd64	x86_64-windows-gnu
mac-arm64	aarch64-macos
mac-amd64	x86_64-macos

Zig must be installed and available on PATH. It is only required for cross-compilation — native builds (gray build) use the system C compiler.

Examples:

gray cross build main.gray --target linux-amd64
gray cross build main.gray --target windows-amd64 -o myapp.exe
gray cross build main.gray --target linux-arm64 --emit-c

gray cross targets

List all supported cross-compilation targets and their corresponding Zig triples.

gray cross targets