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