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. In a terminal, init first offers a pending Velloo update, so the folder is stamped by (and installs skills from) the newest build. It then starts a small setup server on this computer, prints its URL, and opens the setup page in your browser when you press Enter (Ctrl+C cancels). The page asks, in order:

• Project: 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. In a folder that holds several apps, it also asks which app to design, or the repository as a whole. When the folder already has a design, the page offers to open it or to create another beside it.
• Start: with a host app, Just set Velloo up, Redesign a screen (from the routes init found, or a name you type), Redesign a component, Capture a page, Design something new, or Explore the welcome sample. Without UI code to read, Design from a live site, the sample, or Start blank. A capture opens its browser window from the setup page before the canvas; the agent’s first task names the pages you capture, and with none it opens its own capture session.
• Agents: which other agents to wire, in each agent’s own config for every project or in project config files for this one. The agent run in the canvas needs none of this.
• Cloud: what a free Velloo Cloud account adds, with Sign up free and Sign in, which run the same browser sign-in as velloo login. Skip and create design goes on without an account. Once you’re signed in, it asks whether agents may send Velloo product feedback, unless the repository’s velloo.json already says.
• Ready: after the design is created, its first task, which you can edit, and the agent to run it, with an optional model. Start with the agent opens the canvas on the Agent tab with that agent at work; Open without an agent just opens the canvas.

The canvas keeps running after init exits. velloo run reopens it later; it is not a setup step.

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.

Init does not ask what the app can answer:

• The library is read from the app. A provider that matches the app’s UI library is used. An app with none, or with one Velloo has no adapter for, gets the no-library provider, styled with Tailwind when the app has it and inline styles when it doesn’t. It is never given shadcn components it does not have. The library is a question only when there is no app to read; --library still pins it.
• Where components live is found, never asked. Init reads components.json, then the usual directories, and in a monorepo looks under the app that was scanned. --components-dir overrides it.
• The theme is imported. Init runs the same import as import_theme: the app’s stylesheet and the stylesheets it @imports, the nearby Tailwind config, and the fonts a next/font loader sets. In a Mantine app it reads the app’s theme, or uses Mantine’s own defaults when the app sets none.

The terminal reports what happened: the stylesheets the theme was imported from, the fonts and where they came from, and a Left for setup line naming what the import could not carry. When the stylesheet it found holds no theme tokens, init says so and starts the design on a preset.

--non-interactive skips the page and takes every answer from flags, for scripts and agents; without a terminal, init takes this path by itself. It follows the same rules for every start that reads the app. --start=sample reads the app too and uses its library, falling back to shadcn when the app has none; with no app to read the --library default is unchanged. By default it wires Claude Code and Cursor in project configs (--no-connect skips this), then prints the closing steps and, for a design task, a handoff prompt for your agent. A sample is Velloo’s own demo, so its closing steps don’t offer to set it up for your app.

Init records where the theme came from in the design’s config as themeSource (see config.json). velloo upgrade re-imports from the same place and updates it.

When there is an app to match, the agent’s first task opens with setup, and so do the non-interactive closing steps and handoff prompt: ask your agent to set Velloo up for the app (/velloo:setup in Claude Code) before the first design.

cd your-app
velloo init
velloo init --external        # keep the design outside the repository
velloo init --non-interactive --start=redesign-screen --screen-name Settings

Init also detects HTML/htmx apps and plain HTML sites, copies linked app stylesheets it can resolve, and offers to seed tokens from a design-system DESIGN.md (--no-design-md skips the offer).

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 add runs velloo init with a new design folder, so in a terminal it opens the same setup page. 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. --to <path> names it; without it, the command offers the applications it finds in the repo.

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

set-app-root is the fix when a design was recorded from a monorepo’s root while the app is a workspace below it. The preview lists each config value it will rewrite. When one root contains the other, a path that already names the right files is left alone and the values relative to the application root are rewritten instead:

hostApp.root: .. → ../web
hostApp.aliases["@/*"]: web/src/* → src/*
codegen.componentsDir: web/src/components/ui → src/components/ui

When the two roots are unrelated, because the design was recorded for the wrong sibling app, paths under the old application follow it to the new one. Applying the change stops the design’s canvas, since the daemon holds the application root for its whole lifetime.

A design at a workspace root usually works without this. When the root cannot resolve a package such as React itself, Velloo looks in the workspaces the root declares (workspaces in package.json, or packages in pnpm-workspace.yaml) and uses the member that has it, as long as the members agree on one copy. If two workspaces each have their own, the error names them and points at set-app-root.

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. velloo init starts the canvas the first time, so this is the command for every time after: reopening a design, starting a canvas that stopped, or opening one made with --non-interactive. 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 read_velloo, 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. PNG and PDF captures mount your app’s own components and run live islands, as the canvas does. Standalone HTML can’t carry them and warns about the fidelity it drops.

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.

For an HTML design, velloo emit contacts --to contacts.html writes native markup with hx-* attributes; a JSON destination writes the full IR. See the HTML workflow.

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 theme export --to ../design-review --format design-md previews a DESIGN.md export (and DESIGN.dark.md when the theme has dark colors). Add --apply to write. The followed source document is protected from overwrite. Theme export details →

velloo render

A lower-level developer utility that renders a screen to HTML or PNG at a viewport. A PNG mounts the app’s own components like export does. 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.