CLI Starter Template - C23 + Zig 🚀

A modern C23 CLI application starter template with Zig build system

Use this template • View Demo • Report Bug

✨ Features

• 🚀 Modern C23 - Latest C standard with Aro compiler
• ⚡ Zig Build System - Fast, reliable builds with cross-compilation
• 🏗️ Well-Structured - Organized project layout ready for growth
• 🧪 Testing Included - Test framework with examples
• 🎨 Smart CLI - Colored output, help text, argument parsing
• 🖼️ TUI Support - NCurses integration for interactive terminal UIs
• 🔧 Configuration - Layered config system (file → env → args)
• 📦 Minimal Dependencies - Only Zig, libc, and ncurses
• 🤖 CI/CD Ready - GitHub Actions workflow included
• 🔄 Conditional Runners - Uses self-hosted runners for template repo, GitHub-hosted for derived repos
• ⚡ Caching - Speeds up builds by caching Zig dependencies and build artifacts
• 🔒 Release Gating - Ensures releases only happen on tags in main branch
• 🛡️ Security Scanning - CodeQL integration for vulnerability detection
• 📦 Artifact Management - Unique artifact naming to avoid collisions
• 🏷️ Version Pinning - Pinned GitHub Actions versions for reproducibility
• 🚫 Concurrency Control - Cancels redundant CI runs on same branch
• 📊 Dynamic Binary Naming - Extracts binary name from build.zig.zon
• 🧹 Template Cleanup - Automated cleanup of template-specific files and placeholders
• 📚 OpenCLI Compliant - Standardized CLI behavior
• 🔄 Dependency Updates - Automated updates with Dependabot/Renovate
• 📝 Pre-commit Hooks - Code quality enforcement before commits
• 🐳 Devcontainer Support - Consistent development environments
• 📋 Comprehensive Documentation - Detailed guides and examples

🎯 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 & Run

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

# Build (with TUI support)
zig build -Doptimize=ReleaseSafe

# Build without TUI (if ncurses is not available)
zig build -Doptimize=ReleaseSafe -Denable-tui=false

# Run
./zig-out/bin/YOUR-REPO --help

📖 What's Included

Project Structure

your-cli/
├── src/
│   ├── main.c              # Entry point
│   ├── core/               # Core functionality
│   │   ├── config.c/h      # Configuration
│   │   ├── error.c/h       # Error handling
│   │   └── types.h         # Type definitions
│   ├── cli/                # CLI interface
│   │   ├── args.c/h        # Argument parsing
│   │   └── help.c/h        # Help text
│   ├── io/                 # Input/Output
│   └── utils/              # Utilities
├── test/                   # Test suite
├── build.zig               # Build config
└── opencli.json            # CLI specification

Example Commands

The template includes working examples:

# 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: 1.0.0
Build: Jul 27 2025 13:16:11

# Interactive TUI menu
$ myapp menu
# Opens an ncurses-based interactive menu

🛠️ Customization Guide

1. After Creating Your Repo

The template automatically:

• ✅ Replaces myapp with your project name
• ✅ Updates all references and metadata
• ✅ Preserves template structure
• ✅ Removes template-specific files
• ✅ Commits the changes

Check the Actions tab to see progress.

2. Add Your Commands

Edit src/main.c:

if (strcmp(command, "deploy") == 0) {
    printf("Deploying application...\n");
    // Your deployment logic
    return APP_SUCCESS;
}

3. Update Help Text

Edit src/cli/help.c to describe your commands.

4. Add Source Files

1. Create your .c file in src/
2. Add to build.zig:

const c_sources = [_][]const u8{
    // ... existing files ...
    "src/features/deploy.c",  // Your new file
};

🧪 Development

Prerequisites

• Zig (master branch) - Install via zvm
• C compiler - For system libraries
• NCurses - For TUI support
  • Ubuntu/Debian: sudo apt-get install libncurses-dev
  • macOS: brew install ncurses
  • Fedora: sudo dnf install ncurses-devel

Development Environment

This template provides several tools to enhance your development experience:

• Devcontainer Support - Pre-configured development environment with all dependencies
• VS Code Settings - Opinionated settings for C/Zig development
• Pre-commit Hooks - Automated code quality checks before commits
• Tasks Configuration - Predefined build and test tasks for VS Code
• Debug Configuration - Ready-to-use debugging setup for VS Code

Commands

# Build
zig build                    # Debug build
zig build -Doptimize=ReleaseSafe  # Release build

# Test
zig build test              # Run all tests

# Clean
zig build clean             # Remove build artifacts

# Format
zig fmt build.zig          # Format build file

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

📚 Documentation

Getting Started

• 📖 Using This Template - Detailed setup guide
• 🚀 Quick Start Guide - Get up and running quickly
• 🔧 Installation - Platform-specific instructions

Developer Resources

• 🏗️ Architecture Overview - System design and module structure
• ⚡ Zig Primer for C Developers - Understanding the build system
• 🤝 Contributing Guide - How to contribute to the project
• 🧪 Advanced Usage Examples - Piping, scripting, and integration

Examples & 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

🤔 Why This Stack?

• C23 - Latest features: typeof, _BitInt, better type safety
• Zig Build - Superior to Make/CMake, built-in cross-compilation
• Aro Compiler - Better C23 support than most system compilers
• Minimal Dependencies - Just Zig and libc, no complex toolchains

🆘 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 with ❤️ by the open source community