vix new

vix new creates a new Vix project.

Use it when you want to start a new application, create a reusable header-only library, or initialize a Vix project in an existing folder.

Usage

vix new <name|path> [options]

Examples

Create a new application named api:

vix new api

Create a project in the current directory:

vix new .

Create a header-only library:

vix new tree --lib

Create a project inside another directory:

vix new blog -d ./projects

Overwrite an existing directory:

vix new api --force

What it creates

For an application, vix new generates a ready-to-run Vix project with:

• a CMake project
• source structure
• config files
• a vix.json manifest
• default project tasks
• an empty dependency list
• an executable target matching the project name

For a header-only library, vix new generates:

• a CMake project
• an include/ directory
• a generated header
• a tests/ directory
• an examples/ directory
• a vix.json package manifest
• an interface CMake target
• an alias target in the form name::name

Application workflow

Create the project:

vix new api

Enter the project:

cd api/

Build the application:

vix build

Run the application:

vix run

Or start development mode:

vix dev

Library workflow

Create a header-only library:

vix new tree --lib

Enter the project:

cd tree/

Build the generated library project:

vix build --build-target all

Enable tests:

vix build --build-target all -- -Dtree_BUILD_TESTS=ON

Run tests:

vix tests

For header-only libraries, vix build alone may not be the right command because vix build builds the main project target by default.

For example, inside a project named tree, vix build tries to build the target named tree.

A header-only library usually exposes an interface target, not a normal executable named tree.

Use this instead:

vix build --build-target all

Application project

By default, vix new creates an application:

vix new api

This is equivalent to:

vix new api --app

Use this when you want to build an executable application, API server, backend service, tool, or demo.

The generated application can normally be built with:

vix build

Then run with:

vix run

Or launched in development mode with:

vix dev

Library project

Use --lib when you want to create a header-only library package:

vix new tree --lib

This is useful when you want to create reusable C++ code that can later be packaged and shared.

The generated library is header-only, so its main CMake target is an interface target.

Build it with:

vix build --build-target all

Tests are disabled by default for generated header-only libraries.

Enable tests with:

vix build --build-target all -- -Dtree_BUILD_TESTS=ON

Then run:

vix tests

Replace tree with your project name:

vix build --build-target all -- -Dmy_lib_BUILD_TESTS=ON

Why libraries use --build-target all

vix build builds the main project target by default.

The default target name is the project directory name.

For an application named api, this works because the generated CMake project creates an executable target named api.

For a header-only library named tree, the project creates an interface library target, tests, and examples.

Because header-only libraries do not produce a normal binary target named like an app, use:

vix build --build-target all

This asks CMake and Ninja to build all generated targets that are enabled in the current configuration.

Initialize the current directory

Use . to create the project in the current folder:

vix new .

This is useful when you already created the repository manually.

Example:

mkdir api
cd api
git init
vix new .

Create inside another directory

Use -d or --dir to choose the base directory where the project should be created:

vix new blog -d ./projects

This creates:

./projects/blog

Overwrite an existing directory

By default, Vix avoids overwriting existing project files.

Use --force only when you intentionally want to overwrite an existing directory:

vix new api --force

Use this carefully because existing files may be replaced.

Options

Option	Description
--app	Generate an application project. This is the default.
--lib	Generate a header-only library project.
-d, --dir <path>	Base directory for project creation.
--force	Overwrite an existing directory.
-h, --help	Show command help.

Environment variables

Variable	Description
VIX_NONINTERACTIVE=1	Disable interactive prompts.
CI=1	Disable interactive prompts in CI environments.

Use non-interactive mode in scripts and CI pipelines:

VIX_NONINTERACTIVE=1 vix new api

Create a library in non-interactive mode:

VIX_NONINTERACTIVE=1 vix new tree --lib

Generated manifest

A new project includes a vix.json manifest.

The manifest describes the project, its dependencies, and reusable tasks.

For an application, the manifest is used for tasks such as development, testing, checking, formatting, and release workflows.

For a library, the manifest is used for package metadata and dependencies.

The exact generated content may evolve with Vix versions, but the role stays the same: vix.json is the project manifest.

Generated application structure

A generated application has a structure similar to:

api/
├── CMakeLists.txt
├── CMakePresets.json
├── README.md
├── api.vix
├── vix.json
├── .env
├── .env.example
├── src/
│   └── main.cpp
└── tests/
    └── test_basic.cpp

The application target matches the project name.

For example:

vix new api
cd api/
vix build

This builds the api target.

Generated library structure

A generated header-only library has a structure similar to:

tree/
├── CMakeLists.txt
├── CMakePresets.json
├── README.md
├── tree.vix
├── vix.json
├── include/
│   └── tree/
│       └── tree.hpp
├── examples/
│   ├── CMakeLists.txt
│   └── basic.cpp
└── tests/
    └── test_basic.cpp

Build it with:

vix build --build-target all

Enable tests with:

vix build --build-target all -- -Dtree_BUILD_TESTS=ON

Run tests with:

vix tests

Build behavior

vix build does not always mean “build everything”.

By default, it builds the main project target.

For applications, this is usually what you want:

vix build

For header-only libraries, prefer:

vix build --build-target all

This matches the build behavior documented in the vix build guide.

After project creation

For an application, the usual next commands are:

cd api/
vix build
vix run

For a library, the usual next commands are:

cd tree/
vix build --build-target all
vix build --build-target all -- -Dtree_BUILD_TESTS=ON
vix tests

Use:

vix install

when your project has dependencies that must be installed from vix.lock.

Use:

vix check

when you want to validate the project.

Common mistakes

Running commands outside the project

Wrong:

vix new api
vix dev

Correct:

vix new api
cd api/
vix dev

After creating a project, enter the generated directory before running project commands.

Using vix build directly in a header-only library

Wrong:

vix new tree --lib
cd tree/
vix build

This may fail because vix build tries to build the main target named after the project directory.

Correct:

vix new tree --lib
cd tree/
vix build --build-target all

Running library tests before enabling them

Wrong:

vix new tree --lib
cd tree/
vix build --build-target all
vix tests

Correct:

vix new tree --lib
cd tree/
vix build --build-target all -- -Dtree_BUILD_TESTS=ON
vix tests

Tests for generated header-only libraries are disabled by default.

Creating a library when you need an app

This creates a library:

vix new api --lib

For a backend service or executable app, use the default:

vix new api

Using --force too early

Avoid this unless you really want to overwrite files:

vix new api --force

Prefer creating a clean folder first.

Troubleshooting

Build target not found

If you see an error like:

✖ Build target not found
target: tree
hint: This project does not define a CMake target named 'tree'.

You are probably inside a generated header-only library.

Use:

vix build --build-target all

No tests available

If you see:

✖ No tests available.
➜ Tests were not generated in the existing build directory.

Enable tests first:

vix build --build-target all -- -Dtree_BUILD_TESTS=ON

Then run:

vix tests

You created a project but commands do not work

Make sure you entered the generated directory:

cd api/

or:

cd tree/

You need raw build details

Use:

vix build --cmake-verbose

or inspect:

cat build-ninja/build.log

When to use vix new

Use vix new when:

• starting a new Vix application
• creating a reusable Vix header-only library package
• initializing an existing empty repository
• preparing a project for dependency management
• creating a project that should work with vix dev, vix run, vix build, and vix check

Related commands

Command	Purpose
vix build	Build the project
vix run	Build and run the app
vix dev	Run the app with reload
vix tests	Run tests
vix check	Validate the project
vix install	Install project dependencies
vix task	Run generated or custom project tasks
vix add	Add dependencies

Next step

Continue with building projects.

Open the vix build guide.