Skip to main content

Overview

This guide walks you from nothing to a working Waypoint project: signed in, CLI authenticated, a project created, and your first artifacts authored and validated. It should take well under an hour.

Waypoint is additive to your existing setup. You keep coding the way you already do — with Claude Code, Cursor, or whatever agent you prefer — and you add Waypoint on top. You author your project's intent as a graph of small, schema-validated artifacts, and waypoint validate proves that those artifacts are mutually coherent and that your code conforms to them. Waypoint never proxies your LLM or hosts your editor; it gives the tools you already use a checkable definition of "correct."

If you haven't yet, read the Introduction and Why Waypoint for the motivation. This page is the hands-on path.

Prerequisites​

Before you start, make sure you have:

  • A supported coding agent. Claude Code, Cursor, or Zed all work — Waypoint registers itself as an MCP server in whichever agent clients it detects. You'll do most of your authoring by working with the agent.
  • git, with the repository you want Waypoint to manage already initialized (git init) and ideally pointed at a remote. waypoint init reads your origin remote to infer the project owner and name.
  • A POSIX shell (bash or zsh) to run the install script and CLI commands. The CLI ships native builds for macOS, Linux, and Windows.
  • An email address you can receive mail at — sign-in uses a magic link.
tip

You do not need to set up any cloud accounts, configure AWS, or install a database. Waypoint's backend is hosted; you authenticate against it with an API key the CLI stores for you.

The path at a glance​

Follow these five steps in order. Each links to a dedicated page.

  1. Sign in & get an API key — sign into the Waypoint web app with a magic link, then obtain a credential for the CLI (either an auto-minted bootstrap token from the onboarding walkthrough, or a permanent API key from Settings).
  2. Install & authenticate the CLI — install the waypoint binary with a one-line script and log in with your credential. Credentials are stored in your OS keychain.
  3. Create a project — run waypoint init in your repo to create the server-side project, write waypoint.json, install git hooks, register the Waypoint MCP server, and install the agent skill.
  4. Author your first artifacts — work with your coding agent to author artifacts top-down in dependency order, then prove coherence with waypoint validate.
  5. Commit and push — the git hooks validate your artifacts and upload their content; once you git push, the web app renders your graph. (Covered at the end of step 4.)
note

The web app and the CLI are two halves of one flow. You sign in and pick your onboarding mode in the app; you install, authenticate, and author from the terminal. The app polls for your project and switches into the project view once waypoint init creates it.

Ready? Start with Sign in & get an API key.