Overview

waypoint is the command-line interface for the Waypoint framework. It validates artifacts against the embedded workflow DAG, installs git hooks, registers the MCP server your agent uses, and drives the rest of the authoring loop. This section is a complete reference for every public command, grouped by what you're trying to do.

If you're new, start with Getting Started — it walks you through install, authentication, and your first project. This page is the reference: install, versioning, the command tree, flag conventions, and the environment variables the CLI reads.

Install

Install the binary with the one-line script. It detects your platform, downloads the matching release, verifies its checksum, and puts waypoint on your PATH:

curl -sSfL https://software.gowithdante.com/install.sh | sh

The CLI ships native builds for macOS, Linux, and Windows. To upgrade an existing install later, use waypoint update (it pulls from the same release channel the install script uses).

Check the version

waypoint version

Print the CLI version, commit, and build date.

waypoint version [flags]

The text output looks like waypoint v0.1.0 (a1b2c3d, built 2026-06-07).

Flag	Type	Default	Description
--json	bool	false	Emit structured JSON ({version, commit, builtAt}).

caution

waypoint --version does not work — the root command does not wire a --version/-v flag, so passing it errors as an unknown flag. Always use the waypoint version subcommand. This matters because the build workflow installs the binary via go install; waypoint version is how you confirm which build is actually on your PATH.

When to use: To confirm which build is on your PATH.

waypoint version
waypoint version --json

For help on any command, use standard cobra help: waypoint help, waypoint <cmd> --help, or -h.

Command tree

waypoint
├── validate [rule-name]     run structural / validation / semantic checks (proof-tree v2 default)
├── verify <hash>            verify a proof certificate by hash
├── inspect                  interactive TUI to explore a proof tree
├── status                   print repo state + last validate result
│
├── init                     initialize a Waypoint project (onboarding orchestrator)
├── login                    authenticate against the service; store an API key
├── logout                   remove the stored API key
├── pull                     download remote artifact blobs into the local cache
├── push                     upload local artifact blobs to the service
├── project                  manage the local project registry
│   ├── register             register/update a (workspace, project) → path mapping
│   ├── unregister           remove a (workspace, project) entry        [rm, remove]
│   ├── list                 list registry entries                      [ls]
│   └── path                 print the absolute path for an entry
├── artifact                 CLI fallback for the MCP artifact tools (persistent: --workflow)
│   ├── get                  fetch an artifact
│   ├── put                  write an artifact
│   ├── rehash               sync waypoint.json from the on-disk tree
│   └── ping                 verify the MCP server starts and responds
├── workflow                 manage the project's workflow pin
│   └── types [<workflow>]   print waypoint types as type:pattern lines
├── schema [name]            print the embedded JSON Schema for an artifact type
│
├── mcp                      manage the local MCP server + agent-client registration
│   ├── serve                run the MCP server over stdio
│   ├── install              register Waypoint MCP in detected agent clients
│   └── uninstall            remove the Waypoint MCP entry from agent clients
├── hook                     install git hooks that run waypoint validate
├── unhook                   remove waypoint-managed git hooks
├── skill
│   └── install              install Waypoint agent skill bundles into .claude/skills/
├── report
│   └── html <report.json>   render a validation JSON report as HTML
├── version                  print CLI version / commit / build date
├── update                   self-update the CLI to the latest release
├── generate                 generate code/test artifacts (advanced)
│   ├── code                 generate code skeletons
│   ├── relatedcode          record emitted code-file paths onto relatedCode[]
│   ├── enrich-tests         enrich scaffold test artifacts via the model
│   └── tests                generate test-file skeletons {api, unit, proptest, contract}
└── migrate                  one-shot codemods that rewrite artifacts in bulk
    └── page-to-slice        convert legacy page artifacts to slice[layer=page]

The pages in this section cover these groups:

• Validation & Inspection — validate, verify, inspect, status.
• Projects & Artifacts — init, login/logout, project, artifact, pull, push, workflow types, schema.
• Integrations & Automation — mcp, hook/unhook, skill install, report html, update, and the advanced generate and migrate families.

Flag conventions

The root waypoint command registers no persistent (global) flags of its own — running bare waypoint just prints help. Every flag documented in this section is local to its command. There is no shared --workflow, --json, or --verbose that applies everywhere; each command re-declares the flags it needs, with its own defaults (for example --workflow defaults to software, booleans default to false).

Two command groups are the exception: they use group-level persistent flags inherited by their subcommands.

• The artifact group has a persistent --workflow flag (default software) shared by get, put, rehash, and ping.
• The generate tests group shares --workflow, --dry-run, --bc, and --type with its api/unit/proptest/contract subcommands.

Common conventions you'll see across many commands:

• --json — emit structured JSON instead of human-readable text (good for scripting / CI).
• --dry-run — show what would happen without writing anything (pull, push, artifact rehash, generate *, migrate *).
• --workspace / --project — override the workspace/project slugs that otherwise default from the nearest waypoint.json (walk-up from the current directory).
• --workflow — the workflow a command operates against; almost always defaults to software.

Exit codes

Most commands return 0 on success and 1 on failure. The proof-certificate commands use a finer mapping: 0 success, 1 generic error or a tampered certificate, 2 certificate not found. waypoint validate exits 1 directly on validation failure, which is what makes it usable as a git-hook gate.

Environment variables

The CLI reads the following WAYPOINT_* (and a few related) environment variables. None are required for normal use — they're escape hatches for CI, on-prem, and advanced setups. Credentials themselves are stored in your OS keychain by default (or ~/.waypoint/credentials.json when --file is used), not in an environment variable.

Variable	Read by	Meaning
WAYPOINT_STORE_MODE	pull, push, validate, artifact *, mcp serve, migrate	Forces the artifact-store mode: customer, local, or dogfood. Overrides auto-detection (credentials present → customer, else → local). dogfood is never auto-detected; you must set it explicitly.
WAYPOINT_SERVICE_URL	login, init	Overrides the service base URL (default https://api.gowithdante.com/staging). A --service flag, where present, takes precedence over this.
WAYPOINT_PROOF_SIGNING_KEY	validate, verify	HMAC key used to sign and verify the proof certificate. When set, a signature mismatch is fatal (tampered). When unset, signing/verification is skipped.
WAYPOINT_PROOF_BUCKET	validate	When set (with AWS credentials available), proofs are written through to this S3 bucket in addition to the local .waypoint/certs/ store.
WAYPOINT_PROOF_PREFIX	validate	S3 key prefix for the proof bucket above.
WAYPOINT_BEHAVIORAL	validate (--v1 path)	=1 opts in the behavioral test collector (runs go test). Off by default.
WAYPOINT_SWIPLBIN	validate	Override the path to the swipl (SWI-Prolog) binary. If unset, looked up on PATH; absence falls back to the gofunc engine.
WAYPOINT_CLIPPY_PLUGIN_BIN	validate	Override the clippy-plugin-waypoint binary used by the Rust static-code checker. Empty → PATH lookup.
WAYPOINT_ESLINT_PLUGIN_BIN	validate	Override the eslint-plugin-waypoint binary used for JS/TS static checks.
WAYPOINT_REVIEWER_DISABLED	validate	=1 disables the Tier-3 LLM reviewer wiring entirely (a no-op reviewer stays).
WAYPOINT_REVIEWER_API_KEY	validate	API key for explicit reviewer opt-in (CI / on-prem), used when the local claude CLI is absent.
WAYPOINT_REVIEWER_MODEL	validate	Model for the API-key reviewer path (default claude-haiku-4-5).
WAYPOINT_REVIEWER_MAX_TOKENS	validate	Max tokens for the reviewer path (default 512).
WAYPOINT_REVIEWER_TIMEOUT	validate	Reviewer request timeout (default 30s).
WAYPOINT_REVIEWER_BASE_URL	validate	Optional base URL for on-prem reviewer proxies / tests.
ANTHROPIC_API_KEY	validate, generate enrich-tests	Enables the Claude LLM reviewer / enrichment. When unset, the no-op reviewer is used and semantic rules report deferred.
WAYPOINT_BASE_URL	update	Override the release-channel base URL for self-update (falls back to --base-url, then the built-in default).

note

When WAYPOINT_PROOF_BUCKET is set, the standard AWS SDK config is also consulted, so AWS_PROFILE / AWS_REGION / other AWS_* variables apply transitively.

Experimental / hidden commands

The CLI ships a handful of pre-alpha, internal commands that work but are intentionally omitted from waypoint --help and are not part of the stable CLI surface: scaffold, trace, render, loop, emit, and workflow update. Their flags and behavior may change or be removed without notice, so they are not documented as stable API here. If you discover one, treat it as unstable and unsupported. A short recap lives at the end of Integrations & Automation.