CLI

The installed binary is the authority for flags and defaults:

velloo --help
velloo <command> --help

This page explains which command to choose and the distinctions that matter. It avoids duplicating every flag, so it stays useful as Velloo evolves.

Commands follow one shape. An action is a verb (velloo run, velloo publish); managing a set of things is a noun and a verb (velloo design list, velloo publish remove). Flags change how a command runs, never which one runs. A command whose subject is a design takes it as its argument (velloo run web); a command whose argument is something else takes the design as --design (velloo emit home --design web).

Start and organize

velloo init

Initialize Velloo from an app root. The interactive flow first offers a pending Velloo update, so the folder is stamped by (and installs skills from) the newest build. It then asks which agents to wire and where the design lives: in the repo (./velloo/), in Velloo-managed storage under ~/.velloo/designs (outside the repo and not version-controlled), or a custom path. It prints the design folder it will use before scaffolding. A design outside the repository, whether in managed storage or at a custom path such as ../my-designs, is a local design: it is recorded only on your machine, nothing is added to the repository (no velloo.json entry, no project agent config), and agents are wired through global configs. Init never runs Git and does not need it: mkdir mydesign && cd mydesign && velloo init works in a plain directory.

The goal list depends on what init finds. With a host app it offers Redesign a screen, Redesign a component, Custom request, the Elsewhere welcome sample, or Blank. Without UI code to read it offers Design from a live site, the sample, or Blank. Init then detects routes, theme, and component provider, may offer a cloud sign-in and the opt-in feedback tool, and offers shell completions before printing the agent handoff.

cd your-app
velloo init
velloo init --external        # keep the design outside the repository

velloo design

Manage the designs associated with a checkout: those listed in its velloo.json, plus designs kept outside the repository on this machine. Bare velloo design runs list; the list is numbered so --id <number> can disambiguate other commands.

velloo design list
velloo design add
velloo design rename marketing "Marketing site"
velloo design remove "Marketing site"

design remove stops the design’s canvas and unregisters it. An in-repo design is deleted from disk; an external design is forgotten but keeps its content unless you pass --delete-content. It asks for confirmation, and needs --yes without an interactive terminal. Committed in-repo work remains recoverable through Git.

The less common subcommands:

• move moves a design between the repository, managed storage (--external) and another directory (--to <dir>); inside the repository it becomes a velloo.json entry, outside it is recorded only on this machine.
• rename changes the name stored in .design/config.json.
• upgrade migrates one design with the current binary, without self-updating Velloo; --all migrates every design in the checkout.
• bind <design folder> attaches a local design to this checkout on this machine, after moving or cloning the checkout, restoring a backup, or to turn a velloo.json entry that points outside the repository into a local design.
• set-app-root points a design folder at a different application root.

move, bind, and set-app-root print a preview; add --yes to apply.

velloo upgrade

Update Velloo, then migrate every design associated with the current checkout using the newly installed binary. Pass a design name or path to migrate only that one. Running canvases are stopped before their files are rewritten; outside any checkout or design, only the installation is updated. Installed agent skills, plugin, and rules are refreshed too.

velloo upgrade --check        # report an available update and pending migration; write nothing
velloo upgrade --binary-only  # update Velloo, leave the designs alone
velloo upgrade --design-only  # migrate with this build, no self-update

--dry-run is the same preview, and --no-skills skips the agent-guidance refresh. Updates follow the channel that installed Velloo: npm installations update from the npm registry, installer archives re-run the installer from their own download host, and Homebrew installations are handed to brew upgrade. Prefer this command to hand-editing a historical config shape.

Run and connect

velloo run

Start or attach to the persistent canvas for the resolved design folder. In an interactive terminal it stays in the foreground; press o to open the browser, b to continue in the background, or q to stop. Use --open to open immediately or --background explicitly.

velloo run --open
velloo run product

Ports are sticky per design. The daemon records the port it bound in .design/cache/port.json and asks for it first; a design with no remembered port tries 7300, then a port in the 7310–7399 band derived from its path. --port overrides all of it. Running from a checkout with several designs can start their canvases together.

The canvas daemon outlives the command and any agent session. It shuts itself down after 5 minutes with no canvas tab or agent connected.

velloo connect

Detect supported coding agents and write their MCP configuration, plus the agent guidance each one reads. It can wire Claude Code, Cursor, Codex, Continue, Claude Desktop, opencode, Droid, Cline, Gemini CLI, Windsurf, and VS Code/GitHub Copilot where the relevant scope is supported.

velloo connect
velloo connect --agent claude-code,cursor --no-skill

--agent takes comma-separated agent ids (manual prints a config for any other client), --project-root changes where project configs go, and --http with --mcp-url wires the HTTP transport instead of stdio. Connect an agent lists everything it writes.

velloo mcp

The entry point an agent starts. Stdio is the normal transport; --http prints a Streamable HTTP endpoint for clients that dial a URL.

The default guided surface advertises call_velloo, run_velloo_plan, and operation_schema. Use --surface full or VELLOO_MCP_SURFACE=full when a client works better with every native operation advertised directly.

When a checkout has several designs, the session instructions identify the current one. Agents can call list_designs; stdio sessions can call switch_design without restarting, while HTTP clients reconnect with velloo mcp <name>. If no design is selected, MCP opens the first by name and tells the agent to confirm before changing anything.

velloo status and velloo stop

velloo status lists the canvas daemons running on this machine and your Velloo Cloud sign-in state. It does not validate a folder’s config; velloo run does. velloo stop stops the resolved canvas, and velloo stop --all stops every Velloo canvas on the machine.

Bring existing UI in

velloo capture

Open a headed browser session for a live page. Log in and navigate as needed, then capture from the Velloo toolbar in the page or from the terminal: c captures the page, t captures only its theme, l lists captures, and q ends the session. This is the starting point for a faithful redesign: capture the page and its assets, recreate the baseline on a board, then compare new directions at the same viewport.

velloo capture localhost:3000/account
velloo capture list
velloo capture delete <id>     # or `all`

The URL is optional, and a bare host gets a scheme. capture list browses stored captures without opening a browser, and --design picks the design on all three.

velloo browser

velloo browser install installs the browser used for screenshots and PNG/PDF output. It installs a smaller headless shell by default; --full installs full Chromium, and --with-deps also installs required Linux system packages. Canvas editing itself does not require it.

Take work out

velloo export

Create a user-facing artifact from a screen, frame, or board. The output extension selects PNG, PDF, or standalone HTML; themes and light/dark modes can be selected.

velloo export launch-review --to launch-review.pdf
velloo export settings-mobile --to settings.png --scale 2

velloo emit

Print or save a screen’s structured code output for implementation. An agent should adapt it to the host app’s architecture rather than treating it as finished application logic.

velloo theme export

Project the design theme into host-app artifacts. The command previews changes before writing unless you explicitly apply them.

velloo theme export --to ../apps/web          # print diffs
velloo theme export --to ../apps/web --apply  # write the files

velloo render

A lower-level developer utility that renders a screen to HTML or PNG at a viewport. Use export for normal screen, frame, and board artifacts.

Optional cloud

• velloo login: authenticate this machine with the selected Velloo Cloud.
• velloo publish: publish selected boards for controlled external review.
• velloo logout: remove the saved credential.

velloo publish picks boards interactively; --boards takes comma-separated ids. When the design already has a matching published link it asks whether to update it or create a new link; --update and --new answer that without a prompt. Access is --public, --private (your organization), or --password (the value is prompted for or read from VELLOO_SHARE_PASSWORD), with --password-expires <date>; --visibility public|private is the explicit form. --team names the team to publish into; with more than one team to choose from, it’s asked for, and required without a terminal. --team-only limits the board to that team (Business). --public-comments / --no-public-comments decide whether people outside your organization can comment. See Roles and permissions. velloo publish list lists your published designs, and velloo publish remove <url> takes one down.

See Velloo Cloud for the product boundary and review flow.

Shell integration

velloo completions generates completions for supported shells. The experimental trace command appears only when its feature environment variable is enabled and is intended for debugging recorded MCP sessions, not the normal design workflow.