Command Reference

CForge provides a comprehensive set of commands for building, testing, and managing C/C++ projects.

Core Commands

Command	Description	Example
`init`	Create new project/workspace	`cforge init --template lib`
`build`	Build the project	`cforge build --config Release`
`clean`	Clean build artifacts	`cforge clean`
`run`	Run built executable	`cforge run -- arg1 arg2`
`test`	Execute tests (CTest integration)	`cforge test --filter MyTest`
`install`	Install project binaries	`cforge install --prefix /usr/local`
`flash`	Flash firmware to embedded target	`cforge flash --profile avr`
`deps`	Manage dependencies	`cforge deps add fmt`
`package`	Package project binaries	`cforge package --type zip`
`migrate`	Import CMakeLists.txt into cforge.toml	`cforge migrate --dry-run`
`hot`	Start a hot reload session	`cforge hot`

Developer Tools

Command	Description	Example
`fmt`	Format code with clang-format	`cforge fmt --check`
`lint`	Run clang-tidy static analysis	`cforge lint --fix`
`watch`	Watch files and rebuild on changes	`cforge watch --run`
`doc`	Generate documentation with Doxygen	`cforge doc --open`
`bench`	Run benchmarks	`cforge bench --filter BM_*`
`new`	Generate code from templates	`cforge new class MyClass`
`completions`	Generate shell completions	`cforge completions bash`

Dependency Management

All dependency operations use the unified cforge deps command:

Subcommand	Description	Example
`deps add`	Add a dependency to the project	`cforge deps add fmt@11.1.4`
`deps remove`	Remove a dependency	`cforge deps remove spdlog`
`deps search`	Search package registry	`cforge deps search json`
`deps info`	Show package details	`cforge deps info spdlog --versions`
`deps list`	List current dependencies	`cforge deps list`
`deps tree`	Display dependency tree	`cforge deps tree --depth 3`
`deps lock`	Manage lock file	`cforge deps lock --verify`
`deps update`	Update package registry	`cforge deps update`
`deps outdated`	Show outdated dependencies	`cforge deps outdated`

Project Management

Command	Description	Example
`ide`	Generate IDE project files	`cforge ide vscode`
`cache`	Manage binary cache	`cforge cache stats`
`circular`	Detect circular include dependencies	`cforge circular`

Utility Commands

Command	Description	Example
`version`	Display version information	`cforge version`
`upgrade`	Upgrade cforge to latest version	`cforge upgrade`
`doctor`	Diagnose environment issues	`cforge doctor`
`help`	Show help for commands	`cforge help build`

Global Options

All commands accept these global options:

Option	Description
`-v, --verbose`	Enable verbose output
`-q, --quiet`	Suppress non-essential output
`-c, --config`	Build configuration (Debug, Release, etc.)

Command Details

init

Create a new cforge project or workspace.

# Create a project in current directory
cforge init

# Create a named project
cforge init my_project

# Create with options
cforge init --name=my_project --cpp=20 --with-tests --with-git

# Create a workspace with projects
cforge init --workspace my_workspace --projects app lib tests

# Create an embedded bare-metal project
cforge init blink --template embedded

Options:

Option	Description
`--name`	Set project name
`--workspace`	Create a workspace
`--projects`	Create multiple projects
`--cpp`	Set C++ standard (11, 14, 17, 20, 23)
`--template`	Use template (exe, lib, header-only, embedded)
`--with-tests`	Add test infrastructure
`--with-git`	Initialize Git repository
`-y, --yes`	Accept all defaults non-interactively
`--license`	Add a LICENSE file (e.g., `--license MIT`)

Interactive mode: Running cforge init with no arguments or no project name launches an interactive prompt. Pass -y / --yes to skip prompts and accept defaults.

build

Build the project using CMake.

# Debug build (default)
cforge build

# Release build
cforge build --config Release

# Verbose output
cforge build -v

Output:

   Compiling my_app v1.0.0
   Compiling src/main.cpp
   Compiling src/utils.cpp
    Finished Debug target(s) in 2.34s

flash

Flash firmware to an embedded target using the flash command configured in a cross-compilation profile.

# Flash using a cross profile
cforge flash --profile avr

# Flash with specific config
cforge flash --profile esp32 --config Release

Options:

Option	Description
`-P, --profile <name>`	Cross-compilation profile to use (required)
`-j, --jobs <N>`	Number of parallel build jobs

The flash command requires a flash field in the cross profile configuration:

[cross.profile.avr]
flash = "avrdude -c arduino -p atmega328p -P /dev/ttyUSB0 -U flash:w:${PROJECT_NAME}.hex"

run

Build and run the executable.

# Run the default target
cforge run

# Pass arguments
cforge run -- --help --verbose

# Run specific target
cforge run my_target

test

Run tests using CTest.

# Run all tests
cforge test

# Filter tests
cforge test --filter "Unit*"

# Verbose output
cforge test -v

fmt

Format source code using clang-format.

# Format all files
cforge fmt

# Check formatting (no changes)
cforge fmt --check

# Format specific path
cforge fmt src/

Requirements: clang-format must be installed and available in PATH.

lint

Run static analysis using clang-tidy.

# Analyze all files
cforge lint

# Auto-fix issues
cforge lint --fix

# Specific checks
cforge lint --checks="modernize-*"

Requirements: clang-tidy must be installed and available in PATH.

watch

Watch for file changes and automatically rebuild.

# Watch and rebuild
cforge watch

# Watch and run after build
cforge watch --run

# Custom poll interval
cforge watch --interval 2

Press Ctrl+C to stop watching.

doc

Generate documentation using Doxygen.

# Generate documentation
cforge doc

# Initialize Doxyfile
cforge doc --init

# Generate and open in browser
cforge doc --open

Requirements: Doxygen must be installed and available in PATH.

bench

Run benchmark executables.

# Run all benchmarks
cforge bench

# Filter benchmarks
cforge bench --filter "BM_Sort*"

# Output formats
cforge bench --json
cforge bench --csv

# Skip build step
cforge bench --no-build

deps tree

Display the project's dependency tree.

# Show dependency tree
cforge deps tree

# Limit depth
cforge deps tree --depth 2

# Show all details
cforge deps tree -a

# Detect version conflicts; exit 1 if any found
cforge deps tree --check

# Export as Graphviz DOT format
cforge deps tree --format dot > deps.dot

Output:

my_app v1.0.0
├── fmt @ 10.1.0 (index)
├── spdlog @ 1.12.0 (index)
│   └── fmt @ 10.1.0 (index)
└── my_lib (project)

Dependencies: 2 index, 1 project

Options:

Option	Description
`--depth <N>`	Limit tree depth
`-a`	Show all details
`--check`	Detect version conflicts; exit 1 on conflict
`--format dot`	Output Graphviz DOT instead of tree text

new

Generate code from templates.

# Create a class
cforge new class MyClass

# Create a header file
cforge new header utils

# Create with namespace
cforge new class MyClass -n myapp

# Create a test file
cforge new test MyClassTest

# Available templates: class, header, struct, interface, test, main

completions

Generate shell completion scripts.

# Bash
cforge completions bash > ~/.local/share/bash-completion/completions/cforge

# Zsh
cforge completions zsh > ~/.zfunc/_cforge

# PowerShell
cforge completions powershell >> $PROFILE

# Fish
cforge completions fish > ~/.config/fish/completions/cforge.fish

ide

Generate IDE project files.

# VS Code
cforge ide vscode

# CLion
cforge ide clion

# Visual Studio
cforge ide vs

# Xcode (macOS only)
cforge ide xcode

deps

Unified dependency management command. All dependency operations use cforge deps <subcommand>.

# Show all deps subcommands
cforge deps --help

# List current dependencies
cforge deps list

# Check for outdated dependencies
cforge deps outdated

# Update package registry
cforge deps update

deps search

Search the cforge package registry.

# Search for packages
cforge deps search json

# Search for logging libraries
cforge deps search log

deps info

Get detailed information about a package.

# Show package info
cforge deps info spdlog

# Show available versions
cforge deps info fmt --versions

deps add / deps remove

Manage dependencies in cforge.toml.

# Add from registry (default)
cforge deps add fmt

# Add with specific version
cforge deps add fmt@11.1.4

# Add with features
cforge deps add spdlog --features async

# Add from Git
cforge deps add mylib --git https://github.com/user/mylib --tag v1.0

# Add from vcpkg
cforge deps add boost --vcpkg

# Remove a dependency
cforge deps remove spdlog

Options:

Option	Description
`@version`	Specify version (e.g., `fmt@11.1.4`)
`--git <url>`	Add as Git dependency
`--tag <tag>`	Git tag (with --git)
`--branch <name>`	Git branch (with --git)
`--vcpkg`	Add as vcpkg package
`--features <list>`	Comma-separated features
`--header-only`	Mark as header-only library

deps outdated

Check for dependencies with newer versions available.

# Show outdated dependencies
cforge deps outdated

Output:

Package         Current    Latest     Source
--------------  ---------  ---------  ------
fmt             11.1.4     12.1.0     index
spdlog          1.12.0     1.15.0     index

Found 2 outdated package(s)

deps lock

Manage dependency lock file for reproducible builds.

# Generate/update lock file
cforge deps lock

# Verify dependencies match lock
cforge deps lock --verify

# Force regeneration
cforge deps lock --force

# Remove lock file
cforge deps lock --clean

package

Create distributable packages.

# Create a ZIP package
cforge package --type zip

# Create installer (platform-specific)
cforge package --type installer

list

List project information.

# List build variants
cforge list variants

# List targets
cforge list targets

# List configurations
cforge list configs

migrate

Import an existing CMakeLists.txt into a cforge.toml. Alias: cforge import.

# Preview changes without writing any files
cforge migrate --dry-run
cforge migrate -n

# Import and keep a backup of CMakeLists.txt
cforge migrate --backup
cforge migrate -b

# Write the generated config to a custom path
cforge migrate --output path/to/cforge.toml
cforge migrate -o path/to/cforge.toml

# Migrate a project in a different directory
cforge migrate path/to/project

Options:

Option	Description
`-n, --dry-run`	Print what would be written; make no changes
`-b, --backup`	Back up `CMakeLists.txt` before migrating
`-o, --output <path>`	Custom output path for `cforge.toml`

See Advanced Topics for limitations.

hot

Start a hot reload session that recompiles and reloads changed translation units without restarting the process. Alias: cforge hot-reload.

# Start hot reload (requires [hot_reload] section in cforge.toml)
cforge hot

cforge.toml configuration:

[hot_reload]
enabled = true
watch_dirs = ["src", "include"]
exclude = ["src/generated"]

See Advanced Topics for the runtime API and full configuration reference.

Core Commands​

Developer Tools​

Dependency Management​

Project Management​

Utility Commands​

Global Options​

Command Details​

init​

build​

flash​

run​

test​

fmt​

lint​

watch​

doc​

bench​

deps tree​

new​

completions​

ide​

deps​

deps search​

deps info​

deps add / deps remove​

deps outdated​

deps lock​

package​

list​

migrate​

hot​

Core Commands

Developer Tools

Dependency Management

Project Management

Utility Commands

Global Options

Command Details

init

build

flash

run

test

fmt

lint

watch

doc

bench

deps tree

new

completions

ide

deps

deps search

deps info

deps add / deps remove

deps outdated

deps lock

package

list

migrate

hot