w17ctl

w17ctl — the wandering-compiler developer CLI

w17ctl is the single client and entrypoint for a w17 project. Everything a developer or a pipeline does — scaffolding, change requests, codegen, applying migrations, running the local stack — goes through it.

w17ctl <command> --help     # context-sensitive help for any command

Install

curl -fsSL https://get.w17.dev/install.sh | sh -s -- --pre

Installs into /usr/local/bin, verifying the download against the release's SHA256SUMS first — always, with no flag to skip it.

--pre is needed while w17ctl is in release candidates: latest means the newest STABLE release, and there is not one yet. Drop it once v0.1.0 ships.

curl -fsSL https://get.w17.dev/install.sh | sh -s -- --version v0.1.0-rc.1 --dir ~/bin

Or take a .tar.gz straight from Releases — linux and macOS, amd64 and arm64. There is nothing to configure after unpacking: w17ctl is a single static binary and keeps its state in ~/.w17/.

w17ctl version           # what you have, and which console it defaults to
w17ctl version --check   # …and whether a newer release exists
w17ctl update            # upgrade in place, no install command to paste
w17ctl login             # point it at a console

Upgrading

w17ctl update replaces this binary with the newest release, into the directory it is already running from. You do not have to remember the install line, and you do not have to know which tag is newest.

It invokes the installer above rather than resolving the release itself, which is the point rather than an implementation detail: one place knows which release is newest, and that place already verifies the download against SHA256SUMS. Prereleases are included automatically while your binary is itself a prerelease — which is every binary today, since latest means the newest stable release and there is not one yet. --stable opts out, --version <tag> pins, --dry-run only reports what would be installed.

w17ctl version --check asks the same question without changing anything. It is a flag rather than part of version because it costs a network call, and version has to keep working with no network — it is what you run when something is already wrong.

w17ctl version prints the console address compiled into the binary. That is only the LAST resort in the resolution order — --console, then the console you are logged into, then this default — so logging in is what decides where commands go.

Start here — you + a coding agent

w17 is built to be driven by a coding agent (Claude Code, …). Two steps:

1. Log in once:

w17ctl login

2. Paste this to your coding agent ONCE to onboard it (it's context, not a task — the point is that the agent learns w17 and records it, so every later session already knows the drill and you can just ask for features):

This project is built with w17 (wandering-compiler): a declarative compiler where
you declare schemas, DB models, queries, mutations, events, and APIs as proto +
annotations, and it generates the gRPC binaries, DB layer, SQL migrations,
gateways, and clients — the only hand-written code is the business-handler bodies.

Do this now to learn how it works:
1. Run `w17ctl guide`. It writes AGENTS.md (how to drive the w17ctl CLI) and
   w17/specs/ (the platform reference: the annotation catalog, the generation
   model, the event system, the directory structure).
2. Read AGENTS.md and ALL of w17/specs/.
3. If it isn't already recorded there, note the essentials in this project's
   CLAUDE.md / AGENTS.md and in your long-term memory, so future sessions start
   from it: this is a w17 project driven via w17ctl; you change behaviour by
   editing proto/ and running `w17ctl codegen`, NEVER by hand-editing generated
   files; only business-handler bodies are hand-written; the full platform
   reference is w17/specs/ (refresh with `w17ctl guide`).

From now on I'll just ask you to implement features. Always follow the w17 way:
declare then generate, hand-write only handler bodies, and re-read w17/specs/ when
unsure about an annotation or the architecture. Do not invent DB or gRPC plumbing
by hand.

That's it — the agent learns w17 once, records it, and from then on you just describe features. The platform reference is regenerated by the compiler, so it always matches your w17 version. Everything below is reference detail you'll rarely need to read.

Mental model — what w17ctl is (and isn't)

w17ctl is deliberately dumb. It holds no compiler know-how. Every real decision — compiling the proto IR, planning SQL migrations, running the compatibility engine, signing the lock — happens on the console (the backend), reached over a gRPC API. w17ctl's whole job is three things:

1. Transport — talk to the console's gRPC API (always over TLS).
2. Local disk — read/write the project's files: the signed w17/lock.yaml, generated code, snapshots, and the dev-machine config under ~/.w17/.
3. Docker — drive the local compose stack.

   you / CI  ──▶  w17ctl  ──▶  console gRPC API  ──▶  the compiler core
              (transport +      (all the know-how)     (private IP)
               disk + docker)
        ◀──  finished artifacts the client writes verbatim  ──

So when a command "generates code" or "plans a migration", w17ctl is uploading your inputs and applying what the console sends back — it never compiles anything itself. This is why the client is small, publishable, and safe to run in CI: it can't produce a broken or forged artifact, only apply a console-signed one.

w17ctl finds your project by walking parent directories to the nearest w17/lock.yaml, so you can run it from anywhere inside the tree.

State it keeps

The certificate committed in this repo

internal/core/devca.crt is a dev CA certificate, and it is meant to be here. Only the public half ships — the private key is dev-only and never leaves the monorepo — and the client trusts it for loopback dials only, so that w17ctl login localhost:… can verify your local dev terminator with no environment set up. It grants nothing against a remote console: a dial to anything but loopback goes through the system trust store like any other TLS client.

Command reference

Getting started

| version [--check] | Print this binary's version, commit, build date and compiled-in console address. --check also asks the installer which release is newest and says whether you are behind — one network call, and it reports rather than fails when there is none. | | update | Upgrade this binary in place, into the directory it runs from. Invokes install.sh rather than resolving the release itself, so the download is verified against SHA256SUMS and there is only one implementation of "which release is newest". --stable refuses prereleases, --version <tag> pins, --dir targets elsewhere, --dry-run reports without installing. |

Auth & organizations

Talk to a console and pick your org scope. Login is a single gRPC call to the console (the same endpoint every other command dials) — email + password in, bearer out.

Unattended callers don't log in. CI and a production deployment have no terminal to run login on and no home directory worth writing a credential into. They set two variables instead:

The second is what makes the first safe: a token is presented only to the console it is bound to, never to a host named by a --console flag. Without the binding it is presented nowhere — which arrives as invalid credentials, so w17ctl warns on stderr when a token is set and then not sent. (A build with a compiled-in DefaultConsoleAddr — every released binary — uses that when W17_CONSOLE_ADDR is unset.)

Nothing here is required locally: with no token set, the credential store answers exactly as before.

Project setup & scaffolding

These edit the signed lock and write starter proto files. No codegen — they prepare inputs.

Codegen & schema

The compiler-driven commands. Each uploads your protos to the console and writes back what it returns.

Schema lifecycle — the review flow (PR analog)

Snapshots + a compatibility engine + a review/merge gate. Git branch → initiative (main/master → trunk).

Local development

Docker + local project ergonomics. This is where w17ctl drives compose.

Why the split matters (design invariant)

The compiler's IP and all trust-bearing crypto (lock signing) live on the console, never in the client. w17ctl ships as a standalone public tool and imports zero private compiler code — only the public sdk/go module + the console's gRPC contracts. That's what lets the same minimal client both scaffold a project on your laptop and gate a production release in CI: it verifies + applies console-signed artifacts, and can't forge one.

This repository is an export

The sources here are generated from the private monorepo where w17ctl is developed, which is why you will find no _test.go files and comments that speak of test seams ("indirected so tests can…"). The tests exist; they live beside the code they cover, in the monorepo, and they run there before every release — the same pipeline also builds this exported tree and fails the release if it does not compile with zero private compiler code in its import graph.

So nothing here is untested, but nothing here is testable by you either. If you hit a bug, a description that reproduces it is worth as much to us as a patch would be: we turn it into a regression test in the tree where the test actually runs.