Installing vmblu ​

vmblu uses a model to describe the architecture of an application. The CLI creates and generates vmblu projects, while the optional VS Code extension lets you inspect and edit their models visually.

You can start with a coding agent or initialize a project yourself.

Requirements ​

  • Node.js 18 or newer, including npm.
  • Visual Studio Code if you want to use the graphical vmblu editor.
  • A supported coding agent, such as Codex or Claude, if you want agent-assisted development.

You do not need an existing JavaScript or TypeScript project. vmblu init creates the project structure and its package.json for you.

Quick start with a coding agent ​

vmblu can install user-level guidance that teaches a supported coding agent how to work with vmblu projects. See the available integrations:

bash
npx @vizualmodel/vmblu-cli agent list

Before installing support, you can preview which files will be copied:

bash
npx @vizualmodel/vmblu-cli agent install codex --dry-run

Install support for Codex:

bash
npx @vizualmodel/vmblu-cli agent install codex

For Claude, replace codex with claude. The command installs files in the agent's directory under your user home folder. It refuses to overwrite existing files unless you explicitly add --force.

Start a new agent session if necessary, then use a prompt such as:

text
Use vmblu to create a new application in ./my-new-application.
Initialize the project if necessary and read .vmblu/vmblu.prompt.md
before making implementation changes.

With vmblu support installed, the agent should initialize the project, read its project-specific instructions, install its dependencies, and use the root .blu entrypoint to locate the model.

Quick start manually ​

Initialize a new project with a one-off invocation of the CLI:

bash
npx @vizualmodel/vmblu-cli init my-new-application
cd my-new-application
npm install

The initialization command writes the project dependencies to package.json; the separate npm install command installs them.

The generated project has this structure:

text
my-new-application/
  my-new-application.blu
  package.json
  model/
    my-new-application.mod.blu
    my-new-application.mod.viz
  nodes/
  .vmblu/
    vmblu.prompt.md
    overrides/
    cache/
    logs/

The root .blu file is an entrypoint that points to the model:

json
{
  "kind": "vmblu.entrypoint",
  "version": 1,
  "model": "model/my-new-application.mod.blu"
}

Open my-new-application.blu in the vmblu editor. You can verify that the CLI is available with:

bash
npx @vizualmodel/vmblu-cli --help

The generated package.json also provides npm scripts for profiling the model, generating the application, and generating its capability manifest. The tutorial continues from the initialized project.

Install the VS Code editor ​

Install vmblu from the VS Code Marketplace, or install it from within VS Code:

  1. Open the Extensions view.
  2. Search for vmblu.
  3. Select the extension published by Vizual Model and choose Install.

The editor is optional for CLI and agent workflows, but it gives you a visual way to inspect and change the architecture. Open the root .blu entrypoint, rather than a generated application file.

Add vmblu to an existing project ​

Install the runtime as an application dependency and the CLI as a development dependency:

bash
npm install @vizualmodel/vmblu-runtime
npm install --save-dev @vizualmodel/vmblu-cli

Preview the files that initialization would add, then initialize the current directory:

bash
npx @vizualmodel/vmblu-cli init . --dry-run
npx @vizualmodel/vmblu-cli init .

Without --force, initialization preserves files that already exist, including package.json. Do not use --force unless you have reviewed the affected files and intend to replace them.

Version compatibility ​

vmblu versions use the form major.minor.patch. The major.minor pair is the compatibility family: for example, all 1.11.x releases belong to the 1.11 family. Keep the editor, CLI, runtime, and model schema in the same family. Crossing a family boundary requires migration rather than a patch-level update.

By default, vmblu init uses the schema version supplied by the CLI that runs the command.

Troubleshooting ​

The vmblu command is not found ​

The short vmblu command is available inside the generated npm scripts. At a shell prompt, use the explicit one-off form shown in this guide:

bash
npx @vizualmodel/vmblu-cli --help

PowerShell blocks npm or npx ​

On Windows, an execution policy can prevent PowerShell's npm.ps1 or npx.ps1 shim from running. Use the Windows command shims instead:

powershell
npx.cmd @vizualmodel/vmblu-cli init my-new-application
cd my-new-application
npm.cmd install

Agent support files already exist ​

Run the installation with --dry-run to inspect its destinations. Use --force only when you intentionally want to replace the installed support with the version shipped by the current CLI.

Next steps ​