VifuHub CLI

vf is the command-line tool for building, validating, publishing, and playtesting interactive web experiences with VifuHub.

vf manifest check
vf build
vf deploy

When run from an experience or game directory, vf deploy resolves the local project, validates its setup, builds the game, checks the Agent Runtime artifact, uploads only the release artifact, and prints the playable URL.

Install

curl -fsSL https://vifu.ai/cli | bash
vf --help

For repeated use inside one project:

npm install --save-dev @vifu/vf
npx vf --help

Agent Workflows

Install the VifuHub CLI skill separately from github.com/vifudotdev/skills:

npx skills add vifudotdev/skills --skill "vifuhub-cli"

Then a coding agent can start from the current directory:

Use the VifuHub CLI skill. Deploy this game directory and report the Playable URL.

The skill tells agents to check vf --help, then use the one-step deploy path:

vf deploy --yes

vf deploy --yes creates missing setup from detected defaults, builds, checks the output, uploads the valid artifact, and prints Playable URL: when sharing succeeds. If authentication is missing, run:

vf login

Create a new project:

npm create @vifu/vifu my-game -- --template vanilla --no-interactive
cd my-game
vf deploy --yes

Deploy an existing project:

cd path/to/game
vf deploy --yes

You can also pass the project path explicitly:

vf deploy ./path/to/game

Projects And Release Artifacts

A source project can use a V1 manifest.json to define Vifu-specific build and runtime behavior:

{
  "name": "my-ai-game"
}

VifuHub detects Godot, Vite, and other supported project layouts before it builds. Add manifest fields only when you need to override detection or define an Agent Runtime feature. Do not put internal runtime keys such as runtime, services, devices, resources, permissions, capabilities, browser, or security in public game manifests.

README.md is the public Project Card. Its front matter can provide the title, description, tags, and release entry:

---
name: my-ai-game
title: My AI Game
description: A playable interactive story.
runtime:
  entry: index.html
---
# My AI Game

Source projects and release artifacts have separate contracts:

• A source project uses native project files such as project.godot or package.json, with an optional manifest.json for Vifu-specific behavior.
• vf deploy <project-directory> builds the project locally and packages only the runtime output.
• A ready Web artifact contains a root README.md, a root index.html or Project.html, and runtime assets.
• vf deploy <release.zip> validates and uploads the ZIP byte-for-byte.
• vf deploy <extracted-release-directory> packages that ready artifact once without running a source build.

The runtime publisher rejects directories that still contain source-project signals. Use vf deploy for source projects so editable workspace files are not mistaken for release files. Editable source sharing remains a separate, explicit vf upload source or --source workflow.

Useful commands:

vf manifest check
vf manifest check --dir ./path/to/game
vf manifest explain
vf manifest explain --dir ./path/to/game --debug

manifest explain --debug is for Agent Runtime development. It shows the compiled internal policy that the runtime will enforce.

Release Policy

vf deploy and vf publish treat the built output as the reviewed Agent Runtime artifact. The CLI does not rewrite the game, download CDN scripts, or create a deploy lockfile.

Allowed:

• bundled game JavaScript
• local build output from Vite, Angular, Phaser, Three.js, Pixi, plain HTML, or another web build tool
• approved external static CSS, fonts, images, and media
• AI/backend access through @vifu/hub or window.Vifu

Blocked:

• remote <script src="https://...">
• remote JavaScript import("https://...")
• remote workers or importScripts(...)
• remote .js, .mjs, or .wasm URLs inside built files
• direct calls to external AI/backend APIs from game JavaScript

If deploy fails, read the file, line, rule, URL, and fix shown by the CLI. The most common cause is an optional local or third-party provider being statically imported into a production browser bundle.

The canonical policy is .spec/runtime-artifact-policy.md.

SDK Integration

Games should call Agent Runtime capabilities through the VifuHub SDK:

const result = await Vifu.ai.generateText({
  model: "quality",
  messages: [{ role: "user", content: "Describe the next room." }]
});

await Vifu.gameState.save({ reason: "checkpoint" });

The SDK keeps runtime transport, host authentication, model routing, quota, and backend URLs out of game code. See packages/sdk/README.md.

Existing Experiences And Games

To publish an existing browser experience or game:

1. Add manifest.json.
2. Start with only name; let VifuHub infer common entry and build settings.
3. Build a static directory with index.html.
4. Replace direct AI/backend calls with the VifuHub SDK.
5. Remove unused remote/local AI providers from the published build.
6. Run vf deploy.

Extra source workflows live under explicit commands:

vf remix my-remix --from ./existing-game
vf import anki jlpt-review --apkg ./deck.apkg
vf import podcast listening-game --feed-url https://example.com/feed.xml

vf create and vf new are intentionally not exposed. Use npm create @vifu/vifu for new template projects.