CLI reference
Every command, every option.

Exit codes

Code	Meaning
0	Success
1	Failure: a build error, check errors, or warnings when you pass --strict

Commands that take --json print one JSON object, including { "ok": false, "error": "…" } when something fails, so scripts and AI assistants never have to read the screen.

Create and develop

vage create <dir>

Makes a new site in <dir> with an example page, a layout, AGENTS.md, CLAUDE.md and a GitHub Actions check. Most people run it as npm create vagejs@latest my-site.

Option	What it does
--vage-spec <spec>	The version of vagejs to put in the new package.json
--json	Machine-readable output

vage dev

Starts the dev server with live reload and prints the local address.

Option	What it does
--port <port>	Use this port. Fails if it's taken; by default it picks a free port from 5173
--host [host]	Make the server reachable from other devices on your network
--root <dir>	Project folder, if it isn't the current one

vage build

Builds the finished site into dist/, along with robots.txt, sitemap.xml, llms.txt and a 404.html.

Option	What it does
--json	Machine-readable output
--root <dir>	Project folder

vage preview

Serves the built dist/ folder so you can look at the real output before publishing. Takes --port (default: a free port from 4173), --host and --root.

Check before you publish

vage check

Reads your pages and reports problems without changing anything: broken links, missing titles or descriptions, canonical URLs, structured data, image alt text and sizes, the page language, unsafe URLs and analytics events that don't match your config. Every finding names the file to fix.

Option	What it does
--strict	Fail on warnings too
--json	Machine-readable findings
--root <dir>	Project folder

vage audit

Builds the site, then checks each page against size budgets (JavaScript, CSS, images, fonts, number of requests) and runs axe accessibility rules.

Option	What it does
--lighthouse	Also run Lighthouse locally. Needs the lighthouse package and Chrome
--url <url>	Audit a live page with PageSpeed Insights, plus real-visitor data from CrUX when you have a key
--strategy <strategy>	mobile, desktop or both
--strict	Fail on warnings too (budgets, lab scores, API failures)
--json	Machine-readable results

Publish

vage deploy:github

Checks and builds the site, shows exactly which files it will commit, then commits and pushes to GitHub after you confirm. It refuses to commit secrets such as .env files and API keys, and it never force-pushes.

Option	What it does
--remote <url>	Git address to use as origin if the project has none
--branch <name>	Branch for a new repository (default: main)
-m, --message <msg>	Commit message
--dry-run	Show the plan without changing anything
--yes	Skip the confirmation question. Only use it when the site owner has said yes
--json	Machine-readable output

vage deploy

Publishes to GitHub Pages (adds a workflow, pushes, then waits for GitHub to finish) or to Cloudflare Pages (uploads dist/ with Wrangler; other branches get a preview address). It only reports success when the host does.

Option	What it does
--target <host>	github-pages or cloudflare-pages (default: deploy.target in your config)
--project <name>	Cloudflare Pages project name
--remote, --branch, -m, --dry-run, --yes, --json	Same as deploy:github
--no-wait	Don't wait for the GitHub Actions run

vage indexnow

Tells search engines that support IndexNow (such as Bing) which pages changed. It asks before sending anything.

Option	What it does
--changed-since <ref>	Pages changed since a git commit, for example HEAD~1
--urls <list>	A comma-separated list of addresses or paths
--all	Every page in sitemap.xml
--dry-run	Show the list without sending it
--yes	Skip the confirmation question

Search Console, Analytics and reports

Command	What it does
vage connect <service>	Connect Google Search Console (gsc) or Analytics (ga4) by signing in with Google, or save your own PageSpeed or CrUX API key (pagespeed, crux). --no-open prints the sign-in link instead of opening a browser
vage disconnect <provider>	Remove a connection: google (revokes access), pagespeed or crux
vage report <kind>	A Search Console (search) or Analytics (analytics) report. Takes --property, --property-id and --days

Reference and rules

Command	What it does
vage info	Describes every command, option, config setting and frontmatter field. Add --json for the full JSON Schemas
vage guidelines	Shows the facts vagejs relies on (crawler names, analytics limits, host rules), each with its official source and the date it was checked

Environment variables

Keys are always yours. vagejs never ships with shared keys.

Variable	Used for
PAGESPEED_API_KEY	vage audit --url (or save it with vage connect pagespeed)
CRUX_API_KEY	Real-visitor data in vage audit --url (falls back to the PageSpeed key)
GOOGLE_OAUTH_CLIENT_ID	vage connect: your Google Cloud OAuth client (type: Desktop app)
GOOGLE_OAUTH_CLIENT_SECRET	Optional: that client's secret
VAGE_CONFIG_DIR	Optional: where the Google sign-in is stored
CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID	vage deploy --target cloudflare-pages, or run npx wrangler login instead

Not available yet

Netlify and Vercel deploys, multi-language sites, base paths, CMS content sources and an MCP server aren't part of 0.1. npx vage info --json lists them under notImplemented, so an AI assistant won't promise them.