Projects & Artifacts
These commands cover the lifecycle around a project and the artifacts inside it: authenticating the CLI, initializing a repo, keeping the local project registry accurate, reading and writing individual artifacts, syncing artifact blobs with the service, and inspecting the workflow's type catalog and schemas.
If you're setting up for the first time, Getting Started walks these in order — sign in, authenticate the CLI, create a project, and author artifacts. This page is the per-command reference.
waypoint init
Initialize a Waypoint project — the onboarding orchestrator.
waypoint init [flags]
init walks a fresh git repo to a ready-to-author Waypoint project. It confirms you're authenticated, resolves an onboarding mode, reads your git origin remote for owner/repo, creates the project under your workspace, nudges the GitHub App install if the repo is unmapped, writes waypoint.json, installs pre-commit and pre-push hooks, registers Waypoint as an MCP server in detected agent clients, installs the mode-specific agent skill, extends AGENTS.md and writes WAYPOINT_USAGE.md, and prints the next step. It is idempotent; --force overwrites a waypoint.json whose slugs don't match.
The --mode flag selects an onboarding mode: greenfield (a brand-new project), characterize (capture intent for an existing codebase), or rearchitect. When omitted it is auto-detected or prompted.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--workflow | string | software | Which workflow this project uses (software or marketing). |
--workspace | string | "" | Workspace slug (default: the workspace from /me). |
--project | string | "" | Project slug (default: the git repo name). |
--mode | string | "" | Onboarding mode: greenfield, characterize, or rearchitect (default: auto-detect or prompt). |
--force | bool | false | Overwrite an existing waypoint.json with mismatched slugs. |
--service | string | "" | Service base URL (overrides WAYPOINT_SERVICE_URL). |
--no-browser | bool | false | Don't try to open the GitHub install URL in a browser. |
--skip-github | bool | false | Skip the GitHub App install step (project-only init). |
Requires: a prior waypoint login, and a git origin remote to infer the GitHub owner/repo.
When to use: The first command you run in a repo you want Waypoint to manage. It sets up everything — manifest, hooks, MCP registration, agent skills, and the local registry entry.
waypoint init
waypoint init --mode greenfield
waypoint init --workspace acme --project marketplace --skip-github
waypoint login
Authenticate against the Waypoint service and store an API key locally.
waypoint login [flags]
login runs an OAuth-style device-code flow: it prints a short user code and opens the verification page in your browser (--no-browser skips that). On approval it mints an API key and stores it in your OS keychain — or in ~/.waypoint/credentials.json with --file, which is the right choice for CI and containers. Two shortcuts skip the device flow: --bootstrap redeems a wpkx_ bootstrap token (the primary onboarding handoff from the app), and --key stores a raw API key directly (e.g. one from a welcome email or the app's API Keys settings).
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--bootstrap | string | "" | Redeem a wpkx_ bootstrap token (primary onboarding path). |
--key | string | "" | Store an API key directly, skipping the device-code flow. |
--workspace | string | "" | Workspace slug to select non-interactively (skips the multi-workspace prompt). |
--service | string | "" | Service base URL (overrides WAYPOINT_SERVICE_URL). |
--no-browser | bool | false | Don't try to open the verification URL in a browser. |
--file | bool | false | Store credentials in ~/.waypoint/credentials.json instead of the OS keychain (CI/containers). |
--timeout | duration | 15m | How long to wait for approval before giving up. |
When to use: Before init, pull, push, or remote validate. Use --bootstrap for the standard handoff from the app, and --file in CI.
waypoint login
waypoint login --bootstrap wpkx_abc123
waypoint login --file --key wpk_live_xxx
waypoint login --workspace acme --no-browser
waypoint logout
Remove the stored Waypoint API key.
waypoint logout [flags]
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--file | bool | false | Remove credentials from ~/.waypoint/credentials.json instead of the OS keychain. |
When to use: To sign the CLI out on a machine, or to clear a stale credential before logging in again.
waypoint logout
waypoint logout --file
waypoint project
Manage the local project registry at ~/.waypoint/projects.json.
The registry maps (workspace, project) → absolute path. The MCP server consults it to route artifact.* calls to the correct waypoint.json. (CLI commands like validate and status instead walk up from the current directory.) waypoint init auto-registers your project; use these subcommands to fix drift or register a project you set up by hand.
waypoint project register
Register or update a (workspace, project) → path mapping.
waypoint project register [flags]
With no flags, it walks up from the current directory to waypoint.json and reads the workspace, project, and path from there; explicit flags win. Re-registering the same path is a no-op; a different path updates the entry in place.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--workspace, -w | string | "" | Workspace slug; defaults to workspaceSlug in the resolved waypoint.json. |
--project, -p | string | "" | Project slug; defaults to projectSlug in the resolved waypoint.json. |
--path | string | "" | Path to the project root; defaults to the walk-up result. |
cd /path/to/proj && waypoint project register
waypoint project unregister
Remove a (workspace, project) entry from the registry. Aliases: remove, rm.
waypoint project unregister [flags]
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--workspace, -w | string | "" | Workspace slug (required). |
--project, -p | string | "" | Project slug (required). |
waypoint project unregister -w acme -p marketplace
waypoint project list
List every registry entry. Alias: ls.
waypoint project list
Takes no flags. Output is a table with WORKSPACE / PROJECT / PATH / ADDED columns.
waypoint project list
waypoint project path
Print only the absolute path for a registered (workspace, project).
waypoint project path [flags]
Output is just the path, which makes it convenient for shell wrappers. If the entry isn't registered it exits non-zero with no stdout (the error goes to stderr), so a wrapper can chain || cleanly.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--workspace, -w | string | "" | Workspace slug (required). |
--project, -p | string | "" | Project slug (required). |
waypoint project path -w acme -p marketplace
# Shell wrapper to cd into a registered project
wp-cd() { cd "$(waypoint project path -w "$1" -p "$2")" || return; }
waypoint artifact
CLI fallback for the MCP artifact tools — for reading and writing artifacts when an MCP client isn't configured.
get and put mirror the MCP artifact.get / artifact.put tools exactly: they resolve (workspace, project) via the local registry, build the same composite store the MCP uses (dogfood / customer / local), and perform atomic blob + manifest writes. In customer mode the blob uploads to S3 immediately, so no separate waypoint push is needed.
The artifact group has one persistent flag inherited by every subcommand:
| Flag | Type | Default | Description |
|---|---|---|---|
--workflow | string | software | Workflow name. |
waypoint artifact get
Fetch an artifact via the same path as the MCP artifact.get tool.
waypoint artifact get --path <path> [flags]
Resolves the project, builds the composite store, looks up the manifest-pinned blob for --path, and prints it (or writes it to --out). Workspace and project default from the nearest waypoint.json.
Flags (plus inherited --workflow)
| Flag | Type | Default | Description |
|---|---|---|---|
--path | string | "" | Artifact path, extensionless (e.g. personas/alice). Required. |
--workspace | string | "" | Workspace slug; defaults from the nearest waypoint.json. |
--project | string | "" | Project slug; defaults from the nearest waypoint.json. |
--out | string | "" | Write content to this file instead of stdout. |
waypoint artifact get --path personas/alice
waypoint artifact put
Write an artifact via the same path as the MCP artifact.put tool.
waypoint artifact put --path <path> [flags]
Resolves the project, builds the store, uploads the blob (S3 in customer mode; local in dogfood/local), and atomically updates waypoint.json. The content source is one of --file, --payload, or stdin (when neither is set) — they're mutually exclusive. Output is a single JSON object {"path": ..., "hash": ...}.
Flags (plus inherited --workflow)
| Flag | Type | Default | Description |
|---|---|---|---|
--path | string | "" | Artifact path, extensionless (e.g. personas/alice). Required. |
--file | string | "" | Read content from this file (mutually exclusive with --payload). |
--payload | string | "" | Inline content (mutually exclusive with --file). |
--content-type | string | json | Content type: json, markdown, or yaml. |
--workspace | string | "" | Workspace slug; defaults from the nearest waypoint.json. |
--project | string | "" | Project slug; defaults from the nearest waypoint.json. |
waypoint artifact put --path personas/alice --file alice.json
echo '{"slug":"alice"}' | waypoint artifact put --path personas/alice
waypoint artifact put --path notes/readme --content-type markdown --payload "# Hi"
waypoint artifact rehash
Sync waypoint.json from the on-disk artifact tree (dogfood mode).
waypoint artifact rehash [flags]
Walks the on-disk tree (.waypoint/<workflow>/artifacts/), hashes every file, and syncs waypoint.json to match — adding entries for files with no manifest entry, updating entries whose hash changed, and removing entries whose file is gone. Follow with waypoint push to upload the new blobs.
Flags (plus inherited --workflow)
| Flag | Type | Default | Description |
|---|---|---|---|
--dry-run | bool | false | Print the changes without writing waypoint.json. |
waypoint artifact rehash --dry-run
waypoint artifact ping
Verify the MCP server starts and responds correctly.
waypoint artifact ping [flags]
Starts waypoint mcp serve as a subprocess, sends an MCP initialize handshake plus tools/list, and confirms the expected artifact tools (artifact.get, artifact.list, artifact.put, artifact.delete) are registered. Exits 0 on success, 1 on failure. Takes only the inherited --workflow flag.
When to use: To confirm the MCP server is healthy before a session that relies on artifact.put/get.
waypoint artifact ping
waypoint pull
Download remote artifact blobs into the local cache.
waypoint pull [flags]
pull reads waypoint.json, finds the artifact blobs missing from your local cache (~/.waypoint/cache/), and downloads only those from the service — content-addressed by hash and verified on receipt. Already-cached blobs are never re-fetched, and pull never modifies waypoint.json or the .waypoint/ tree. It's the cache-warming complement to push; run it after a git pull brings in teammates' artifacts.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--workflow | string | software | Workflow to warm. |
--workspace | string | "" | Workspace slug (overrides waypoint.json). |
--project | string | "" | Project slug (overrides waypoint.json). |
--cache-root | string | "" | Override the local cache directory (default ~/.waypoint/cache). |
--dry-run | bool | false | Print what would be downloaded without fetching. |
--json | bool | false | Emit structured JSON output. |
Requires: login.
When to use: Warm the cache so a subsequent validate doesn't make a per-artifact service round trip.
waypoint pull
waypoint pull --dry-run
waypoint push
Upload local artifact blobs to the Waypoint service.
waypoint push [flags]
push reads waypoint.json, asks the service which blobs it lacks, and uploads only those — content-addressed, so identical content already uploaded under any path is skipped.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--workflow | string | software | Workflow to push. |
--workspace | string | "" | Workspace slug (overrides waypoint.json). |
--project | string | "" | Project slug (overrides waypoint.json). |
--dry-run | bool | false | Print what would be uploaded without uploading. |
Requires: login.
When to use: Upload new or changed artifact blobs so the service has every blob waypoint.json names. The pre-push git hook runs this automatically before a git push reaches the remote, so others never see a hash without a blob.
waypoint push
waypoint push --dry-run
waypoint workflow types
Print a workflow's artifact types as type:pattern lines.
waypoint workflow types [<workflow>] [flags]
workflow types prints one type:pattern line per artifact type in the embedded metagraph, sorted by type id (the pattern is the path glob for that type). The optional positional <workflow> defaults to software. It takes no flags.
When to use: A machine-readable enumeration of the workflow's node types — used by tooling rather than parsing a workflow definition by hand.
waypoint workflow types
waypoint workflow types software
waypoint workflow also has an update subcommand, but it is hidden / pre-alpha and not part of the stable CLI surface. See Experimental / hidden commands.
waypoint schema
Print the embedded JSON Schema for an artifact type.
waypoint schema [name] [flags]
schema prints the JSON Schema bundled with the CLI binary for a given artifact type (for example persona, feature, or aggregate). Schemas come from the embedded workflows/<workflow>/schemas/ tree — there is no per-project schemas/ folder. The positional name is required unless you pass --list.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--workflow | string | software | Workflow the schema belongs to. |
--list | bool | false | List all schema names in the workflow instead of printing one. |
When to use: Discover the available artifact types and their exact field contracts when authoring artifacts by hand.
waypoint schema persona
waypoint schema --workflow software --list
waypoint schema --workflow marketing audience