Integrations & Automation
These commands connect Waypoint to the rest of your toolchain: the MCP server your coding agent talks to, the git hooks that gate commits and pushes, the agent skill bundles, HTML reporting for CI, and CLI self-update. The page closes with the advanced code-generation (generate) and codemod (migrate) families, and a note on the experimental/hidden commands that are intentionally not documented as stable API.
waypoint mcp
Manage the local MCP server and its registration in agent clients.
Agent clients (Claude Code, Cursor, Zed, Antigravity) use the local MCP server to read and write Waypoint artifacts. The server exposes exactly four CRUD tools — artifact.get, artifact.list, artifact.put, artifact.delete. Validation is deliberately not advertised to agents; run waypoint validate yourself or use the app.
waypoint mcp serve
Run the MCP server over stdio.
waypoint mcp serve [flags]
Runs the server over newline-delimited JSON-RPC 2.0 on stdin/stdout. It's meant to be spawned by an agent client (via waypoint mcp install), not run by hand. Project and workflow default to sensible local values; --root points the backing store at a directory.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--project | string | dev | Project ID the server scopes to. |
--workflow | string | software | Workflow the server scopes to. |
--root | string | "" | Local-fs artifact-store root (default ~/.waypoint/localstore/). Implies local mode. |
--verbose | bool | false | Log requests/responses to stderr. |
When to use: Almost never directly — agent clients launch it for you. Run it by hand only to debug the server.
waypoint mcp serve --verbose
waypoint mcp install
Register Waypoint as an MCP server in every detected agent client.
waypoint mcp install [flags]
Writes a Waypoint MCP server entry into each supported client's config (Claude Code ~/.claude.json, Cursor ~/.cursor/mcp.json, Zed ~/.config/zed/settings.json, and Antigravity). Foreign entries are left untouched; the command is idempotent. Use --client to target specific clients, and --command to override the executable path written into the configs (useful when waypoint isn't on PATH).
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--client | string list | all | Restrict to these client IDs (claude-code, cursor, zed, antigravity). |
--command | string | waypoint | Override the executable path written into client configs. |
When to use: After installing the CLI in a repo set up outside init, or to re-register the MCP server in a newly added agent client. (waypoint init runs this for you.)
waypoint mcp install
waypoint mcp install --client cursor,zed --command /usr/local/bin/waypoint
waypoint mcp uninstall
Remove the Waypoint MCP entry from supported agent clients.
waypoint mcp uninstall [flags]
Removes only the Waypoint entry from each client's config, preserving all others. Safe even if it was never installed.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--client | string list | all | Restrict to these client IDs (claude-code, cursor, zed, antigravity). |
waypoint mcp uninstall
waypoint hook
Install git hooks that run waypoint validate.
waypoint hook [flags]
hook writes git hooks under scripts/hooks/ (committed to version control) and sets git's core.hooksPath to that directory, so the hooks run on every clone. Existing waypoint-managed hooks are overwritten; foreign hooks are preserved unless you pass --force. Remove them with waypoint unhook.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--force | bool | false | Overwrite foreign (non-waypoint) hook files. |
When to use: To add validation gating to a repo set up outside init, or to repair hooks that drifted.
waypoint hook
waypoint hook --force
waypoint unhook
Remove waypoint-managed git hooks.
waypoint unhook
Removes the hooks installed by waypoint hook and clears core.hooksPath. Non-waypoint hooks are left untouched. Takes no flags.
waypoint unhook
waypoint skill install
Install the Waypoint agent skill bundles into .claude/skills/.
waypoint skill install
Writes one SKILL.md per onboarding mode (greenfield, characterize, rearchitect) into .claude/skills/waypoint-<mode>/. The files are committed to git so every contributor gets the same agent rules, and Cursor and Zed pick up the same files. It's idempotent — matching files are left untouched. Takes no flags.
When to use: To re-install or refresh the agent skill bundles after init, or in a repo set up by hand.
waypoint skill install
waypoint report html
Render a validation JSON report as a self-contained HTML page.
waypoint report html <report.json> [flags]
report html turns a JSON report previously written by waypoint validate --report into a shareable, browsable HTML page. The required <report.json> argument is that report file.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--out | string | "" | Write the HTML to this file (default: stdout). |
When to use: To publish a machine-readable validation report as a human-readable CI artifact or review page.
waypoint validate --report r.json && waypoint report html r.json --out report.html
waypoint update
Self-update the CLI to the latest published release.
waypoint update [flags]
update fetches the latest release from the public release channel (the same source the install script uses), downloads the asset for your platform, verifies its SHA-256 checksum, and atomically replaces the running binary. Override the source with --base-url or $WAYPOINT_BASE_URL. --check prints the latest version without installing.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--check | bool | false | Print the latest version without installing. |
--base-url | string | "" | Override the release-channel base URL (default $WAYPOINT_BASE_URL or the built-in default). |
When to use: To upgrade an existing install in place. Confirm the result with waypoint version.
waypoint update
waypoint update --check
Advanced: code generation and codemods
The generate and migrate families are advanced tooling. generate emits code and test skeletons from the artifact graph; migrate runs one-shot codemods that rewrite artifacts in bulk when an upstream schema changes shape. Both operate against the same composite artifact store the rest of the CLI uses, and both support --dry-run — always preview before writing.
waypoint generate code
Generate code skeletons from the artifact graph (code only, no tests).
waypoint generate code [flags]
Walks every artifact in waypoint.json and asks each type's registered scaffolder for the code files it would emit (test files are excluded — use generate tests). It's idempotent by file presence: existing files are never overwritten, with the documented exception that Cargo.toml files are refreshed each run to keep the workspace structure in sync.
The command's summary describes Rust skeletons, which is the primary target, but the emitted language is scaffolder-dependent per artifact type — the framework also emits Go. Treat the output language as determined by each artifact type's scaffolder.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--workflow | string | software | Workflow name. |
--dry-run | bool | false | Print what would be written without writing. |
--bc | string | "" | Limit to one bounded-context slug. |
--type | string | "" | Limit to one waypoint type (e.g. command_handler). |
waypoint generate code --bc marketplace --dry-run
waypoint generate relatedcode
Record each artifact's emitted code-file paths onto its relatedCode[] field.
waypoint generate relatedcode [flags]
Walks every artifact, asks each type's scaffolder for the code files it would emit (the same call as generate code), and records the sorted file paths onto the artifact's relatedCode[], writing back through the artifact store. No code files are written. It's idempotent — relatedCode[] is replaced each run and stale paths are dropped — and it lets downstream lint rules see which files each artifact owns. Same flags as generate code (--workflow, --dry-run, --bc, --type).
waypoint generate relatedcode
waypoint generate enrich-tests
Enrich scaffold test artifacts with business-rule scenarios via the model.
waypoint generate enrich-tests [flags]
Reads aggregate_test scaffold artifacts and enriches their businessRuleScenarios from the aggregate's declared invariants using the Claude API, then updates generationStatus from scaffold to generated. It respects // waypoint:preserve markers (preserved blocks aren't overwritten). Requires ANTHROPIC_API_KEY; --dry-run previews without calling the API.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--workflow | string | software | Workflow name. |
--dry-run | bool | false | Preview without calling the model. |
--model | string | claude-haiku-4-5-20251001 | Claude model to use for enrichment. |
--bc | string | "" | Scope to a specific bounded-context slug. |
ANTHROPIC_API_KEY=... waypoint generate enrich-tests --bc marketplace
waypoint generate tests
Generate test-file skeletons from the artifact graph.
waypoint generate tests [api|unit|proptest|contract] [flags]
Walks every artifact and asks each type's scaffolder for the test files it would emit (code files excluded — use generate code). The subcommands scope to a specific category. This group's flags are persistent, inherited by generate tests and all four subcommands:
| Flag | Type | Default | Description |
|---|---|---|---|
--workflow | string | software | Workflow name. |
--dry-run | bool | false | Print what would be written without writing. |
--bc | string | "" | Limit to one bounded-context slug. |
--type | string | "" | Limit to one waypoint type. |
The subcommands (each takes only the inherited flags above):
| Subcommand | Generates |
|---|---|
waypoint generate tests api | Bruno .bru API tests from api_endpoint artifacts. |
waypoint generate tests unit | Per-handler unit tests from command_handler / query_handler. |
waypoint generate tests proptest | Per-invariant proptest fixtures from aggregate artifacts. |
waypoint generate tests contract | Port contract tests from port_contract_test artifacts. |
waypoint generate tests
waypoint generate tests api --dry-run
waypoint generate tests unit --bc marketplace
waypoint migrate page-to-slice
Convert legacy page artifacts to slice[layer=page] (plus ui/model segments).
waypoint migrate page-to-slice [flags]
Reads every manifest entry matching interfaces/ui/pages/<slug>/page and rewrites each as a slice artifact at interfaces/ui/apps/<ui-app>/slices/<slug>/slice (layer=page, route preserved), a segments/ui sibling mirroring components[], and a segments/model sibling carrying dataRequirements[] → dataNeeds[]; the original page is then deleted. --ui-app is required when the project has more than one ui_app (it's auto-selected when there's exactly one). Workspace and project default from the nearest waypoint.json.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--ui-app | string | "" | ui_app slug to assign converted slices to; required when the project has multiple ui_apps. |
--workspace | string | "" | Workspace slug; defaults from the nearest waypoint.json. |
--project | string | "" | Project slug; defaults from the nearest waypoint.json. |
--dry-run | bool | false | Print the planned mutations without writing. |
waypoint migrate page-to-slice --ui-app web --dry-run
Experimental / hidden commands
The CLI ships several pre-alpha, internal commands that work but are intentionally omitted from waypoint --help and are not part of the stable CLI surface. Their flags and behavior may change or be removed without notice, so they are not documented here as stable API:
scaffold— generate stub artifacts on disk (superseded by MCP-based authoring).trace— inspect feature beats, data-flow milestones, and scenario coverage.render— render architecture diagrams from artifacts.loop— run the commit-driven agent loop.emit— emit generated test artifacts as Go test files.workflow update— pin a workflow version / run a workflow migration.
If you come across one of these, treat it as unstable and unsupported.