CLI Reference

veloxc is the command-line tool that scaffolds, builds, lints, and runs Velox applications — install it with cargo install veloxc. Every command on this page is verified against the CLI source; veloxc --help lists them, and veloxc <subcommand> --help is the authoritative flag reference.

Command summary

veloxc init <name>

Creates a complete, working project — not a stub. The scaffold is a todo list app with components, assets, and a build script, so everything is on screen from the first veloxc dev.

The scaffold writes:

<name>/
├── Cargo.toml          # velox-core/dom/style, velox-renderer (skia-native), veloxc build-dep
├── build.rs            # compiles src/App.vx + imports via veloxc::build_cmd
├── README.md
├── assets/
│   ├── velox-logo.svg
│   └── velox-logo.png
└── src/
    ├── main.rs
    ├── App.vx
    └── components/
        ├── Todos.vx  TodoInput.vx  TodoItem.vx
        └── Confirm.vx  Modal.vx

Dependency resolution, in order: --local <path> wins; otherwise the CLI walks up from the current directory looking for a Velox workspace (a velox-core/Cargo.toml), or uses the checkout the CLI itself was built in — either way the scaffold gets relative path dependencies. When no workspace is found it falls back to git dependencies pinned to the commit the CLI was built at, so a scaffold always compiles against tested code.

veloxc init counter

✅ Created Velox project: counter
📦 To get started:
   cd counter
   veloxc dev
   veloxc build
   veloxc run
✅ Created Velox project at: counter

📖 Next steps:
   cd counter
   veloxc dev

The scaffold writes veloxc commands in its next-steps banner (line 21 of its README.md). The CLI and the scaffold are consistent. The installed-CLI case (cargo install veloxc) is covered by the version = "..." dependency branch: generate_cargo_toml detects rev == "unknown" (the VELOX_GIT_REV_FALLBACK sentinel) and emits plain version pins instead of an unresolvable rev = "unknown", which cargo rejects (revspec 'unknown' not found).

veloxc build [input]

Two modes, chosen by whether a positional input is given:

The component compile is recursive: every component imported from <script setup> is parsed and compiled, one .rs file per component in the output directory. The root component is wrapped in a pub mod block (so include! in main.rs works), imported components are declared with #[path] attributes, and child-component styles are merged into the root stylesheet — scoped ones stay scoped. When run from a build script, cargo:rerun-if-changed directives are emitted for every .vx file read, so Cargo re-runs the build script when a component changes.

veloxc build src/App.vx -o target/velox-gen

[velox] Generated: target/velox-gen/app.rs
ℹ️  The generated .rs file is source code, not an executable.

veloxc run

Builds first when --release is passed, then runs the project. The app inherits your terminal.

veloxc run            # debug build (existing binary is reused by cargo)
veloxc run --release  # builds in release mode first, then runs

veloxc dev

Starts the dev server: file watching, rebuild on save, and the HMR channel that tells the running app to restart itself.

There is no positional directory argument — the watch root is passed with --watch/-w. The server watches src/ and assets/ (roots that do not exist are skipped), binds 127.0.0.1:31313 for hot reload, and serves keyboard commands on stdin.

veloxc dev

The full workflow — what updates live, what restarts, the banner, the shortcuts, and inotify troubleshooting — is on Dev Workflow & HMR.

veloxc lint [target] [--fix]

Checks .vx files for issues. Three kinds of findings:

The target defaults to src and may be a single .vx file or a directory (walked recursively, .vx files only). CSS warnings are reported by file and rule index; unknown declarations are not flagged — the cascade filters those out silently, so vendor prefixes and custom properties stay quiet.

--fix applies the two auto-fixes — trailing whitespace on every line, and exactly one final newline. Parse errors are not auto-fixable: non-parseable files are reported as errors and left untouched.

veloxc lint src/App.vx
veloxc lint            # every .vx under src/
veloxc lint --fix      # …and fix whitespace issues

📊 Lint results: 8 files, 0 errors

veloxc add component <name>

Generates a new, self-contained component .vx file in src/components/. The name is normalized: my-counter, side_bar, and My Component all produce a PascalCase struct (SideBar), a matching PascalCase filename (SideBar.vx), and a kebab-case CSS class (side-bar). The name must start with a letter, and the file is never overwritten.

Slot names are folded to the form the SFC parser registers — footerBar and main_content are scaffolded as footer-bar and main-content — and default cannot be requested explicitly.

veloxc add component side-bar --slots header,footer

✅ Created component: src/components/SideBar.vx
   Slots: default, header, footer
   Fill one from a parent: <SideBar><template v-slot:header>…</template></SideBar>
   (shorthand: <SideBar><template #header>…</template></SideBar>)
   Import it from a parent component, e.g.:
   import SideBar from './components/SideBar.vx'

veloxc version

veloxc version

velox 0.1.2
Edition: 2021
Platform: Linux

Note: Edition: 2021 is a fixed string from the CLI itself, not read from your project’s manifest.

Exit codes

A failing veloxc lint exits non-zero, so it drops straight into CI: veloxc lint src/ as a step fails the pipeline on the first parse error.

Environment variables

See also

• Dev Workflow & HMR — veloxc dev end to end.
• Renderer — the HMR channel and rendering backends the CLI wires up.
• Template Syntax — what veloxc lint checks and what veloxc build compiles.