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 |
gray completion <shell> |
Generate a shell tab-completion script |
Global Flags
Section titled “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 warning codes (e.g. W1001,W1003; see the error reference). |
--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. |
--cc <compiler> |
C compiler for this invocation (see C Compiler). |
-define:NAME=VALUE |
Override the value of the #define constant NAME at build time (see 7.5.7). May be repeated for different names. |
Command Help
Section titled “Command Help”Every command prints its own help. gray [command] --help and gray help [command] are equivalent.
gray build --helpgray help buildThe output has the command’s description and examples, then its usage line and its flags. For a subcommand, name the parent first: gray cross build --help or gray help cross build.
gray help with no command, like gray --help, prints the root help: the command list and the global flags.
C Compiler
Section titled “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--cc <compiler> on gray <file.gray> and gray build chooses the compiler for one invocation and takes precedence over $GRAY_CC and $CC. The value is a compiler name on PATH or a path to a compiler; if it cannot be found, gray reports it by name and exits non-zero.
gray main.gray --cc tccgray build main.gray -o app --cc /usr/local/bin/clangGRAY_CC and CC are different settings. GRAY_CC chooses the compiler gray uses to compile .gray programs. When building Grayscale from source, CC chooses the compiler make uses to build grayc and the runtime, and gray falls back to $CC only when $GRAY_CC is unset.
CC=clang GRAY_CC=gcc make selfhost build # grayc and the runtime built with clangmake help lists every make target. make help TARGET=<name> prints what one target does, the variables it reads and an example. TARGET is a variable because make rejects -- options before the Makefile is read and accepts only one goal. An unknown name fails with an Unknown target error, and TARGET= on any target other than help is ignored.
make help TARGET=buildgray <file.gray>
Section titled “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.graygray main.gray -q allgray main.gray -- --port 8080gray build
Section titled “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 myappgray build main.gray --emit-cgray build main.gray --emit-c -o output.cgray build main.gray --time -q allgray build main.gray --arena-limit=256MBgray check
Section titled “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 | directory/...> [flags]A directory is checked as one merged module (Imports); files directly in it form a module, and dir/... additionally checks each subdirectory as its own module. Unlike fmt, doc and test, which handle each file independently, check merges the files in a directory, so a directory of standalone programs fails with a duplicate definition. check does not require main.
| Flag | Description |
|---|---|
-q, --quiet <codes> |
Suppress warnings. |
gray check main.graygray check src/gray check src/...gray test
Section titled “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 testgray test math_test.graygray test ./src/...gray watch
Section titled “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.graygray watch src/gray fmt
Section titled “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.graygray fmt src/gray fmt ./...gray fmt --check ./...gray doc
Section titled “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.graygray doc ./...gray doc src/ -o API.mdgray new
Section titled “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 myappgray new myapp -t cligray new myapi -t server -s minimalgray new myapp -t basic -cgray new # interactive modegray man
Section titled “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 mangray man builtinsgray man mathgray man printlngray man strings.containsgray man langgray man keywordsgray man structgray man i8gray man flagsLeave 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
Section titled “gray report”Print system information for filing bug reports.
gray reportOutput includes Grayscale version, commit hash, OS, CPU, RAM, C compiler version, and target triple.
gray update
Section titled “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 updategray update --pregray install
Section titled “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 v0.11.5gray install "grayscale: v0.11.5"gray version
Section titled “gray version”Show the installed version, build commit, build timestamp, and whether newer versions are available.
gray versiongray verify
Section titled “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 verifyNot available on Windows, which has no runtime yet.
gray cross build
Section titled “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 (default: the source file name without its extension, followed by - and the target, with .exe appended for Windows targets, e.g. main-linux-arm64) |
--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-amd64gray cross build main.gray --target windows-amd64 -o myapp.exegray cross build main.gray --target linux-arm64 --emit-cgray cross targets
Section titled “gray cross targets”List all supported cross-compilation targets and their corresponding Zig triples.
gray cross targetsgray completion
Section titled “gray completion”Generate a tab-completion script for bash, zsh, fish, or powershell.
gray completion <shell>make grayc install, make selfhost install, gray update, and gray install install the script for the shell named by $SHELL (PowerShell on Windows), and gray completion install does the same on demand. No rc file is modified; when the script cannot be written, one line names the command to run instead.
| Shell | Installed to |
|---|---|
| zsh | _gray in the first writable directory on zsh’s fpath |
| bash | $XDG_DATA_HOME/bash-completion/completions/gray (default ~/.local/share/...) |
| fish | $XDG_CONFIG_HOME/fish/completions/gray.fish (default ~/.config/...) |
| powershell | ~/.gray/completions/gray.ps1 |
To load the script by hand instead:
| Shell | Setup |
|---|---|
| zsh | add source <(gray completion zsh) to ~/.zshrc, after compinit has run |
| bash | add source <(gray completion bash) to ~/.bashrc |
| fish | gray completion fish > ~/.config/fish/completions/gray.fish |
| powershell | add gray completion powershell | Out-String | Invoke-Expression to your profile |
Once loaded, Tab completes:
- subcommand names
.grayand.grayscalefiles and directories, forgray <file>and the commands that take source paths (build,check,watch,fmt,doc,test,cross build)- flag values for
gray new --template,gray new --server-type, andgray cross build --target - names for
gray man, such asgray man os.exec