CLI reference

Status: the Rust compiler (rust/, cargo build --release -p sky) is the Sky compiler (the earlier compilers were removed in v0.29.0). Verified by the example sweep + compiler test suite (cargo test + xtask gates). See ../history/compiler/versions.md for the changelog.

Every sky subcommand. Run sky --help for the authoritative list.

Build & run

sky init [name] [--production]

Scaffolds a new project in name/ (default sky-project): sky.toml, src/Main.sky, .gitignore, .gitattributes, .dockerignore, docker-compose.yml, .env.example, AGENTS.md and CLAUDE.md. --production (aliases --postgres, --prod) makes the Postgres configuration active from the start.

The .gitattributes makes GitHub highlight Sky source as Elm, because GitHub Linguist has no Sky grammar yet and Sky syntax is Elm:

# GitHub Linguist has no Sky grammar yet. Sky syntax is Elm, so highlight it as Elm.
*.sky linguist-language=Elm
*.skyi linguist-language=Elm

Every variant writes it (since v0.27.12). A .gitattributes the directory already has is kept unchanged. For an older project, add the three lines by hand.

sky build [path]

Compile a Sky source file to a Go binary under sky-out/.

sky build src/Main.sky

Pipeline:

  1. Parse sky.toml for [go.dependencies] and [dependencies].
  2. Auto-regenerate any missing FFI bindings in .skycache/.
  3. Resolve modules, type-check, lower to Go under sky-out/.
  4. Invoke go build → sky-out/app (or the bin name set in sky.toml).

Client entries AUTO-SPLIT. When the entry resolves to a client app — a Std.App (App.app / App.run) built for a client target (--target web:app / mobile:* / tablet:*, from which the build synthesises the split), or a low-level Spa.app — sky build src/Main.sky derives a wasm frontend + native backend + shared codec under .split/ (override with --out) and builds both — the split you would otherwise run sky spa-split … --build for by hand. sky run src/Main.sky does the same and then runs the backend (it serves the frontend

--target and --embed compose with the split: --target <t> picks the frontend delivery shell, --embed bundles PostgreSQL into the backend, and they combine (sky build --embed --target ios src/Main.sky). Three things skip the split: sky check (type-checks the shared source directly), an explicit --wasm (a raw client build, below), and a project already generated by a prior split (its sky.toml carries a [spa] generated = true marker, so building the generated frontend — itself a client entry — never re-splits). For the explicit form that keeps the artefacts at a chosen path, see sky spa-split.

--wasm compiles a Sky.Spa client for the browser (GOOS=js GOARCH=wasm) instead of a native binary, writing sky-out/main.wasm + sky-out/wasm_exec.js (the matching loader). Standard-Go wasm has full reflect, so it runs in any browser / WKWebView / Android WebView.

sky build --wasm src/Main.sky        # -> sky-out/main.wasm + wasm_exec.js

--target <t> builds the wasm client (implies --wasm), always stages the servable dist/ bundle (index.html + main.wasm + wasm_exec.js), and then — for a native surface — generates a shell and builds it into a real artifact. Each shell is a thin native window over the SAME wasm client, loading it from your backend; client and server stay separate, only the shell is native.

--targetProducesNotes
web / tabletdist/ ready to serveserve statically, or same-origin via Server.static "/" "../dist"; tablet == responsive web
desktopsky-out/desktop/<app> (native binary)generates a Std.Webview.url shell + builds it (cgo — WKWebView / WebView2 / webkit2gtk)
iossky-out/ios/build/<App>.appgenerates a SwiftUI + WKWebView shell + builds it for the Simulator (swiftc). Requires full Xcode + the iOS Simulator runtime; missing → warns + exits
androidsky-out/android/build/<app>.apk (signed)generates a WebView shell + builds a signed APK (aapt2 → javac → d8 → zipalign → apksigner, no Gradle). Requires the Android SDK (ANDROID_HOME / adb) + a JDK; missing → warns + exits
sky build --target web src/Main.sky      # -> dist/ (serve it)
sky build --target desktop src/Main.sky  # -> sky-out/desktop/<app>  (run after starting your backend)
sky build --target ios src/Main.sky      # -> sky-out/ios/build/<App>.app  (xcrun simctl install booted …)
sky build --target android src/Main.sky  # -> sky-out/android/build/<app>.apk  (adb install -r …)

The generated shells point at http://127.0.0.1:8951/ (desktop, via PORT), http://localhost:8951/ (iOS Simulator — shares the host network), and http://10.0.2.2:8951/ (Android emulator's host alias) — start your backend first. For a real device / production, host the dist/ bundle from your backend over https and point the shell there. For ios / android the platform toolchain is checked before the (slower) build, so a missing SDK fails fast with an install hint rather than half-building. The hand-written reference shells live in examples/60-spa-todos/{mobile-ios,mobile-android,desktop} if you want to eject and customize (icons, permissions, package id).

--embed bundles a PostgreSQL distribution into the binary, so ./sky-out/app --embed is a self-contained app and database on a bare host — one file, no system PostgreSQL, no DATABASE_URL.

sky build --embed src/Main.sky
./sky-out/app --embed                       # starts its own cluster
./sky-out/app --embed --data-dir /var/lib/myapp

--embed belongs on sky build, not on sky run — see below.

--timings (or SKY_TIMINGS=1 in the environment) prints a table of the build's phases, each with its wall-clock and the process's peak resident memory when the phase ended, to stderr when the build ends: loading the sources, parse, canonicalise + typecheck, lower + emit Go, writing sky-out/, go build, and for a client build the split, both legs, the dist/ bundle and its precompression. A split build runs its backend and frontend legs as child sky builds; each leg prints its own table under its own == … == header, and the parent's table gives the wall-clock of each leg. sky check --timings works the same way. Use it to see where a slow build spends its time before you report it.

Under the table, note: front end: N source load(s), M type check(s) counts how many times the process loaded a program's sources and type-checked its modules. A build runs the front end once for each program it compiles. A direct Spa.app entry is checked once, and the split analyses that same checked program, so the parent reports one of each. A --target web:app build checks your own entry and then splits the client entry it derives from it, which is a second program, so the parent reports two of each.

sky build --timings --target web:app src/Main.sky

What a rebuild reuses. Go's build cache keys on content, and Sky's emitted Go is deterministic, so an unchanged module is never recompiled. A client build keeps each leg's sky-out/ between builds, so a rebuild whose Go did not change does not re-link the backend or the wasm client either. The .gz / .br variants in dist/ are cached by the SHA-256 of the file they compress (in ~/.cache/sky/precompress, or under $XDG_CACHE_HOME), so brotli runs only when the wasm bytes change. The bundle's assets (the wasm, wasm_exec.js, the boot script) are compressed at once, gzip and brotli each, and in a client build the parent sky build compresses them while the backend leg is still building, when the available memory holds both (brotli is counted at 64 MB, three times the input, and 190 MB per part it compresses at once). The .gz is the bytes of gzip -9. The .br is written by sky itself (the brotli crate, no tool needed): quality 11 with a 16 MB window, a large file split into up to 8 parts of 6 MB or more that are compressed at once, each part able to refer back into the parts before it. On a 52 MB wasm that is 26 s against 81 s for brotli -q 11, for a file 0.3% larger; any brotli decoder reads it. A cached result is used only after it decompresses to the file. sky run and sky watch do not write them at all: their backend serves the bundle itself and compresses on the fly.

--precompress=max|fast|off (or SKY_PRECOMPRESS=max|fast|off; the flag wins) sets how much work goes into the .gz / .br:

Levelbrotligzip52 MB wasm: time, .br size
max (default)quality 11, parallel-926 s, 2.77 MB
fastquality 9, one thread-6~1.5 s, 3.25 MB (+18%)
offnonenone0 s; the server compresses on the fly

Use fast (or off) for a quick edit-rebuild loop of a production-shaped build, and max for what you deploy. max starts up to 8 brotli parts at once (1.56 GB peak on a 52 MB wasm). When the available memory is known and holds less than that need (64 MB, three times the input and 190 MB per part) plus 1 GB kept free, the build warns and writes the fast variants instead. The number of parts depends only on the file's length, so max bytes are the same on every machine: a machine short of memory writes fast bytes under the fast name and cache key, and the manifest records "level": "fast". --no-precompress is --precompress=off. An unknown level is an error. Every level first removes the .br / .gz of each asset it manages (the wasm, wasm_exec.js, the boot script) and the manifest, so off leaves none behind. The build then lists what it wrote in dist/sky-precompress.json: each asset's size and SHA-256, and those of its .br / .gz. The Sky backend serves a .br / .gz itself only when a request accepts it and the manifest lists it with the size and SHA-256 the files still have (hashed once per file version per process). The manifest is read by the backend and is not served: a request for it is answered as for a file that does not exist (404, or the app's NotFound page on the Sky.Spa / mount). A Range request that accepts the encoding ranges over that file, with Content-Encoding on the 206; anything else gets the raw file, gzipped on the fly. A .gz / .br that the build did not write (one committed in an app's own static dir) is never served.

A new directory reuses the cache too. Every go build Sky runs passes -trimpath, so a compiled package's cache key does not include the directory it was compiled in: the same program in a new checkout, a CI runner's workspace, each leg of a client build, or a desktop shell compiles no package again. One effect on the built app: a panic stack trace names files by module path (sky-app/main.go, sky-app/rt/live.go) instead of the build machine's absolute path. Function names and line numbers are unchanged, and a go build error still names ./main.go:LINE:COL. --no-trimpath (or SKY_GO_TRIMPATH=0) builds without it. sky run --profile builds without it on its own, because pprof -list / pprof -http source views and Delve find the sources by the absolute paths in the binary.

Serial or parallel legs. A leg needs its own sky process (which stays in memory while its go build runs) plus its largest Go compile. The backend and frontend legs of a client build run in parallel only when the machine's available memory holds both legs' sky and Go peaks plus a 1 GB reserve; otherwise they run one after the other. Available memory is free + inactive + speculative pages on macOS (vm_stat), MemAvailable on Linux, capped by the cgroup's remaining limit in a container, free + inactive pages on FreeBSD (sysctl), and the available physical memory on Windows (GlobalMemoryStatusEx). The plan estimates each leg from the size of its generated sources, and raises each figure to the peak the leg measured on a previous build when that was more (each leg keeps the largest it has seen in its own sky-out/, .sky-front-peak-bytes and .sky-go-peak-bytes, which covers main's compile and the link; a record from a compiler before v0.25.18 is ignored). When memory cannot be read, the legs run serially. SKY_BUILD_SERIAL=1 forces serial and SKY_BUILD_PARALLEL=1 forces parallel. The build prints its decision in the == building … == line and in the --timings report.

An app whose backend renders the first page (SSR) names the frontend's main.<hash>.wasm in that page, and the hash exists only once the frontend leg has built. The backend gets the name through its generated sky-out/skybuildinfo package (a small package of its own), not through its main package. So in parallel the backend leg builds while the frontend leg builds, main included; when the frontend ends, the parent writes the name to the backend leg's standard input (a pipe that belongs to this build alone), and the backend recompiles only that small package and links (the --timings rows go build (native, before the frontend's wasm name) and wait for the frontend's wasm name). A build whose frontend did not change links nothing new. Serially, the frontend builds first and the backend reads the name as it starts. If the frontend fails, or its thread in the parent ends early, the backend is still built, without a name: its page then finds the wasm by scanning ../frontend/dist at run time, as before. If the parent sky build exits (Ctrl-C, a crash), the pipe closes and the backend stops waiting at once, with an error. The wait ends at most 600 s after the backend leg started. A backend built on its own (cd .split/backend && sky build) keeps the name its last build linked.

The wasm client links a constant build stamp (nothing in the browser reads it), so its bytes, and its main.<hash>.wasm name, depend on the app's source only: a new commit does not change them, the .gz / .br cache hits, browsers keep their cached copy, and the backend has no new name to link. The server still reports the commit and build time at /_sky/buildinfo.

Go compile parallelism. go build compiles up to one package per CPU at the same time. Inside one go build the generated main package always compiles alone (every other package is one of its dependencies), so a limit on -p protects no memory from main: it only limits the dependency compiles that run beside one another. So sky build sizes -p from the dependency compiles: the largest one (the generated sky-out/skyffi package for a project with large Go FFI bindings, estimated from its size, else about 0.7 GB, or the largest dependency peak measured on an earlier build of the project, sky-out/.sky-go-dep-peak-bytes) plus as many others of about 0.25 GB each as the available memory holds after the 1 GB reserve (measured at Go's default -p 8 on darwin/arm64, the compiles beside the largest one average about 0.1 GB). When that is one per CPU, Go keeps its default. Below 6 GB of room (an 8 GB machine) the 0.25 GB figure is not trusted: each other compile counts about 0.7 GB and -p is at most 4. A 16 GB machine keeps Go's default. The generated skyffi package is a special case: it imports the runtime and every bound Go package, so Go compiles it after all of them, and only the console package and the build stamp can compile beside it, whatever -p is. It must fit with the console compile beside it (else -p 1), and -p is sized from the ordinary compiles that run before it. Each go build is measured on its own (its own child process, never the largest of every child before it), and a build records a dependency peak only when its dependencies compiled and its main did not (Go's action graph says which ran), so a cache hit, a main compile, or a build that compiled only the build stamp package never sets it. Unknown memory builds one package at a time. When a client build runs its legs in parallel, it sets each leg's -p from the memory both legs share. --go-jobs <n> (or SKY_GO_BUILD_JOBS=<n>) sets -p <n> yourself (auto decides as above), and a -p already in GOFLAGS is kept. The decision is printed under the --timings table as go build: -p ….

Further build-speed changes were studied and not made in v0.27.9: one Go package per Sky module, a parallel front end with a cached stdlib world, a linear unifier, one front-end load on the --target web:app path, and fast brotli by default for edit rebuilds. docs/perf/build-speed-decisions.md records, for each, what was measured, the expected gain, the risk and what would make it worth doing.

Build identity. The app's version, commit and build time are automatic: no flag, no environment variable, no CI step. sky build writes them into generated Go source (the sky-out/skybuildinfo/ package), so any go build of sky-out/ carries them, including your own cross-compile (CGO_ENABLED=0 GOOS=linux go build .). They are resolved once, at the project root, and every server leg of the build embeds the same values (a Sky.Spa wasm client links a constant stamp, so that its bytes depend on the source only). The commit is, first match wins: SKY_BUILD_COMMIT (optional override); git rev-parse HEAD in the project directory or any parent; the commit variable your CI sets by default (GITHUB_SHA, CI_COMMIT_SHA, BITBUCKET_COMMIT, CIRCLE_SHA1, BUILDKITE_COMMIT, GIT_COMMIT, SOURCE_VERSION, COMMIT_SHA, VERCEL_GIT_COMMIT_SHA, RENDER_GIT_COMMIT, CF_PAGES_COMMIT_SHA, DRONE_COMMIT_SHA, TRAVIS_COMMIT, SEMAPHORE_GIT_SHA, BUILD_SOURCEVERSION; a non-hex value is skipped); else src-<12 hex>, a hash of the source tree, sky.toml and sky.lock. The build time (RFC 3339 UTC) is SKY_BUILD_EPOCH=<unix seconds> (optional override), else the commit time of HEAD when git resolves, else the newest modification time of those source files (git archive | tar -x sets it to the commit time). It is never the wall clock, because a per-build value would re-link the binary on every no-change rebuild. The app reports them at /_sky/buildinfo (with source: git, ci:<VAR>, content, override or ldflags) and in the Sky Console header. Your own go build -ldflags "-X sky-app/rt.buildCommit=..." (also buildAt, skyVersion) still wins, field by field. See docs/observability.md.

sky package --release --target <t> [--upload testflight [--ipa <file>]] [path]

Builds the store / distribution artefact for a native shell into sky-out/release/: a signed .ipa for mobile:ios (unsigned -unsigned.ipa without signing configured), a release .apk signed with your upload key plus an .aab when bundletool is on PATH for mobile:android, and a .app + .dmg for desktop:mac. It runs sky build --target <t> in release mode (device build, release signing, no web inspector).

Signing comes from the environment only (SKY_IOS_SIGN_IDENTITY, SKY_IOS_PROVISIONING_PROFILE, SKY_ANDROID_KEYSTORE, SKY_ANDROID_KEYSTORE_PASSWORD, SKY_ANDROID_KEY_ALIAS, SKY_ANDROID_KEY_PASSWORD, SKY_MACOS_SIGN_IDENTITY, SKY_MACOS_PROVISIONING_PROFILE; see docs/sky-toml.md). Before any build it refuses: no --release (exit 2), a target that is not a native shell, a local or plain-http backend address, a generic permission purpose string, missing Android signing, and an iOS identity without a provisioning profile. Guide: docs/skyapp/native.md.

--upload testflight (with --target mobile:ios or tablet:ipad, on macOS with Xcode) then validates the signed .ipa and uploads it to App Store Connect with xcrun altool, which makes it a TestFlight build. The API key comes from SKY_ASC_KEY_ID, SKY_ASC_ISSUER_ID and SKY_ASC_KEY_PATH (the .p8, which never goes on a command line). --ipa <file> uploads an .ipa packaged earlier, without a build. Before any build or network call it refuses an unknown destination or a non-iOS target (exit 2), a missing Bundle.withId or Bundle.withBuild, a missing key variable or key file, and a build that is not signed for App Store distribution (exit 1). Apple's errors are printed as Apple wrote them with the fix, and the exit status is 1. Guide: docs/skyapp/native.md#upload-to-testflight--sky-package---upload-testflight.

sky spa-split <path> --out <dir> [--build | --target <t>]

The explicit Sky.Spa auto-split generator — the form of the split that sky build / sky run invoke for you (see above); reach for spa-split directly when you want the generated shared//backend//frontend/ kept at a chosen --out path. It takes ONE Sky.Spa project whose update runs effects inline, and generates a wasm frontend + native stateless backend + a shared wire contract — no hand-written API. The compiler infers the client/server split from effects (the rule is dead simple: pure → client, any effect → server; the client is 100 % pure UI), so a database/file/secret/auth value or function can never reach the browser — it is a build failure if it could (a fail-closed guard over every kernel family). Server branches become generated RPC endpoints; Cmd.publish fans out to subscribed clients over SSE (server→client push).

The entry is a Std.Spa app (main = Spa.app …) or a Std.App app (main = App.run app). A Std.App entry is split as sky build --target web:app splits it: the Spa.app entry is synthesised from the App value and staged under .skyapp/spa-split/, and your src/ is not changed.

sky spa-split src/Main.sky --out dist/split                 # generate only
sky spa-split src/Main.sky --out dist/split --build         # + build backend + web frontend
sky spa-split src/Main.sky --out dist/split --target desktop # + native desktop shell
sky spa-split src/Main.sky --out dist/split --build --embed  # + PostgreSQL bundled in the backend

The generated backend serves the frontend, the /_rpc/<Msg> endpoints, and GET /_sky/sub (SSE). Client→server is HTTP RPC, server→client is SSE — same origin, so no CORS and a trivial connect-src 'self' CSP. Each /_rpc/<Msg> is a Server.rpc route (same-origin application/json POSTs only), and /_sky/sub streams a topic only when the app's subscriptions for the verified session name it (auto-split.md §21). Inspect the derived split first with sky spa-partition — it prints each branch CLIENT/SERVER with the reason. (In-process broker = single replica; SKY_LIVE_BROKER_URL gives cross-replica push, same as Sky.Live.) Design + internals: docs/skyspa/auto-split.md.

sky spa-partition <path>

Read-only: prints the inferred client/server partition of a Sky.Spa update — each branch as CLIENT or SERVER with the taint reason, each server branch's RPC inputs/outputs, and the server-tainted top-level bindings. Answers "what runs where, and why" before you generate anything with sky spa-split. Nothing is hidden: the split is inferred but always inspectable.

sky run [path]

sky build + execute the resulting binary. On a Sky.Spa entry it auto-splits (as sky build does) and runs the backend, which serves the frontend + /_rpc same-origin; --embed and --target compose (sky run --embed src/Main.sky runs the backend with its own bundled PostgreSQL).

Program arguments. Everything after -- goes to the program, as with go run and cargo run: sky run src/Main.sky -- a "b c" gives System.args () the two arguments a and b c. A flag after -- is the program's, so sky run src/Main.sky -- --help passes --help to it. Without -- the program gets no arguments. sky run --help (or -h) before any -- prints the sky run usage and builds nothing.

For a plain (non-Spa) app in development you do not need --embed (and sky run --embed on such an app is refused with a pointer): set [database] embedded = true in sky.toml and sky run starts a local cluster, injects the DSN, and stops it on exit. See sky db start.

--profile turns on runtime profiling of the app (not the compiler) — for when an app hangs, spins the CPU, or eats memory and you can't tell which. It writes a profile/ directory next to your project on stop:

FileWhat
REPORT.mdHuman-readable summary: stop reason (exit / panic / signal / hang), wall time, goroutine count + a state breakdown, and a ⚠️ Likely hang verdict when goroutines sit blocked. Start here.
cpu.pprofCPU profile for the whole run — go tool pprof -http=: cpu.pprof for a flame graph.
heap.pprofHeap profile at stop — go tool pprof -http=: heap.pprof.
goroutines.txtFull goroutine stack dump; the top frame of each blocked goroutine is where it's stuck.

Options:

sky run src/Main.sky --profile                     # profile until exit / Ctrl-C
sky run src/Main.sky --profile --profile-timeout 30s   # + auto-dump if it hangs

The stop fires whichever comes first: normal exit / panic, a signal (SIGINT/SIGTERM/SIGQUIT), or the timeout. --profile off means zero overhead — profiling is armed purely by an env var the flag sets, and the emitted Go is byte-identical either way.

sky verify [project]

The one-command pre-release gate for a project. Run inside a project dir (or pass its path) and it runs, in order, stopping non-zero on the first failure:

  1. fmt — every .sky file under the source root + tests/ is already sky fmt-clean.
  2. check — type-checks + go builds and emits the production binary (sky check ≡ sky build minus the artefact, so this one build covers both).
  3. stores — when the entry module exposes db (a Store.Project), a scratch build runs Store.dumpSchema db and fails on a Store builder problem: a builder that names an unknown column, an invalid table name or a primary key that is not a column. That problem makes every verb on the store fail at run time, so the gate stops it before a deploy. A db that is not a Store.Project is skipped with a note. Any other failure of the scratch build fails the step with the build error.
  4. test — every tests/*.sky suite passes.
sky verify           # gate the current project
sky verify path/to/app

A library package has no entry to build: its sky.toml names no entry, and it declares a [lib] table or has no Main module. For one, the check step type-checks and go builds every module under the source root (through a generated entry that imports each of them, built in a scratch directory), the tests run as usual, and only the entry binary is skipped:

  ✓ fmt      (2 file(s) clean)
  ✓ check    (library: 1 module(s) type-check and build; no entry binary)
  ✓ tests    (1 suite(s) passed)

In the compiler repo (a dir with examples/), sky verify instead builds AND runs every example — the runtime smoke sweep. sky verify --help documents both modes.

sky check [path]

Fully validate the program. sky check is a strict superset of sky build: it runs parsing, canonicalisation, HM inference, Go codegen, and invokes go build on the emitted output — without producing a runnable binary. If sky build would fail, sky check fails with the same error. This is the soundness gate — editor integrations should use it directly.

sky check <module.sky> on a module that is not a program entry (it defines no main and no Std.App app) checks that module and what it imports the way a library check does: it type-checks, lowers and go builds them, and prints Checked module <Name> …. The program entry is checked by sky check with no path, or by naming the entry file.

Machine-readable output: --format json

sky check, sky build, sky test and sky fmt --check take --format json (or --format=json; --format text is the default). Stdout then carries only NDJSON: one JSON object per line. The human text (progress, the Elm-style error blocks, a test suite's ok / FAIL lines) goes to stderr. The exit code is the same as in text mode (sky test: 0 all passed, 1 a test failed, 2 nothing ran).

sky check --format json src/Main.sky
{"kind":"diagnostic","schema":1,"file":"src/Main.sky","range":{"start":{"line":8,"character":4},"end":{"line":8,"character":10}},"severity":"error","code":"E2001","message":"[x] type mismatch: `String` vs `Int`","source":"sky"}
{"kind":"summary","schema":1,"command":"check","ok":false,"errors":1,"warnings":0,"durationMs":146,"root":"/home/me/app"}

Every line has "schema": 1 and a "kind". The schema number changes only when a field changes meaning or type; a new field does not change it.

kindFields
diagnosticfile: the path relative to the project root (root on the summary), /-separated, or null. range: start / end, each {line, character}, 0-based, character in UTF-16 code units (the LSP Range), or null. severity: error, warning or info. code: the Sky error code (E2001) or null. message. source: sky or go. relatedInformation (only when present): a list of {file, range, message}. suggestion (only when present): the fix hint the text mode prints as Try: …; a v0.27.0 hint ends with its see docs/migration/v0.27.md#… link. half (a Sky.Spa sky build only): frontend or backend, the split project the diagnostic came from.
testsky test only, one per case: suite (the enclosing Test.suite labels joined with >, or the test module's name for a top-level case), name (the case's own name), fullName (as the human output prints it), status (pass or fail), message (on a failure), durationMs (null: Sky.Test runs every case in one pure pass, with no clock between cases).
summaryAlways exactly one, always the last line: command, ok (the exit code was 0), errors and warnings (the counts of the diagnostic lines above), durationMs, root (the absolute project directory). sky test adds total, passed, failed, skipped (always 0; Sky.Test has no skip) and exitCode.

The diagnostics are the same values the text mode prints, so the two modes report the same errors. A parse, name or type diagnostic has the location of its primary label. A lowering warning or error (the memoised-value lint, an unresolved Go-FFI call, an over-applied kernel, an internal compiler error) has the location of the expression being lowered when it was raised, else of the definition's name; the text mode prints it as src/Main.sky:11:1: …. A go build failure is reported against the Go file go named (sky-out/main.go, or a file in a local Go path dependency) with source: "go", because the generated Go carries no map back to the Sky source.

file and range are null only for a diagnostic that is about the program or the project as a whole and so has no source node:

A failing run that produced no error line of its own gets one that points at stderr, so ok: false always comes with a reason.

Sky.Spa builds. sky build of a Sky.Spa entry checks the app's own source first (the same front half sky check runs), so an error in the app is reported against src/… in both output modes. It then builds the two generated projects of the auto-split. In json mode each of those builds runs with --format json and its diagnostics are relayed with an extra key, "half": "frontend" or "half": "backend" (an added key, so the schema stays 1). A diagnostic in a module the split copied unchanged is reported against the app's own file (src/Store.sky); one in a generated or rewritten file is reported against that file's real path (.split/backend/src/Main.sky). A module both halves compile can report the same warning once per half.

sky fmt --format json needs --check: it reports, it never rewrites.

sky watch [path]

File-watch-driven hot rebuild + restart. Watched scope is a strict allowlist: sky.toml + the entry-point's directory (recursive .sky walk) + tests/ at the project root if present. Generated dirs (sky-out/, .skycache/, .skydeps/, .skyapp/, .split/, node_modules/, .git/) are excluded.

A Std.App entry (main = App.run app) is built for the sky.toml [app] target, else web, as sky run builds it. With [database] embedded = true the spawned app gets the embedded cluster's DSN on every restart, on every target.

sky watch                           # entry: src/Main.sky
sky watch src/Main.sky              # explicit entry
sky watch --no-run                  # rebuild only (don't spawn)
sky watch --clear                   # clear screen between rebuilds
sky watch --interval=200            # poll interval ms (default 200)
sky watch --debounce=150            # debounce after a change (default 150)
sky watch --kill-timeout=3000       # SIGTERM grace before SIGKILL
sky watch --watch=docs/notes.md     # additional path (repeatable)

Build-error policy: on a failing rebuild, the previously-running binary stays alive. The next successful build kills + respawns. A typo halfway through a save doesn't tear down the dev session.

Caches reused: .skycache/source.hash (full short-circuit on unchanged source), .skycache/lowered/ (per-module IR), .skycache/ffi/*.skyi (HM types — never regenerated by watch). Typical warm rebuild: 1-3 s.

Signals: Ctrl-C and SIGTERM both go through the clean-teardown path. Sky.Live's SSE handshake auto-reconnects post-restart (banner shows "Reconnecting…" for ~1 s then clears).

sky doc [target] [--list] [--serve] [--tui] [--port N]

Browsable API documentation for the Sky stdlib + project + deps. Four modes:

sky doc Sky.Core.String          # terminal: list every symbol with its HM signature
sky doc List                     # shorthand for Sky.Core.List
sky doc --list                   # print every documented module
sky doc --serve                  # HTTP doc server (auto-opens browser)
sky doc --serve --port 8081      # custom port
sky doc --tui                    # interactive terminal doc browser (Sky.Tui)

--serve and --tui are mutually exclusive — --serve runs the Sky.Http.Server bundle; --tui runs the Sky.Tui bundle. Both consume the same on-disk catalogue rendered to .skycache/doc-out/ under the project root.

Which stdlib. Inside the Sky repository (a directory with sky-stdlib/ and runtime-go/ above the working directory) sky doc reads the working-tree sky-stdlib/, so it shows edits that are not released yet. Anywhere else it reads the stdlib embedded in the sky binary. The first line of the output names the source: stdlib: working tree (<repo>/sky-stdlib) or stdlib: embedded in this sky binary. A record type alias is printed with its fields (type alias Chunk = { data : String , … }).

The HTTP server (default :8080) renders:

The server is a Sky.Live mini-app bundled into the compiler binary (sky-bundled/doc/), spawned as a child + reverse-proxied behind the sky doc --serve entry point.

--tui runs the Sky.Tui sibling (sky-bundled/doc/src/MainTui.sky) which reads the same JSON catalogue and renders an interactive terminal view: ↑/↓ navigate, Enter expands the highlighted entry, / focuses the search box, Esc clears, Ctrl-C quits.

sky doc --diagram <kind> [--format puml|md|svg] [--out <path>]

A read-only architecture diagram of the current project, drawn to an audit-grade standard — the kind an engineer uses for an architecture deep-dive and that stands up in a SOC2 / ISO review. Four kinds ship today — components, wire, telemetry, and journey. Three formats are available for every kind: puml (raw PlantUML, the default), md (a Markdown table), and svg (a self-contained SVG the compiler draws itself, with no external tool). --out <path> writes the output to a file instead of stdout. Mermaid is retired.

sky doc --diagram components               # raw PlantUML (default)
sky doc --diagram components --format svg  # a self-contained SVG
sky doc --diagram components --format md   # a module → capability table
sky doc --diagram wire --target web:app    # the Sky.Spa /_rpc contract, as PlantUML
sky doc --diagram wire --out wire.puml     # write the PlantUML to a file
sky doc --diagram telemetry --format md    # the privacy/observability inventory
sky doc --diagram journey --format svg     # the page state machine, as an SVG
sky doc --diagram journey --target web:app # client/server split per action (Sky.Spa)

The PlantUML output is a raw @startuml … @enduml document with one title line, a shared skinparam block, and a legend — so it pipes straight into a .puml file. The SVG output is a complete <svg>…</svg> document, laid out with orthogonal edges only, collapsed parallel edges, generous spacing, a legend, and a canvas sized to its content — no diagonal spaghetti and no overlapping labels. All three formats carry the same depth — the table lists, the per-branch effect families, the effectful / pure action split — as node labels + notes (puml), sections + tables (md), or drawn sections (svg); the md form additionally carries the reader notes as prose.

The three architecture kinds are target-aware: the zones, crossing labels and sections change with the app shape derived from the resolved target — Sky.Spa (a wasm client + a server over /_rpc), Sky.Live (one trusted server serving SSR + one SSE channel per session), Sky.Tui / Sky.Cli (a single terminal binary, no network boundary), and Sky.Http.Server (an HTTP API). --target overrides the sky.toml [app] target.

components is a C4 container diagram. It does not draw every module (that detail stays in the md table); it collapses the app to a handful of containers inside dashed trust-boundary zones, left → right: a User actor, a Browser · untrusted zone holding the SPA «wasm client» (Sky.Spa only), a Server · trusted zone holding the Backend «native» container with its data stores (Database, Files) and an audit-egress sink below it, and an External zone holding any External HTTP systems. The Database container lists the app's real table names — every Std.Db.Schema.table / Std.Db.Store.fromCodec name, capped at eight with a "+N more" line. For a Sky.Spa app the /_rpc crossing is labelled with the count of effectful actions that round-trip (N effectful → /_rpc), and a caption under the SPA states how many pure client actions stay in the wasm client. Auth is a control marker on the crossing; the remaining effect families (Env/Config, Jobs, Realtime, Time/Random/Uuid) fold into the Backend subtitle. A Sky.Live app drops the Browser zone and connects the actor (User (browser)) straight to the Backend over HTTPS + SSE; a terminal app draws a single Process · local zone with an in-process edge and no auth crossing; an HTTP app connects a Client over HTTPS.

wire is a data-flow diagram (DFD). The headline is the trust boundary: a client entity and a Server · trusted process either side of a dashed boundary line, with a representative request / response crossing labelled for the shape (request · /_rpc for Spa, an interaction · SSE / patch · SSE session channel for Live, HTTP for an API). For a Sky.Spa app the RPC endpoints (/_rpc) table lists every SERVER update branch that becomes a POST /_rpc/<Msg> endpoint, with its REQUEST (the Model fields it reads plus the Msg args, or "whole model"), its RESPONSE (the fields it writes), and the effect families it reaches — so a missing read is visible at a glance. Beside it, an HTTP endpoints section lists the raw App.api endpoints that sit outside /_rpc (an inbound Stripe webhook, say): each is drawn as an inbound external entity crossing the boundary to a CSRF-exempt endpoint. A Sky.Live app has no /_rpc; it shows its HTTP route table — page GET routes (App.route / App.routeParam) plus any raw App.api — and the SSE session channel as the browser↔server interaction. An HTTP app shows its whole Sky.Http.Server route map (method, path, handler, kind). A terminal app has no network boundary, so it prints one clear line.

telemetry is a data-egress inventory — what behavioural data leaves the system, and to where. Modules sit on the left; the sinks on the right are grouped into Internal (structured logs — console; OTel when OTEL_EXPORTER_OTLP_ENDPOINT is set), External egress (the analytics store), and Consent (the per-session consent state). One collapsed edge per module → sink pair carries the comma-joined events (no parallel overlapping edges); a chatty module is summarised as a few events plus "+N more" (the full list stays in the md table). Log and Analytics are effect kernels, so under a Sky.Spa split they run on the server, reached over /_rpc. An app with no such call sites prints a short note and exits 0.

journey is a TEA state machine. Each page (a Page union variant the Model's page field uses, with its URL when the app declares an App.withRoutes table) is a state, ranked left → right from the initial page (which carries the [*] entry). Parallel Msgs between the same two states are collapsed onto one edge whose label lists them, so labels never stack on top of each other; a self-navigation is one collapsed self-loop; a run-time-chosen target routes to a (dynamic page) state. Below the machine, the non-navigating actions are split into two typed sections: Effectful actions (server-classified — they reach a side effect), each chip annotated with its effect families (AddToBasket · Db), and Pure actions (client-only UI, no effect). The section labels are shape-aware: Effectful (server · /_rpc) for Spa, server-side for Live, in-process for a terminal app. A Cli app (a TEA loop with no Page union) drops the state machine and shows only the two action sections; an HTTP API prints one clear line. Per-page attribution is best-effort: a navigation target is the page an action routes TO, not attributed to a source page (the md form carries that note).

The components, wire, and journey kinds reuse the same analysis as the Sky.Spa auto-split, so the diagram cannot drift from what ships; no kind type-checks beyond the shared source load, lowers, go builds, or writes.

The remaining kind — callpath — is planned and exits non-zero with a "not yet implemented" note today.

sky doctor [--fix] [--verbose]

Project + environment health checks. v0.15.48 shipped 15 checks total — the foundational 5 (sky.toml syntax, stale .skycache/, stale sky-out/, port-in-use, missing FFI) plus 10 tooling-polish additions:

Check idSeverityWhat it covers
entry-missingerrorthe entry file (default src/Main.sky) exists. A library ([lib] in sky.toml) with no entry has no entry file and is not asked for one
library-no-moduleserrora library has at least one .sky module under its source root
go-toolchainerrorGo ≥ 1.25 on PATH (the go directive of runtime-go/go.mod)
ffi-cache-orphanwarn.skycache/ffi/*.skyi with no .skydeps/ source
missing-lockfileinfo.skydeps/ populated but no sky.lock
auth-secret-short / auth-secret-missingerror / warnSKY_AUTH_TOKEN_SECRET ≥ 32 bytes when [live] / [auth] set
ci-parityinfo.github/workflows/ci.yml invokes sky build / cargo test / verify-*.sh
stdlib-version-driftwarn (fixable).skycache generated by a different Sky compiler version
toml-unknown-sectioninfosky.toml top-level keys outside the known set
subapp-bin-missingwarn[subapp] bin = "..." paths are executable
gitignore-secrets / gitignore-missingwarnin a git work tree, .gitignore lists .sky/ (the dev console writes its secret to .sky/console-token, bare hex that secret scanners do not flag) and .env; sky init writes both, this catches a replaced or hand-written file
check-smokeinforeminder to run sky check when build is current
govulncheck-*infoflags govulncheck availability for Go-runtime CVE scanning

The Sky compiler repo also gets mem-guard (Info: running mem-guard.sh check) — gated to the compiler repo so user projects don't see it.

sky doctor                       # report only
sky doctor --fix                 # apply safe fixes (clean stale caches, etc.)
sky doctor --verbose             # print check-id alongside each finding
sky doctor --warm-cache          # prime the Go build cache (native + wasm)

The Sky Go build cache

sky build runs go build, which stores compiled objects in a build cache. Sky keeps its own isolated cache at ~/.sky/go-build (rather than the shared machine-global Go cache), so Sky can bound its size and refresh it on upgrade without ever touching the cache your other Go projects rely on.

Caching builds in CI

A CI job starts with empty caches unless it restores them, and a cold build of an app compiles the runtime and every Go dependency. Cache these three paths:

PathWhat it holds
~/.sky/go-buildSky's Go build cache (or your GOCACHE, when you set one)
~/go/pkg/modthe Go module cache (go env GOMODCACHE)
~/.cache/sky/precompressthe .gz / .br results of a client build ($XDG_CACHE_HOME/sky/precompress when that is set)

actions/setup-go's built-in cache saves ~/.cache/go-build (Go's default build cache), which Sky does not use: turn it off (cache: false) and cache the paths above. Key the cache on the runner OS and a hash of sky.toml and sky.lock (add the Go and Sky versions when your workflow pins them, so an upgrade starts a new cache instead of growing the old one); a prefix of that key is a safe fallback, because every cache entry is keyed on its content. The checkout path does not matter: every go build Sky runs passes -trimpath.

- uses: actions/setup-go@v5
  with:
    go-version: "1.26"   # the Go your app builds with
    cache: false
- uses: actions/cache@v4
  with:
    path: |
      ~/.sky/go-build
      ~/go/pkg/mod
      ~/.cache/sky/precompress
    key: sky-${{ runner.os }}-${{ hashFiles('sky.toml', 'sky.lock') }}-${{ github.sha }}
    restore-keys: |
      sky-${{ runner.os }}-${{ hashFiles('sky.toml', 'sky.lock') }}-
      sky-${{ runner.os }}-

A restored build cache is trusted as compiled code: go build links what it finds there. Never restore a cache that an untrusted job could write (a pull request from a fork, another repository, a shared self-hosted runner) into a job that builds a release or holds deploy secrets. GitHub Actions does not give a pull request's caches to the default branch, but other CI systems may share one cache across all jobs; key protected builds separately there.

On a runner with little memory, --go-jobs <n> (or SKY_GO_BUILD_JOBS=<n>) caps how many packages go build compiles at once, and SKY_BUILD_SERIAL=1 builds a client app's two legs one after the other.

sky stops a go build that runs longer than 10 minutes, so a wedged Go toolchain (a stuck linker, a hung module fetch) cannot hold a build for ever. On a slow runner, raise the limit with --go-build-timeout <value> (or SKY_GO_BUILD_TIMEOUT=<value>) on sky build, sky check and sky run. The value is whole seconds (900) or a whole number with a unit (900s, 15m, 1h). A value that does not parse stops the build with an error, it never falls back to the default. (v0.29.0+)

When another process (a memory watchdog, kill) stops a build, sky says so. A child leg or go build stopped by a signal ends with a line such as frontend build stopped by SIGTERM from another process (a memory watchdog?) and these two knobs. A SIGTERM to sky itself prints sky: stopped by SIGTERM from another process, and the exit status stays 143.

Exit codes: 0 clean, 1 warnings, 2 errors. CI-friendly.

sky verify [example]

CI canonical runtime check. Iterates every directory under examples/ (or the named one), builds it, go builds the emitted Go, and runs it (cmd_verify, rust/crates/sky/src/main.rs:3842-3941).

Output lines: ok: <name>, FAIL build: …, FAIL go-build: …, FAIL run: …. Exit code is non-zero if any example fails.

sky verify does no scenario-driven HTTP assertion, and this section used to say it did. The removed text described hitting / plus "any routes declared in examples/<n>/verify.json", checking status codes and body substrings, skipping GUI examples via SKY_SKIP_GUI=1, printing runtime ok: / FAIL scenario: / [skip], and a {"requests":[… "expectStatus" … "expectBody" …]} schema. None of it exists — grep -rn 'verify.json\|expectStatus\|SKY_SKIP_GUI\|runtime ok\|FAIL scenario' rust runtime-go scripts returns nothing from the verify path.

Two consequences worth knowing:

The scenario-contract mechanism the old text described does exist — under a different name, in a different tool: scripts/example-e2e.sh reads examples/<n>/e2e.json and honours expectStatus (example-e2e.sh:113, :185). That is the behavioural tier in docs/rust-rewrite/11-testing-and-verification.md §1. To get scripted HTTP assertions on an example, write an e2e.json — not a verify.json.

sky test <file>

Run a Sky test module. Only that suite and the project modules it imports are built, so a type error in another suite under tests/ does not stop it (sky verify runs every suite). See testing.md. --format json prints one test line per case and a summary with the case counts (see Machine-readable output). A project with a .env.test file runs in test mode: outbound HTTP is mocked from tests/mocks/ fixtures (unmatched requests fail closed), a [database] project gets an ephemeral offline database, and SKY_TEST_SEED / SKY_TEST_CLOCK_MS make effects deterministic. sky test never takes a database from .env: a DSN for the tests comes from .env.test or the environment. A project whose .env names one runs in test mode even without a .env.test, on the throwaway database, and the run prints one line that names the ignored DSN. Test mode never loads .env at all. The mock fixture shape and the multi-outcome patterns are in testing.md.

sky test --scaffold-mocks writes mock-fixture skeletons for the app's outbound HTTP boundary (method + urlContains pre-filled from the typed IR; fill each body with a captured payload). It never overwrites an existing fixture. See testing.md.

sky test takes several suites (sky test tests/ATest.sky tests/BTest.sky) and exits with the worst status of them. --coverage (data in .sky-coverage/) or --coverage=<dir> records which top-level functions and case arms the suites ran, and prints a one-line summary on stderr. Read the detail with sky coverage report. With --format json give one suite per run.

sky coverage report

sky coverage report [dir] [--by-module] [--format json|text] [--all]

Reports the coverage the last sky test --coverage recorded in dir (default .sky-coverage/ in the project): per Sky module, the functions that ran and the case arms that ran. Text by default. --by-module prints one line per module. --format json prints the stable JSON shape (version 1) documented in testing.md. Only the project's own modules are shown unless --all (test suites, Sky dependencies, and the stdlib functions the program reached). Needs the go toolchain (go tool covdata). Exits 1 when the directory holds no coverage data.

sky fuzz <file>

The unified app fuzzer for any TEA app (Spa or Live). It always runs the model no-panic net: derives a Msg generator from the app's own Msg union, folds random Msg sequences from init () through the real update, and asserts no unclassified panic. Runs offline under test mode.

sky fuzz src/Main.sky --iters 500 --seed 42          # model no-panic net
sky fuzz src/Main.sky --target web:app --iters 500   # + the differential split oracle
sky fuzz src/Main.sky --unguided                     # fresh random sequences only
sky fuzz src/Main.sky --coverage[=dir]               # + a run for `sky coverage report`

The model net is coverage-guided by default: it counts the case arms each sequence reaches, keeps the Msg prefixes that reach a new arm and mutates them, and prints case arms reached R/T. A panicking sequence is shrunk and printed (panicking sequence (3 Msg(s) from init): Open, Turn, Fire). --unguided folds fresh random sequences only. --iters is the Msg budget. --coverage (data in .sky-coverage/) or --coverage=<dir> also builds the harness with go build -cover, so sky coverage report shows what the fuzz reached. See testing.md.

--target (default: the project's sky.toml [app] target) selects the app shape. When it is a Sky.Spa client target (web:app, mobile*, desktop:<os>, tablet:<os>) sky fuzz ALSO runs the differential split oracle: it runs each random (Model, Msg) directly and through the client/server split and asserts the two agree — a free oracle that catches dropped read/write-set fields and Msg-argument collisions. A non-split target (or none) runs the model net alone. This replaces the former sky spa-diff-fuzz verb. Exit 0 on PASS, non-zero on the first divergence or panic (reproducible with the same --seed). See testing.md.

Configuration

sky config migrate

Rewrite a legacy sky.toml's runtime keys into a typed config binding (the Sky.Config / Live.withX surface — see sky.toml typed config).

sky config migrate            # move legacy runtime keys → typed config, in place
sky config migrate --dry-run  # print the summary + diff, write nothing
sky config migrate --check    # exit non-zero if legacy runtime keys remain (CI gate)

The same legacy keys, when present, are also reported by a migration LIST printed on every sky build / sky run (moved / removed / changed), self-extinguishing once the keys are gone. Both the build-time hint and this verb derive from one migration table, so the hint names exactly what the verb rewrites.

Database

sky db status [FILE] · sky db migrate [FILE]

Inspect and apply Std.Db schema migrations. FILE defaults to src/Main.sky.

sky db status      # report applied / pending / drifted migrations, then exit
sky db migrate     # apply all pending migrations in order, then exit

Both build the project, then run it in DB-ops mode — the app's Db.migrate call does the work and exits before serving. The underlying mechanism is the SKY_DB_OP env var (status / migrate), usable directly in a deploy pipeline: SKY_DB_OP=migrate ./sky-out/app.

See Sky.Db — Schema migrations.

sky db migrate --gen [NAME] — file-based migrations (no live DB)

When you define your schema with Std.Db.Store + Std.Codec and expose a db : Store.Project binding, --gen derives migration files from the types — no database connection required:

sky db init                      # scaffold db/migrations/ + db/schema.json (once)
sky db migrate --gen init        # first migration: CREATE TABLE for every store
# …add a field to a record, then:
sky db migrate --gen add_stock   # → addColumn (required cols: NOT NULL DEFAULT <declared or zero>)
sky db status                    # ✓ applied / ○ pending / ✗ EDITED per committed file vs the ledger
sky db migrate                   # apply the committed db/migrations/*.json to the live DB
sky db seed                      # run the entry module's seed : Db -> Task Error ()

--gen follows the same rule as Store.migrate: a Maybe field is a nullable column, any other field NOT NULL DEFAULT <declared default, else zero>, a unique column gets an addIndex, and declared indexes (Store.index / uniqueOn / uniqueWhere, Schema.withIndex) become addIndex / dropIndex ops. Every migration file, old or new, renders with this one rule.

The _sky_migrations ledger keeps a checksum of each migration file's ops (a canonical form of the op list, the same on every dialect), not of the SQL they render to, and a kind column (ops, or sql for hand-written Db.migrate SQL). A later change to how an op renders never makes an applied file look edited, and an edit to an applied file is still refused (checksum mismatch). A ledger written by v0.28 is upgraded on the first migrate, with no configuration: the kind column is added, and each applied op file is re-stamped once with its ops checksum (one log line per file). See docs/migration/v0.29.md.

sky db status compares the committed files against the live _sky_migrations ledger, with the checksum check sky db migrate and sky db check use, and exits non-zero while anything is pending or edited (an applied file changed afterwards is EDITED) — a ready-made "is this DB up to date?" deploy gate. sky db seed runs the seed binding your entry module exposes (module Main exposing (main, db, seed)), against the live DB.

sky db check — does the live database match the code?

sky db check                 # report; exit 0 when it matches, 1 on drift, 2 when it cannot run
sky db check --sql           # print the SQL that makes the database match the code (never run)
sky db check --sql --write   # also save the safe steps as a migration in db/migrations
sky db check --code          # what the code needs to read the database safely

sky db check reads the live database and changes nothing. It connects the way the app does (DATABASE_URL, <PREFIX>_DB_PATH, SKY_DB_PATH or sky.toml [database]), so it works on a local cluster, a CI database or a remote one, on PostgreSQL and SQLite. Its helper runs with SKY_READ_ONLY_DB=check: a SQLite file is opened read-only, whatever mode its DSN gives (mode=ro and the query_only PRAGMA replace it; a missing file is refused with exit 2, never created, for a plain path and a file: URI alike; a plain path keeps its own ? parameters, as the app opens it). A database in WAL mode (the mode Db.connect sets) creates no -wal or -shm file: with no -wal file beside it, no process has it open and every committed page is in the main file, so it is read with immutable=1; with one, a live process holds pages the main file does not have yet, and the check reads through the -wal and -shm that are there. So the check works in a directory it cannot write, and sees a running app's committed rows. A -wal file with no -shm file beside it (a backup that copied the database and its -wal only) is refused with exit 2: SQLite reads a -wal only through the -shm index, which a read-only open would have to create. The message names the fix: fold the -wal into the database once (sqlite3 x.db 'PRAGMA wal_checkpoint(TRUNCATE)', with no app running), or copy the -shm file with it. Every PostgreSQL transaction is read-only, and no telemetry table is written. sky db status runs the same way. It compares every table of the project's db : Store.Project (the Std.Db.Store stores, and the Std.Db.Schema tables that Schema.toProject adds) with the database: tables, columns, types, NOT NULL, defaults, the serial key, UNIQUE, and indexes with their columns, uniqueness and partial-index predicate. It also reports the migration ledger: each db/migrations file is applied, pending or edited (its checksum changed after it was applied), by the same rule sky db migrate uses. It exits 1 on any difference and on a pending or edited migration, so it is a CI and pre-deploy gate.

The comparison is the sky db migrate --gen diff. The live database is read into the same model as db/schema.json, so check and --gen find the same missing tables, columns and indexes and the same type changes. check also sees what only a live database holds (NOT NULL, defaults, UNIQUE, the serial key). The tables the Sky runtime keeps (sky_*, _sky_*, analytics_events, telemetry_*) are not the app's, and are never reported.

check compares the primary key too: a composite key, a key on another column than the Store's, or no key is a difference, with what it means for Store.update, Store.upsert and Store.delete (v0.29.2). A UNIQUE constraint over several columns (UNIQUE (tenant, name)) is the index it is, matched to a declared Store.uniqueOn by its columns whatever the database named it; one the code does not declare is a difference that names the constraint. An index whose column list does not describe it (an expression column, a collation or operator class of its own, a DESC column, INCLUDE columns, another index method such as hash, an exclusion constraint, or PostgreSQL's NULLS NOT DISTINCT, a deferrable constraint, or an index that is not valid, ready and live) is something no Store declares: check gives a notice for it, leaves it as it is, and says so in the report ("matches what the code declares; N notice(s)"). Under a name the code also declares, it is a difference. An inherited non-default column collation is also unsupported, on both SQLite and PostgreSQL. It does not become plain uniqueness in an adoption stub.

check also runs the data check the app's Store.migrate runs before it changes a table (Store.checkProjectData, the same runtime function), so the two never disagree. A column type can fit while its rows do not: a SQLite TEXT column that holds the JSON a Codec.auto Money field wrote fits a Codec.moneyIn GBP field by type, and Store.migrate refuses it. check reports such a table as drift with Store.migrate's own text, and --sql gives the check query and the conversion it names, commented out. On PostgreSQL the refusal replaces the type finding for that column. An Int column that PostgreSQL holds as INTEGER (an older Schema.createSchema made it) is accepted, with a notice: a Sky Int is 64-bit, and a value above 2147483647 fails there.

--sql prints each step under a comment that names the difference. A step that loses nothing is plain SQL, rendered by the same renderer as sky db migrate (create a table, add a column, add an index). A step that loses data or can fail on existing rows is commented out, with the reason: a type change, NOT NULL on a column that can hold NULL, a dropped column, table or index, and on SQLite any change that needs a table rebuild. The INTEGER → BIGINT widening is a commented step with its notice. --write saves the safe steps as a normal migration file (db/migrations/<time>_db_check.json, the same format and the same ops --gen writes), puts a dropped column or table in its inert destructive array, and updates db/schema.json as --gen does. Because db/schema.json then records the code as what the migrations build, the file also carries the steps --gen writes against the old db/schema.json when the database is ahead of it (a table adopted from --code): its CREATE TABLE and CREATE INDEX are IF NOT EXISTS. Snapshot-only unconditional unique indexes also carry skipEquivalentConstraint: true: applying the migration checks for an equivalent ordinary UNIQUE constraint in the current transaction and skips a redundant index. This check does not apply to explicit named index ops or to partial, expression or special indexes. Rendered SQL alone only checks the index name. Tables are created before added columns, and columns before their indexes. The same written file builds a fresh database and updates the live one. If a column exists in only one database state and CREATE cannot supply it on the other, --write refuses without writing. It also refuses any snapshot operation that would drop a constraint-backed index. It refuses while a migration is pending or edited, and in a project with no db/migrations (run sky db init first).

--code lists, for the tables the code declares, the columns the code has no field for (and whether an insert then fails), the columns a field reads as another type, and the nullable columns a required field reads. For each table the code declares nothing for, it prints a Sky record type alias, a Codec (one Codec.field per column, Codec.decimal for a PostgreSQL NUMERIC column) and a Store with a Store.default… builder for each column default, a Store.unique for each single-column UNIQUE constraint or index, a Store.uniqueOn for each multi-column UNIQUE constraint, and a Store.indexNamed / Store.uniqueOnNamed for each other index under its live name (v0.29.2), ready to copy into a module. An index the Store cannot declare (a partial index, a unique index over a nullable column, or one over a column the stub has no field for) is a comment in the stub, and sky db check reports it until you declare it or drop it. An index whose column list does not describe it (an expression, a collation, …) is a comment too, and check gives a notice for it. A table with a composite primary key gets a stub that is all comment: a Store's key is one column. A project with no tables yet (db = Store.project []) is checked as one (v0.29.2). Each field has the type sky db check accepts for its column, so an adopted stub passes the check: a date, time, UUID or JSON column is a String (on SQLite as well, where such a type has NUMERIC affinity), as is any PostgreSQL type that is not a number, a boolean or binary data (timestamptz, uuid, jsonb, interval, an array). A default no Store builder declares (an expression such as gen_random_uuid()) is a comment in the stub. sky db check never edits your code, never runs SQL, and never writes a file without --write.

sky db push — no-migration-files dev sync

sky db push        # create missing tables + add new columns to match your types

The fast prototyping loop (Prisma-style db push): syncs the live DB to your current db : Store.Project with no migration files — creates each missing table, adds any new columns (by the Store.migrate rule: a Maybe field nullable, any other NOT NULL DEFAULT <declared or zero>) and creates any missing declared index. Additive + idempotent; never drops, retypes or alters an existing column. Use sky db migrate --gen once your schema stabilises and you want reviewable, committed history for production.

sky db reset [table] · sky db drop [table] — destructive resets

sky db reset            # empty EVERY declared table (keep schema + the ledger)
sky db reset users      # empty just the `users` table
sky db drop             # drop EVERY declared table + `_sky_migrations`
sky db drop users       # drop just the `users` table (ledger untouched)

Both operate on the tables your entry module declares via db : Store.Project (each Table carries its name / cols / pk) — not on other tables that happen to share the database.

Both are destructive, so both prompt before doing anything:

This will reset 3 table(s) in sqlite — type 'yes' to continue:

Scope note. reset / drop only touch the tables your Store.Project declares. For a TOTAL wipe of a shared database (every table + extensions + sequences, including ones Sky doesn't know about), use your database's own tooling — e.g. DROP SCHEMA public CASCADE; CREATE SCHEMA public; on Postgres, or delete the SQLite file.

sky db start · sky db stop · sky db ps — the local PostgreSQL cluster

Every verb above talks to a database. These three are the database: they supervise a local PostgreSQL cluster for the project you are standing in, so development runs the same engine production does instead of the SQLite that quietly diverges from it. The design is docs/skydb/embedded-postgres.md.

sky db start        # initdb on first use, then start; already running is a no-op
sky db ps           # this project's cluster
sky db ps --all     # every Sky-managed cluster on the machine
sky db stop         # stop this project's cluster (pg_ctl stop -m fast)
sky db stop --all   # stop all of them
$ sky db start
sky db start: PostgreSQL 18.6 running (pid 41277).
  data:   /Users/dev/shop/.skydata/pg
  socket: /tmp/sky-9f2c1a4b7e03d5c8
  log:    /Users/dev/shop/.skydata/postgres.log

Connect with:
  psql -h /tmp/sky-9f2c1a4b7e03d5c8 postgres
  DSN: postgresql:///postgres?host=/tmp/sky-9f2c1a4b7e03d5c8

The binaries are discovered, in order, from SKY_POSTGRES_BIN, then ~/.sky/postgres/<version>/bin (pinned version first, then newest), then PATH; a directory must hold initdb, pg_ctl and postgres to count. SKY_POSTGRES_BIN set but incomplete is an error rather than a fall-through — silently using a different installation is worse than the typo. Set SKY_HOME to relocate the registry (tests and CI).

sky db provision --embed — fetch PostgreSQL, no system install needed

Populates the middle entry of that discovery order with Sky's own build of PostgreSQL, so a machine with no PostgreSQL at all can still run sky db start.

sky db provision --embed                 # fetch, verify, install, pin
sky db provision --embed --force         # re-install over an existing cache
sky db provision --embed --from ./postgres-18.6-linux-amd64.tar.gz \
                        --checksum <sha256>   # offline, from a local file
$ sky db provision --embed
sky db provision: fetching https://github.com/anzellai/sky/releases/download/…
sky db provision: PostgreSQL 18.6 installed.
  /Users/dev/.sky/postgres/18.6/bin
  pinned in sky.toml ([database] postgresVersion = "18.6")

Next: sky db start

Bundles are built from source in Sky's CI for linux-amd64, linux-arm64, darwin-amd64 and darwin-arm64; psql is deliberately excluded (GNU readline is GPL-3.0). Windows is out of scope — use a system PostgreSQL and SKY_POSTGRES_BIN.

sky db provision --shared — one cluster for every app on a host

The production counterpart to sky db start. --embed provisions the binaries; --shared provisions the cluster they run, at a stable state directory (/var/lib/sky, /usr/local/var/sky on macOS, --state-dir to move it), tuned from the host's real RAM and CPU rather than from the small development profile.

sky db provision --shared --service --backup --start   # once per host
sky db provision --shared --app orders                 # once per app, prints its DSN
sky db provision --shared --app orders --rotate-password
sky db provision --shared --dry-run                    # show the conf, hba, SQL and units
$ sky db provision --shared --app orders
sky db provision --shared: app orders is ready.
  database: orders
  role:     orders  (may connect to orders and to nothing else)

DSN — sky does not write this anywhere; put it in your secret store:
  postgresql://orders:<generated>@/orders?host=/var/lib/sky/run

SKY_PG_TUNE_MEM_MB states the RAM the cluster may use, for containers where /proc/meminfo reports the host's total rather than the cgroup limit.

sky db init and sky db status belong to the migration engine documented above and are unchanged. The cluster verbs are start / stop / ps / provision.

Running migrations as part of sky run

sky run takes --db-push, --db-migrate, and --db-seed flags that run those steps (in that order) before the app starts — the container-entrypoint "migrate-then-serve" shape. Any step failing aborts the run.

sky run --db-migrate --db-seed src/Main.sky   # apply committed migrations, seed, serve
sky run --db-push src/Main.sky                # dev: sync schema, serve

Deploying — self-migrating binaries

When a project has db/migrations/, sky build embeds the migrations into the binary. A deployed binary then self-migrates with no source tree and no sky toolchain on the host:

SKY_DB_OP=migrate ./app   # apply the embedded migrations, print a summary, exit
SKY_DB_OP=status  ./app   # report applied / pending, exit
./app                     # (unset) boot + serve — no migration on boot

Run SKY_DB_OP=migrate ./app once as a deploy step (a single owner), then start your replicas normally — booting without SKY_DB_OP never migrates, so scaling out is safe. The connection comes from the app's usual config (DATABASE_URL / <PREFIX>_DB_PATH).

How it works — gen builds a temporary DB-free entry (main = Store.dumpSchema db), captures the type-derived schema, and diffs it against the committed snapshot db/schema.json:

The output is committed to git (db/migrations/*.json + db/schema.json), so review + history live in the repo. sky db migrate (with db/migrations/ present) applies the files through the same checksummed _sky_migrations ledger as the code-defined path — at most once each, dialect-correct for the live connection (one file → correct on SQLite and Postgres).

Cache & cleanup

sky clean

Removes:

Rebuild from scratch with sky build after sky clean.

Dependencies

sky add [--go|--sky] <pkg>[@version]

Adds a dependency. With neither flag, sky add smart-resolves whether the target is a Go module or a Sky-source package and routes accordingly; --go / --sky force one path and skip the probe.

For a Go module it fetches the module, runs the FFI inspector, generates the FFI surface (sky-ffi/<slug>.{skyi,kernel.json} + sky-ffi/go/<slug>_bindings.go — a gitignored build artifact, regenerated by sky install), and records the dependency under ["go.dependencies"]. For a Sky package it git clones the repo into .skydeps/<slug>/ and records it under [dependencies].

Smart resolution (deterministic, content-based):

  1. An undotted import head (net/http, io) is stdlib → Go, no probe.
  2. Otherwise the import path is cloned (a Sky package always lives at its repo root). If the clone succeeds and the repo has a [lib] table in its sky.toml → Sky (the cloned tree is kept, no re-fetch). If it has no [lib] (a Sky app, or a src/-less Go repo) the tree is discarded and it falls through to Go. If the clone fails (a Go package subpath like github.com/stripe/stripe-go/v84/customer, or a vanity path like golang.org/x/sync/errgroup, is not a clonable URL) it falls through to Go.
  3. Go: go get <path>@<spec> resolves the package (it walks a package path up to its module and handles vanity redirects + major-version subdirs). On success the Go surface is generated.
  4. If neither resolves → an actionable error suggesting --go / --sky.

Tie-break: a repo that is both a Go module and a Sky [lib] package resolves to Sky (that is the case the smart default exists for — sky add github.com/org/sky-widgets); pass --go to force the Go surface. A private Sky package whose probe clone fails on auth looks like "not a repo" and falls to Go — use --sky to force it.

Version handling (Go-native):

sky add github.com/google/uuid           # pin-by-default: records the resolved
                                          # version, e.g. "v1.6.0"
sky add github.com/google/uuid@v1.5.0    # pin an exact version / branch / commit
sky add github.com/google/uuid@latest    # explicit float — pulls latest on every
                                          # `sky install` / `sky update` (a broken
                                          # latest API fails the build, forcing a fix)
sky add github.com/stripe/stripe-go/v84

Forcing the kind — sky add --go / sky add --sky:

sky add github.com/anzellai/sky-tailwind              # smart-resolves → Sky
sky add --sky github.com/anzellai/sky-tailwind@v1.2.0 # force Sky, pin a tag/SHA
sky add --go  github.com/some/polyglot-repo           # force Go for a repo that
                                                       # is both a Go module and
                                                       # a Sky [lib] package

--sky trusts the looser src/ marker (you asserted it is a Sky package), so it also accepts a Sky package that predates the [lib] convention. --go skips the clone probe entirely (offline-friendly for a known Go module). A Sky package is git cloned into the gitignored .skydeps/<slug>/ and recorded under [dependencies], with the same version semantics as Go deps (pin-by-default; latest/branch float; exact tag/SHA pin). sky install fetches every declared [dependencies]; sky build is read-only and errors run 'sky install' if a declared Sky dep isn't fetched; sky remove --sky <path> drops the entry and its .skydeps/ tree.

A fetched package is checked as your code. sky check, sky build and sky test parse-check and type-check every module under .skydeps/<slug>/src/ on every build, with the rules your own modules follow, and report an error under the package file (.skydeps/<slug>/src/Evil/Probe.sky:8:5). Three consequences:

Why every build, and not once per pinned version: a pin fixes the package's text, not the result of checking it. The same text can be checked by a newer compiler, against a newer stdlib or another Go surface, and give a different answer, so a verdict cached under the package's hash would need all of those in its key to be sound. The check is the same pass that runs over your own modules, packages are small, and the go build that follows costs far more, so the build re-checks them rather than trust a cached verdict.

The FFI inspector (sky-ffi-inspect) is embedded in the sky binary and self-provisions into $XDG_CACHE_HOME/sky/tools/ on first use — no separate install required. Cold start costs one go build (~4s); subsequent calls are instant. Content-hashed cache means sky upgrade invalidates the helper automatically.

There are no overrides. This section used to list a probe order — $SKY_FFI_INSPECTOR, then bin/sky-ffi-inspect in the cwd or an ancestor, then the embedded fallback. Neither of the first two is implemented (grep -rn 'SKY_FFI_INSPECTOR\|bin/sky-ffi-inspect' rust/crates --include='*.rs' is empty); ffi::ensure_inspector (rust/crates/ffi/src/inspect.rs:329) goes directly to the source tree and the content-hashed cache. See docs/development.md for what that means for the bin/ copy scripts/build.sh still writes.

Local path dependencies — sky add ./dir:

An argument that starts with ./, ../ or / names a directory on this machine instead of an import path. Nothing is fetched or copied:

sky add ../greet        # has go.mod    → ["go.dependencies"] "example.com/greet" = { path = "../greet" }
sky add ./libs/widgets  # has sky.toml or .sky sources → [dependencies] "widgets" = { path = "./libs/widgets" }

sky remove [--go|--sky] <pkg>

Drops a dependency. With no flag it routes by which sky.toml section declares the package: a [dependencies] entry (Sky package) removes the [dependencies] line and its .skydeps/<slug>/ tree; a ["go.dependencies"] entry (Go module) removes the line, the generated sky-ffi/<slug>.* surface, and the go.mod require (go mod tidy). The routing is a local section lookup — no probe. --go / --sky force one path.

When the last entry of a section goes, the empty table header goes with it (a table that keeps a comment stays). sky remove and sky install also bring the generated go.mod files under .skyapp/ and .split/ (the Std.App staging and the Sky.Spa split legs) in line with sky.toml: a module it no longer lists loses its require and its local replace there too, without waiting for the next build.

A ["go.dependencies"] entry that leaves sky.toml some other way (a git branch switch, a hand edit) keeps its sky-ffi/ files. The build uses only the surfaces sky.toml declares: it ignores the others, prints one line that names them, and removes their old wrappers from its own output (sky-out/skyffi/). Declare the dependency again and the surface is used again, with no sky install.

sky install

Regenerates the FFI surface from the declared dependencies. For each ["go.dependencies"] entry it ensures the go.mod pin, then generates any absent surface and re-inspects each present one. Because sky-ffi/ is a gitignored build artifact (not a committed reproducibility anchor), a present surface that no longer matches a fresh inspection — e.g. after a toolchain or dependency-version change — is simply refreshed in place (reported as refreshed), never a hard failure. All three files (.kernel.json, .skyi, go/*_bindings.go) are compared, and each carries a surface-format stamp: a surface written by a sky with another format (or none) is refreshed and named as such, and sky build warns about it until sky install runs. Unchanged surfaces are left untouched (verified). For each [dependencies] entry it clones any Sky package that is absent or whose pinned ref drifted. Idempotent.

After sky install, sky build needs no network. The last step of sky install (and of sky update) composes the Go module graph a build uses: the runtime's own requirements plus every Go dependency at its spec, resolved together, so a dependency that raises a module the runtime also imports (a newer google.golang.org/api raising go.opentelemetry.io/proto/otlp) is resolved here. It then loads every package a build compiles, for the host and for js/wasm (the Sky.Spa client), which downloads each module at the version the build selects. The graph is kept in sky-out/.sky-gograph/ with a fingerprint of its inputs. Every build of the project (Sky.Live, a Std.App target under .skyapp/, a Sky.Spa backend or wasm client under .split/) starts from it, and a latest or branch spec takes the version the install resolved, so two builds between installs use the same versions and an offline module cache (GOPROXY=off, a file:// proxy, an air-gapped host) is enough. latest moves on the next sky install / sky update. After sky add, sky remove, an edit to ["go.dependencies"] or a Sky upgrade the fingerprint no longer matches: the build then resolves the specs itself (with the network) until sky install runs again. A failure to download the graph fails sky install.

The path-dependency wiring is rebuilt from sky.toml each time. A Go path dependency that sky.toml no longer lists (removed by hand, or by a branch switch) is dropped from sky-out/go.mod, and its generated surface (sky-ffi/<slug>.* and sky-ffi/go/<slug>_bindings.go) is removed, so go get never reads the old directory. sky remove does the same for one module.

sky update

Re-floats latest/branch-pinned [go.dependencies] to their newest versions and regenerates their surfaces. Exact-pinned deps (vX.Y.Z / commit SHA) are left untouched — bump a pin explicitly with sky add pkg@<newversion>.

sky upgrade

Self-upgrades the sky binary from the latest GitHub release. After a successful upgrade it prints the release notes for every version between your old and new binary, flagging any release with breaking changes or a migration section.

sky upgrade           # upgrade, then print the notes for each version jumped
sky upgrade --notes   # preview the notes for (current, latest] WITHOUT upgrading
sky upgrade --force    # install the latest release even from a dev build

Notes come from the GitHub Release body (mirrored from CHANGELOG.md); the fetch is best-effort and never fails the upgrade.

Automatic update nudge. When you run a sky command interactively and a newer release exists, sky prints a one-line "a new release is available — run sky upgrade" note to stderr. The check is cached (~/.cache/sky/update-check.json, %LOCALAPPDATA%\sky on Windows) and refreshed at most once a day in a detached background process, so it never slows a command or blocks on the network. The nudge itself prints at most once a day. It stays out of your way entirely when output isn't interactive: it's suppressed unless stderr is a TTY (so scripts / CI / pipes never see it), for builds from a source checkout (their sky --version names a commit: sky v0.29.0 (1a2b3c4)), and for lsp / fmt / --version. Set SKY_NO_UPDATE_CHECK=1 to disable it completely.

sky upgrade-claude

Refreshes the cwd's AGENTS.md and CLAUDE.md from the templates embedded in the running sky binary at build time. Use it after sky upgrade. The embedded templates move with new releases (new stdlib APIs, deprecation notes, current limitations), but a project's copies are a snapshot taken at sky init time and do not update by themselves. AGENTS.md is the agent-agnostic guide. CLAUDE.md is the Claude Code entry point, and it imports AGENTS.md.

Behaviour:

$ sky upgrade-claude
Refreshed AGENTS.md (61204 → 67701 bytes)
  previous version saved as AGENTS.md.bak
Refreshed CLAUDE.md (12918 → 13533 bytes)
  previous version saved as CLAUDE.md.bak
(from sky v0.30.0 (70969ab3e))

Dev console

sky console [--port N] [--tui]

Runs the bundled Sky Console mini-app standalone. The console is also auto-mounted at /_sky/console inside every Sky.Live and Sky.Http.Server app in dev mode — the standalone form is for ad-hoc inspection when you don't have (or don't want to start) a host app.

sky console                # Sky.Live in the browser on :8025
sky console --port 8030    # different port
sky console --tui          # same UI rendered through Sky.Tui in your terminal

The source lives in sky-bundled/console/ (embedded into the sky binary at build time by rust/crates/ffi/build.rs). First invocation builds into $XDG_CACHE_HOME/sky/console-<version>/ (~3–10 s); subsequent runs are instant. Cache keys include the version string so sky upgrade auto-invalidates.

Live and TUI variants share the same State.sky + View.sky — only the entry-point module switches between Live.app and Tui.app. Cached binaries are kept side-by-side (app-live / app-tui) so switching backends doesn't trigger a rebuild.

Env flags (full reference in CLAUDE.md):

AI models

sky ai provision | pull | ps | start | stop (v0.28.0)

Drive the managed local model engines of Std.Ai.Local. The verbs hold no logic of their own: sky ai builds a bundled Sky program (sky-bundled/ai) once per Sky build and runs it, and the program calls the Std.Ai.Local and Std.Ai.Endpoint API a user's program has. The training verbs run a second bundled program, sky-bundled/ai-train, over Std.Ai.Train. Every verb takes --format json.

sky ai provision [--variant cpu|metal] [--dev-model] [--model <ref>]
sky ai pull <org>/<repo> <file>
sky ai ps [--all]
sky ai start <slot> [--model <ref>] [--context <n>] [--embeddings]
sky ai stop <slot> | --all

sky ai promote | rollback | lineage (v0.28.0)

The Std.Ai.Registry verbs. In a project with a pipeline (src/Ai.sky) they run through it, on the database and registry its code names (Pipeline.withDb, Pipeline.withRegistry); elsewhere the bundled program runs them. --db <dsn> wins over the code, then SKY_DB_PATH, then DATABASE_URL; the artefact store is --registry <url>, else SKY_AI_REGISTRY, else the code's. Nothing is read from sky.toml. Every verb takes --format json.

sky ai promote <name> <version> --to <alias> [--min-pass-rate <x>] [--expect <n>|none]
sky ai promote <name> <version> --to <alias> --force --reason <text>
sky ai rollback <name>@<alias>
sky ai lineage <name>@<alias> | <name>@v<n>
sky ai lineage --dataset <sha256> | <name>@<n>

See ../ai/registry.md.

sky ai eval | data freeze <dataset> | run | members (v0.28.0)

The project-mode verbs. A project declares its AI pipeline in src/Ai.sky (module Ai exposing (pipeline), Std.Ai.Pipeline); the CLI builds a program whose main is Pipeline.commandLine Ai.pipeline, caches it under .sky/ai/cli/<key>/ (rebuilt when the Sky version, sky.toml or a source file changes; progress on stderr) and runs it in the project directory.

sky ai eval <suite> [--against <alias>] [--candidate <model>@v<n>] [--promote-to <alias>]
                    [--junit <file>] [--markdown <file>] [--min-pass-rate <x>] [--max-regression <x>]
sky ai data freeze <dataset>
sky ai run <task> [-- <args>]
sky ai members

See ../ai/pipeline.md.

sky ai provision --train | train | export (v0.28.0)

The Std.Ai.Train verbs, run by the same bundled program. Every verb takes --format json.

sky ai provision --train mlx|unsloth|fake [--base <base>]
sky ai train --data <dir>/<name>[@<digest>] [--base <base> --serving <model>]
             [--name <n>]
             [--steps <n>] [--rank <r>] [--seed <s>] [--layers <n>]
             [--checkpoint-every <n>] [--eval-every <n>]
             [--backend mlx|unsloth|fake] [--gguf] [--merged] [--register]
             [--detach] [--work-dir <dir>] [--db <dsn>]
sky ai train status [<run>] | runs | resume <run> | cancel <run>
sky ai export <run> [--out <file>] [--merged]
sky ai start <slot> ... --adapter file:<path>#sha256=<hex>

SKY_AI_TRAIN_BACKEND (mlx, unsloth, fake, vertex) wins over --backend. See ../ai/train.md.

sky ai train --backend vertex | serve | deploy | teardown | cloud | image build (v0.28.0)

Training on Google Cloud Vertex AI and the GPU tier on Cloud Run. The cloud verbs run a third bundled program, sky-bundled/ai-cloud, over Std.Ai.Serve and Std.Ai.Cloud.Google. Every verb takes --format json.

sky ai train --data <dir>/<name> --backend vertex [--project <p>] [--region <r>]
             [--machine <type>] [--staging gs://<bucket>/<prefix>] [--budget "USD 2.00"]
             [--image <ref>@sha256:<hex>] [--service-account <email>]
             [--max-runtime-minutes <n>] [--price <machine>@<region>=<amount>]...
             [--price-book <date>] [--spot] [--keep-staging] [--label k=v]...
sky ai registry publish <name>
sky ai serve [--adapters <name>@<alias>,...] [--registry <url>] [--bind <addr>]
sky ai serve --image [--out <dir>] --service <name> [target flags]
sky ai deploy --service <name> --tier-image <ref> [target flags] [--dry-run]
sky ai teardown --service <name> | --run <key> [--staging gs://...] | --all-sky
sky ai cloud ls [--run <key>]
sky ai cloud prices --service <name> --region <r> [--match <word>]...
sky ai image build --train|--tier --repo <name> --staging gs://...

Target flags: --project, --region, --adapters, --engine-image, --token-secret, --registry, --service-account, --invoker, --min-instances, --max-instances.

See ../ai/serve.md and ../ai/deploy-gcp.md.

sky ai provision --device and the device build flags (v0.28.0)

sky ai provision --device web|ios|android|all [--from <dir|archive>] [--check]
sky build --target web:app [--ai-web-engine webgpu|cpu|both|none] src/Main.sky
sky build --target mobile:ios|mobile:android|desktop:mac [--ai-embed <slot>] src/Main.sky

See ../ai/device.md.

A model <ref> is hf:<org>/<repo>/<file>#sha256=<hex> or file:<path>#sha256=<hex>. See ../ai/local.md.

Formatting

sky fmt <file>

sky fmt --check <file…> rewrites nothing and exits 1 when a file is not formatted; add --format json for one diagnostic line per such file.

Opinionated, deterministic, no configuration (output is Elm-compatible):

Editor integration

sky lsp

Starts the Language Server over JSON-RPC / stdio. Used by the Helix and Zed integrations and any LSP-aware editor.

See lsp.md for configuration snippets.

Layout

Sky writes generated artefacts to predictable locations — everything under .skycache/ and sky-out/ is regenerable. Nothing generated lives alongside your source.

project/
    src/                  -- your Sky source
    sky.toml              -- manifest
    .skycache/
        ffi/              -- .skyi signatures + kernel.json registries
        go/               -- generated Go FFI wrappers
        lowered/          -- incremental lowered-module cache
    .skydeps/             -- Sky source deps (if any)
    sky-out/              -- compiled binary + lowered main.go + rt/