CLI Reference

---

FULL LIFECYCLE

Scaffold. Develop. Deploy.
One CLI, zero friction.

The Vurb CLI manages the full lifecycle of an MCP server: scaffolding, HMR development, governance lockfiles, deployment, and runtime inspection.

Installation

npx vurb --help

Or install globally:

npm install -g @vurb/core
vurb --help

---

Commands Overview

vurb create

Scaffold a new Vurb server with interactive wizard or CLI flags.

vurb dev

HMR dev server with auto-reload on file changes.

vurb lock

Generate or verify a capability lockfile for CI governance.

vurb deploy

Bundle, compress & deploy to Vinkius Edge. Under 40 seconds.

vurb remote

Manage remote cloud configuration stored in .vurbrc.

vurb inspect

Real-time TUI dashboard for monitoring your MCP server.

---

vurb create

Scaffold a new Vurb server:

terminal

vurb create my-server
vurb create my-server -y
vurb create my-server --vector prisma --transport sse

Options

Option	Short	Default	Description
--transport <stdio|sse>	—	stdio	Transport layer
--vector <type>	—	—	Ingestion vector: vanilla, prisma, n8n, openapi, oauth
--testing	—	true	Include @vurb/testing + Vitest
--no-testing	—	—	Skip test suite
--yes	-y	—	Skip prompts, use defaults

TIP

vurb create auto-injects SKILL.md into your IDE's rule files — .cursorrules, .windsurfrules, .clinerules. Your AI agent becomes a framework expert on first scaffold.

---

vurb dev

HMR development server with auto-reload:

vurb dev --server ./src/server.ts
vurb dev --server ./src/server.ts --dir ./src/tools

Option	Short	Default	Description
--server <path>	-s	Auto-detect	Path to server entrypoint
--dir <path>	-d	Auto-detect	Directory to watch for changes

---

vurb lock

Generate and verify capability lockfiles. The lock command captures the behavioral surface of your server. Use --check in CI to gate builds against unreviewed capability changes.

Generating a Lockfile

terminal

vurb lock --server ./src/server.ts

  vurb lock — Generating vurb.lock

  ● Resolving server entrypoint — payments-api (12ms)
  ● Compiling tool contracts — 8 tools (45ms)
  ● Discovering prompts — 3 prompts (2ms)
  ● Computing behavioral digests (120ms)
  ● Writing vurb.lock (5ms)

✓ vurb.lock generated (8 tools, 3 prompts).
  Integrity: sha256:a1b2c3d4e5f6...

Verifying in CI

vurb lock --check --server ./src/server.ts

--check compares the existing lockfile against the live server surface without writing. Exits 0 if up-to-date, 1 if stale.

Options

Option	Short	Default	Description
--server <path>	-s	—	Path to server entrypoint. Required.
--name <name>	-n	Auto-detected	Server name for lockfile header
--cwd <dir>	—	process.cwd()	Project root directory
--check	—	—	Verify mode — compare without writing

CI/CD Integration

GitHub Actions

- run: vurb lock --check --server ./src/server.ts

GitLab CI

governance:
  script:
    - vurb lock --check --server ./src/server.ts

Pre-commit Hook

#!/bin/sh
vurb lock --check --server ./src/server.ts

---

vurb deploy

Bundle your server into a self-contained Fat Bundle (IIFE), compress it, and deploy to Vinkius Edge:

vurb deploy
vurb deploy --server ./src/server.ts

Prerequisites

# Quick setup (one-liner)
vurb remote --server-id <uuid> --token <token>

# Or configure separately
vurb remote --server-id <uuid>
vurb token <token>

Token Resolution

1

--token flag — highest priority, one-time override

2

VURB_DEPLOY_TOKEN env var — ideal for CI/CD

3

.vurbrc file — persisted via vurb token or vurb remote --token

Options

Option	Short	Default	Description
--server <path>	-s	Auto-detect	Path to server entrypoint
--token <token>	—	—	Override deploy token (one-time)
--allow-insecure	—	—	Suppress HTTP plaintext warning

Security

The CLI warns when a token reaches a non-localhost HTTP endpoint. Use --allow-insecure to suppress, or switch to HTTPS.

Bundle Limits

Maximum 500KB (before compression). The Fat Bundle includes all dependencies (Zod, MCP SDK, Vurb) — most servers fit well within this.

---

vurb remote

Manage cloud configuration stored in .vurbrc:

# Set server ID (uses default Vinkius Cloud endpoint)
vurb remote --server-id 019d0250-7baf-7172-9732-096c8baa4478

# Set server ID + token (full setup)
vurb remote --server-id 019d0250-7baf-7172-9732-096c8baa4478 --token vk_live_9hfaJlIPOv5x

# View current config
vurb remote

Option	Default	Description
<url> (positional)	Vinkius Cloud	Override API endpoint
--server-id <id>	—	Target server UUID
--token <token>	—	Save deploy token to .vurbrc

---

vurb token

Manage deploy tokens stored in .vurbrc. Tokens are displayed in masked form (vk_live_••••••••wp96):

vurb token vk_live_9hfaJlIPOv5xZhJEtjIYM0mcWBgo5tWcEePbwp96
# ✓ Token saved to .vurbrc (vk_live_••••••••wp96)

vurb token          # View token status
vurb token --clear  # Remove token

WARNING

The .vurbrc file is auto-added to .gitignore. Tokens are never displayed in full. For CI/CD, prefer the VURB_DEPLOY_TOKEN environment variable.

---

vurb inspect

Real-time TUI dashboard for monitoring:

vurb inspect
vurb insp --demo
vurb insp --pid 12345

TIP

Requires the optional @vurb/inspector package:

npm install @vurb/inspector

Option	Short	Default	Description
--demo	-d	—	Launch with simulator (no server needed)
--out <mode>	-o	tui	Output: tui or stderr (headless ECS/K8s)
--pid <pid>	-p	—	Connect to a specific server PID
--path <path>	—	—	Custom IPC socket/pipe path

Aliases: vurb inspect, vurb insp, vurb debug, vurb dbg

---

Exit Codes

Code	Meaning
0	Command completed successfully
1	Error — lockfile stale, missing config, server not found

Progress Reporting

CLI outputs Composer/Yarn-style progress to stderr:

Icon	Status
○	Queued
◐	In progress
●	Completed
✗	Failed

Programmatic API

The CLI logic is also available as importable functions:

import {
  parseArgs,
  commandLock,
  commandToken,
  resolveRegistry,
  ProgressTracker,
  createDefaultReporter,
} from '@vurb/core/cli';

See Capability Lockfile for the full programmatic lockfile API.