Skip to main content

Command Line Interface

The zynx command-line tool is the primary entry point for working with Zynx projects. It provides a cohesive interface for:

  • creating and managing workspaces
  • building and running code
  • executing tests and formatting sources
  • managing SDKs and packages
  • generating and syncing C bindings

This document describes the core commands and their intended usage. For a deeper dive into specific topics, see:

Global Usage​

zynx <command> [subcommand] [options] [args...]

Global flags (common to most commands):

  • -h, --help – Show help for a command.
  • -v, --verbose – Increase output verbosity (can be repeated).
  • --version – Print the zynx tool version.

Unless otherwise noted, commands operate on the workspace containing the current working directory (the directory with zynx.json).

Notable specialized commands also include:

  • zynx bindgen ... for C header translation
  • zynx meta ... for dynamic-module metadata inspection and embedding

Workspace Management​

new​

Create a new Zynx project from a template.

zynx new <name> [--type <kind>] [--path <dir>]
  • <name> – Project name (also used as the default module name).
  • --type <kind>:
    • library – Reusable Zynx library (default).
    • executable – Application with a main entry point.
    • ffi – Project focused on local C bindings.
  • --path <dir> – Target directory (defaults to ./<name>).

The command scaffolds:

<name>/
├── src/
│   └── main.zx   # or lib.zx for library projects
└── zynx.json     # workspace configuration

init​

Initialize a zynx.json manifest in an existing directory.

zynx init [--name <name>] [--type <kind>]
  • --name <name> – Project name (defaults to directory name).
  • --type <kind> – Same values as new.

Use this when you already have source files and want to turn the directory into a Zynx workspace.

Build and Execution​

build​

Compile the current project or a single source file.

zynx build [<path>] [--profile <profile>] [--target <triple>] [--out-dir <dir>]
  • <path> – Optional path to a .zx file; if omitted, builds the entire workspace.
  • --profile <profile> – Build profile:
    • debug (default) – Faster compilation, debug info, minimal optimization.
    • release – Optimized build suitable for production.
  • --target <triple> – Compilation target triple (for example, x86_64-linux-gnu).
  • --out-dir <dir> – Custom output directory for build artifacts.
  • --incremental / --no-incremental – Enable or disable incremental project builds.
  • --jobs <n> – Limit parallel build workers to <n>.

Notes:

  • When building a workspace, zynx reads zynx.json for target settings and module layout.
  • When building a single file, zynx uses a minimal implicit module graph rooted at that file.
  • For workspace builds, incremental compilation is enabled by default.
  • Parallel build jobs are auto-sized by default from available CPUs and ready work; use --jobs to cap.

run​

Compile and immediately execute a program.

zynx run [<path>] [--profile <profile>] [--target <triple>] [--] [args...]
  • <path> – Optional source file. If provided, runs that file directly.
  • --profile, --target – Same semantics as build.
  • -- – Separator; everything after is passed to the compiled binary.

When <path> is omitted, zynx run resolves and runs the workspace entry from zynx.json (entry).

Example:

zynx run src/main.zx -- --config prod.json --verbose

Exit Status​

  • 0 – Compilation and execution succeeded.
  • non-zero – Compilation failed, tests failed, or the program exited with a non-zero status.

Testing​

The test command compiles and runs test blocks embedded in your modules. See Testing for details.

zynx test [<path>] [--profile <profile>] [--target <triple>] [--filter <pattern>]
  • <path> – File or directory to test:
    • If a directory, all test-bearing modules in the workspace are included.
    • If omitted, runs all workspace tests.
  • --filter <pattern> – Only run tests whose names contain <pattern>.

Typical usage:

# Run all tests in the current project
zynx test

# Run tests in a specific file
zynx test src/math.zx

# Run only tests whose description contains "range"
zynx test --filter range

Formatting​

format​

Automatically format Zynx source files.

zynx format [<paths>...] [--check]
  • <paths> – One or more files or directories. If omitted, the entire workspace is formatted.
  • --check – Do not modify files; instead, exit non-zero if any file is not correctly formatted.

Examples:

# Format the whole workspace
zynx format

# Format a single file
zynx format src/main.zx

# CI-style check (no writes)
zynx format --check

Dynamic-Module Metadata​

meta​

Inspect or materialize embedded metadata for a shared library:

zynx meta [--embed=<header.zxh>] [--emit-blob=<out>] [--lib-path <dir>] <path>

Typical uses:

# Inspect embedded metadata
zynx meta plugins/libmath.so

# Embed metadata from a generated header into an existing shared lib
zynx meta --embed=build/libmath.zxh build/libmath.so

# Emit a metadata blob for linker-driven section injection
zynx meta --emit-blob=build/libmath.meta build/libmath.zxh

zynx meta reports:

  • the resolved module path
  • whether metadata came from an embedded section or trailer
  • the schema version
  • target and ABI information
  • exported members discovered from the metadata-backed module

For the full producer workflow, see Building Dynamic Modules.

Package and Module Management​

Zynx uses a single, unified package system driven by zynx.json and a lockfile. The CLI provides subcommands under zynx to manage dependencies, locking, fetching, and installation. See Package Management for the full model.

add​

Declare a new dependency in zynx.json.

zynx add <name> [--version <semver>] [--git <url>] [--kind <kind>] [--header <path>] [--source <path>...]
  • <name> – Logical module name.
  • --version <semver> – Requested version range (for example, ^1.2.0).
  • --git <url> – Git repository URL for git-sourced packages.
  • --kind <kind>:
    • package – Registry or git package (default).
    • ffi – Local C source/header module.
  • --header <path> – Primary header (for ffi modules).
  • --source <path> – One or more C source files (for ffi modules).

Examples:

# Add a registry package
zynx add io --version ^1.2.0

# Add a git-backed package
zynx add fmt --git https://github.com/org/fmt --version ^0.3.0

# Add an ffi module backed by local C sources
zynx add mylib --kind ffi --header include/mylib.h --source src/mylib.c

lock​

Resolve all dependencies and write/update zynx-lock.json.

zynx lock [--artifact <mode>]
  • --artifact <mode>:
    • auto (default) – Prefer matching binary artifacts; fall back to source.
    • source – Use source artifacts only.
    • binary – Require exact binary artifacts where possible.

fetch​

Download artifacts referenced in the lockfile into the local cache, without installing them into the project.

zynx fetch [--artifact <mode>]

Use this for offline builds or CI pipelines that want to prewarm caches.

install​

Materialize packages into modules/ for the current project.

zynx install [--artifact <mode>]

After a successful install, modules are available under:

modules/<name>/<target>/

where you typically find lib<name>.a, header shims, and metadata.

sync​

Synchronize manifest (zynx.json), lockfile, and installed modules.

zynx sync [--artifact <mode>]

This command:

  1. Resolves and locks (if needed).
  2. Fetches artifacts.
  3. Installs them into modules/.

publish​

Create a distribution bundle for a Zynx package.

zynx publish pack [--target <triple>] [--profile <profile>]
  • Without --target, produces a source package archive and release.json.
  • With --target and --profile, also produces a binary artifact for that exact target/profile pair.

Outputs are written under dist/. See Package Management for structure and metadata.

C Bindings and FFI​

bindgen​

Generate Zynx bindings from one or more C headers.

zynx bindgen -o <out.zx> [--clang-arg <arg>...] [--report <path>] <header...>
  • -o <out.zx> – Output .zx file containing generated declarations.
  • --clang-arg <arg> – Additional arguments passed to the embedded Clang parser (for example, -Iinclude, -DMODE=1).
  • --report <path> – Optional JSON or text report of skipped or partially translated C symbols.
  • <header...> – One or more header files to process.

For project-local C code, prefer ffi modules together with zynx sync, which will internally invoke bindgen and C compilation for you. See Native Bindings Workflow for details.

SDK and Toolchain Management​

SDKs encapsulate sysroots and toolchains for cross-compilation. The sdk subcommands are documented in Managing SDKs, summarized here for quick reference.

sdk add​

Install an SDK for a specific target.

zynx sdk add <triple> [--source <path/to/sdk.tar.gz>]
  • <triple> – Target triple (CLI form is typically arch-platform-abi, for example x86_64-linux-gnu).
  • --source <path> – Install from a local SDK archive.

Note: remote SDK fetching is not implemented yet; install currently requires --source.

SDKs are stored under:

~/.local/share/zynx/sdk/<triple>/

sdk list​

List installed SDKs.

zynx sdk list

sdk del​

Remove an installed SDK.

zynx sdk del <triple>

In zynx.json, you can choose between system and managed SDK modes; see Managing SDKs.

Language Server​

server​

Start the Zynx language server for editor integration (LSP).

zynx server [--stdio] [--socket <addr>]
  • --stdio – Run the server over standard input/output (default for LSP clients).
  • --socket <addr> – Listen on a TCP or Unix domain socket (for example, 127.0.0.1:7000 or unix:/tmp/zynx-lsp.sock).

Editors typically invoke this command indirectly via an LSP configuration.

For comment syntax and standardized documentation tags, see Comments.

Configuration Files​

zynx.json​

The central manifest for the project. Common sections:

  • name, version – Package identity.
  • zynx.target – Target configuration (architecture, platform, ABI, SDK mode).
  • zynx.registries – Package registries.
  • zynx.modules – Module dependency declarations.

zynx-lock.json​

The lockfile generated by zynx lock, zynx install, or zynx sync, capturing exact versions and artifacts used for reproducible builds.

Examples​

Create and run a new executable​

zynx new app --type executable
cd app
zynx run

Add a dependency and lock it​

zynx add io --version ^1.2.0
zynx lock --artifact auto
zynx install

Build for a different target using a managed SDK​

zynx sdk add linux-x86_64-gnu --source /path/to/sdk-linux-x86_64-gnu-v1.tar.gz
# configure zynx.json with target.arch/platform/abi and "sdk": "managed"
zynx build --target x86_64-linux-gnu --profile release

Conventions and Best Practices​

  • Prefer zynx test over custom test runners; tests live next to your code in test blocks.
  • Use zynx format (with --check in CI) to enforce a consistent style.
  • Manage dependencies exclusively via zynx add, zynx lock, zynx install, and zynx sync to keep zynx-lock.json authoritative.
  • Use sdk commands and managed SDK mode when cross-compiling or when you require a reproducible sysroot.

The CLI is designed to keep common workflows simple while supporting more advanced scenarios through subcommands and flags. Over time, new commands will follow the same naming and behavior conventions described here.