C23 TUI + CLI Starter Template - Zig + ncurses

A ready-to-use C23 starter for command-line tools and terminal UIs. Click Use this template, run the cleanup script, and you have a cross-compiling C project with argument parsing, an optional ncurses TUI, end-to-end tests, and a GitHub Actions CI/CD scaffold.

Use this template • View Demo • Report Bug

---

Highlights

• Modern C23, no compiler wrangling - The latest C standard through Zig's bundled toolchain.
• CLI and TUI in one - Argument parsing and colored output, plus an optional ncurses/PDCurses interface (-Denable-tui=true).
• Fast, cross-compiling builds - The Zig build system replaces Make/CMake and targets other platforms out of the box.
• Tested end to end - Three test layers: in-process unit tests, C23 CLI contract tests, and PTY-driven terminal scenarios for real CLI/TUI behavior.
• CI/CD scaffold included - GitHub Actions for builds, tests, linting, release artifacts, and optional security checks.
• OpenCLI-style contract - A checked-in machine-readable CLI contract your tool can print on demand with myapp opencli.

Quick Start

Create your project

Option 1: GitHub UI

1. Click "Use this template"
2. Name your repository
3. Click "Create repository"

Option 2: GitHub CLI

gh repo create my-cli \
  --template sammyjoyce/c23-cli-template \
  --public \
  --clone

Build and run

# Clone your new repo
git clone https://github.com/YOU/YOUR-REPO
cd YOUR-REPO

# Build the default CLI starter
zig build -Doptimize=ReleaseSafe

# Build with the optional ncurses/PDCurses TUI
zig build -Doptimize=ReleaseSafe -Denable-tui=true

# Run (the default binary is named `myapp`; override with `-Dapp-name=`)
./zig-out/bin/myapp --help

Example Commands

The template ships with working commands so you can confirm the build immediately:

# Greeting command
$ myapp hello
Hello, World!

$ myapp hello Alice
Hello, Alice!

# Echo command
$ myapp echo Hello from CLI
Hello from CLI

# Info command
$ myapp info
Application: myapp
Version: 0.1.0
Build: omitted

$ myapp --json info
{"format_version":"1.0", ...}

$ myapp doctor
myapp doctor
  binary        ok (myapp 0.1.0)

$ myapp opencli
{
  "opencli": "0.1",
  ...
}

# Interactive TUI showcase
$ zig build -Denable-tui=true run -- menu
# Opens ncurses menus, dialogs, panels, and progress bars

Project Layout

See docs/ARCHITECTURE.md#module-map for what each directory under src/ owns, plus the representative public functions in each module.

Customize It

1. After creating your repo

Run the template cleanup workflow or local setup script. It will:

• Replace myapp with your project name
• Update all references and metadata
• Preserve the template structure
• Remove template-specific files
• Commit the changes

Check the Actions tab to see progress.

2. CI runner selection

Generated repositories default to GitHub-hosted runners so the cleanup workflow and first CI run work without extra infrastructure. To opt into Namespace or another self-hosted fleet, configure CI_LINUX_RUNNER, CI_MACOS_RUNNER, and CI_WINDOWS_RUNNER as described in Using This Template.

3. Add a command

Commands are table-driven. Write a handler, register it in src/cli/commands.c, regenerate opencli.json, add a contract test, and add the new file to base_sources in build.zig. The full five-step flow is in examples/adding-a-command.md.

Help text and the OpenCLI contract update automatically from the command table; you do not edit help.c by hand.

For TUI screens, see examples/custom-tui.md.

Develop

Prerequisites

Default CLI builds need only:

• Zig 0.16.0 - the version pinned by this template; install via zvm or your package manager
• A system C toolchain - for libc and platform libraries

Optional TUI builds (-Denable-tui=true) also need curses development files:

• Ubuntu/Debian: sudo apt-get install pkg-config libncurses-dev
• macOS: brew install pkg-config ncurses
• Fedora: sudo dnf install pkg-config ncurses-devel
• Windows: vcpkg install pdcurses:x64-windows

Optional PTY-backed TUI scenarios need libghostty-vt development files discoverable through pkg-config, or the Nix dev shell.

Development environment

This template provides several tools to enhance your development experience:

• Devcontainer Support - Pre-configured non-Nix development environment with Zig and platform packages
• Optional Nix Dev Shell - Convenience shell with Zig, C tooling, curses, Ghostty VT, and markdown lint tooling
• CI Quality Checks - Automated build, test, lint, security, and release checks without requiring Nix by default

Commands

# Build
zig build                                  # Debug build
zig build -Doptimize=ReleaseSafe           # Release build
zig build -Denable-tui=true                # Build with the ncurses/PDCurses TUI
zig build -Denable-tui=true -Dcurses-prefix="$(brew --prefix ncurses)"  # macOS/Homebrew TUI
zig build tui-menu-lib                     # Build the reusable TUI menu static library

# Test
zig build unit-test                        # In-process unit tests
zig build test                             # Unit tests + CLI contract tests
zig build terminal-test                    # Unit + CLI tests; PTY/TUI skipped unless TUI + backend are available
zig build -Denable-tui=true terminal-test  # TUI build; PTY scenarios run if libghostty-vt is found
zig build -Denable-tui=true -Dterminal-backend=ghostty terminal-test  # Require Ghostty VT
zig build -Dterminal-backend=none terminal-test  # Never run PTY/TUI scenarios
zig build check                            # fmt-check + tests (the CI gate)

# Format
zig build fmt                              # Format build.zig (Zig formatter; C uses clang-format via pre-commit + CI)

# Clean
zig build clean                            # Remove zig-out and .zig-cache

Configuration

Your app supports config from multiple sources:

1. CLI arguments (highest priority)
2. Environment variables
3. Config file (~/.config/yourapp/config.json)
4. Defaults

Config files are flat JSON objects with boolean keys for debug, quiet, verbose, no_color, json_output, and plain_output.

Everything Included

The template wires up far more than the starter code. The full inventory:

Language and build

• Modern C23 - Latest C standard through Zig's bundled C toolchain
• Zig Build System - Fast, reliable builds with cross-compilation
• Minimal Dependencies - Zig and libc by default; curses only for TUI builds
• Configurable binary name - Set via -Dapp-name= (default myapp)

CLI and TUI

• Smart CLI - Colored output, help text, argument parsing
• TUI Support - ncurses/PDCurses integration for interactive terminal UIs
• Reusable TUI Menu - Optional tui-menu-lib target for downstream C apps
• Configuration - Layered config system (file → env → args)
• OpenCLI-style contract - Standardized CLI metadata under myapp opencli
• Live CLI Contract - myapp opencli prints the checked-in OpenCLI spec

Testing and quality

• Testing Included - In-process unit tests, C23 CLI contract tests, and optional PTY terminal scenarios for CLI/TUI flows
• Markdown Linting - Documentation checks in local tooling and CI

CI/CD and releases

• CI/CD Ready - GitHub Actions workflow included
• Caching - Speeds up builds by caching Zig dependencies
• Concurrency Control - Cancels redundant CI runs on same branch
• Release Gating - Ensures releases only happen on version tags after required quality jobs pass
• Artifact Management - Unique artifact naming to avoid collisions
• Security Scanning - Gitleaks, CodeQL, OpenSSF Scorecard, and SBOM generation scaffolds
• Dependency Updates - Automated updates with Dependabot/Renovate

Project and developer experience

• Well-Structured - Organized project layout ready for growth
• Template Cleanup - Scripted cleanup of template-specific files and placeholders
• Devcontainer Support - Consistent development environments
• Comprehensive Documentation - Detailed guides and examples

Why this stack?

• C23 - Current standard mode with nullptr, attributes, and other portable language improvements
• Zig Build - Superior to Make/CMake, built-in cross-compilation
• ncurses/PDCurses - Proven terminal UI primitives with a small wrapper API
• Minimal Dependencies - Zig and libc by default, with curses behind -Denable-tui=true

Documentation

Start with Using This Template for the full setup guide.

Developer resources

• Architecture Overview - System design and module structure
• Public Contracts - Supported CLI and TUI seams
• Zig Primer for C Developers - Understanding the build system
• Testing CLI And TUI Behavior - End-to-end terminal scenario tests
• Contributing Guide - How to contribute to the project
• Advanced Usage Examples - Piping, scripting, and integration

Examples and demos

• Adding Commands - Extend the CLI
• Custom TUI Components - Build interactive interfaces
• Configuration Guide - Config file examples
• Demo Gallery - Animated demonstrations

Project information

• Security Policy - Reporting vulnerabilities
• Code of Conduct - Community guidelines
• Changelog - Version history
• License - MIT License

Getting Help

Template issues

For problems with the template itself:

• Check existing issues
• Create a new issue
• Read template support

Your project issues

For issues with your generated project:

• Use your own repository's issues
• Check Zig documentation
• See C23 reference

Projects using this template

Using this template? Add your project!

• Example CLI - Description
• Your project here!

License

This template is MIT licensed. See LICENSE for details.

When you use this template, you can choose any license for your project.

---

Ready to build your CLI app?

Made by the open source community