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.mdfor 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:
- Parse
sky.tomlfor[go.dependencies]and[dependencies]. - Auto-regenerate any missing FFI bindings in
.skycache/. - Resolve modules, type-check, lower to Go under
sky-out/. - Invoke
go build→sky-out/app(or thebinname set insky.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
/_rpc+/_sky/console+/_sky/metricssame-origin, one binary).
--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.
--target | Produces | Notes |
|---|---|---|
web / tablet | dist/ ready to serve | serve statically, or same-origin via Server.static "/" "../dist"; tablet == responsive web |
desktop | sky-out/desktop/<app> (native binary) | generates a Std.Webview.url shell + builds it (cgo — WKWebView / WebView2 / webkit2gtk) |
ios | sky-out/ios/build/<App>.app | generates a SwiftUI + WKWebView shell + builds it for the Simulator (swiftc). Requires full Xcode + the iOS Simulator runtime; missing → warns + exits |
android | sky-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
- What it costs. The binary grows by the compressed bundle — about 25–30 MB
— and becomes platform-specific. A build without the flag pays nothing: no
bundle is linked, and any archive an earlier
--embedbuild staged is removed. - Where the bundle comes from. The pin is
[database] postgresVersion.sky build --embeduses$SKY_HOME/postgres-bundles/, else re-packs an existingsky db provision --embedcache (no network), else fetches and checksum-verifies the release. A priorsky db provisionis not required. - Cross-compiling.
GOOS/GOARCHselect the target's bundle, soGOOS=linux GOARCH=arm64 sky build --embed …embeds Linux/arm64 PostgreSQL. A target Sky publishes no bundle for is refused before the build starts — the host's binaries are never embedded into another platform's binary. --embedplus an explicit DSN is an error, at app startup, naming the source. There is no precedence that does not either ignore the operator's database or make the flag inert.
--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:
| Level | brotli | gzip | 52 MB wasm: time, .br size |
|---|---|---|---|
max (default) | quality 11, parallel | -9 | 26 s, 2.77 MB |
fast | quality 9, one thread | -6 | ~1.5 s, 3.25 MB (+18%) |
off | none | none | 0 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.
- bare — generates
shared/,backend/,frontend/and prints the build commands. --build— also builds both: backend native, frontend wasm (--target web).--target <web|desktop|ios|android|tablet>— builds the frontend for that delivery surface (implies--build);desktop/ios/androidalso produce the native shell (WKWebView / WebView2 / webkit2gtk / Android WebView / SwiftUI) over the same wasm client.--embed— builds the backend with an embedded PostgreSQL bundle (the backend owns the DB); combines with--build/--target.
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:
| File | What |
|---|---|
REPORT.md | Human-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.pprof | CPU profile for the whole run — go tool pprof -http=: cpu.pprof for a flame graph. |
heap.pprof | Heap profile at stop — go tool pprof -http=: heap.pprof. |
goroutines.txt | Full goroutine stack dump; the top frame of each blocked goroutine is where it's stuck. |
Options:
--profile-dir <dir>— where to write (defaultprofile/in the project root; a relative<dir>is read against the directory you ranskyin). The app gets an absolute path, so a Sky.Spa backend (which runs in its build folder) and aStd.Appentry write there too.--profile-timeout <dur>— if the app hasn't exited after<dur>(e.g.30s,2m), dump profiles with a hang verdict and exit. Opt-in — leave it off for a server (which "hangs" by design); it still profiles until you Ctrl-C it.
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:
- fmt — every
.skyfile under the source root +tests/is alreadysky fmt-clean. - check — type-checks +
go builds and emits the production binary (sky check≡sky buildminus the artefact, so this one build covers both). - stores — when the entry module exposes
db(aStore.Project), a scratch build runsStore.dumpSchema dband 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. Adbthat is not aStore.Projectis skipped with a note. Any other failure of the scratch build fails the step with the build error. - test — every
tests/*.skysuite 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.
kind | Fields |
|---|---|
diagnostic | file: 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. |
test | sky 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). |
summary | Always 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:
- the lowering warning
no \main` in entry moduleand the driver errorsno entry module named …,no .sky under …,lowering found no entry `main`,Sky dependency … not fetched` and the missing path-dependency error; sky.tomlwarnings (an unknown key, a[database] driverthat contradicts its DSN), path-dependency drift warnings, and the legacy-config migration hint (info);- a Sky.Spa split that refuses the app as a whole (
cannot auto-split: …); - a
go buildfailure with nofile.go:line:colline (a toolchain error); sky fmt --check(one error per unformatted file:fileis set,rangeisnull).
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:
- Per-module pages with HM signatures, Markdown-rendered doc
comments, and an in-module symbol filter (counter shows
X / Y). - Fuzzy search by name, module, OR type signature
(Hoogle-style, case-insensitive —
string -> intorString -> Intboth findString.length,String.toIntetc.). - FFI binding browsing — every imported Go-pkg FFI dep lists its surface alongside the stdlib.
- Live reload if the underlying project changes (re-runs the index build on each request).
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 id | Severity | What it covers |
|---|---|---|
entry-missing | error | the 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-modules | error | a library has at least one .sky module under its source root |
go-toolchain | error | Go ≥ 1.25 on PATH (the go directive of runtime-go/go.mod) |
ffi-cache-orphan | warn | .skycache/ffi/*.skyi with no .skydeps/ source |
missing-lockfile | info | .skydeps/ populated but no sky.lock |
auth-secret-short / auth-secret-missing | error / warn | SKY_AUTH_TOKEN_SECRET ≥ 32 bytes when [live] / [auth] set |
ci-parity | info | .github/workflows/ci.yml invokes sky build / cargo test / verify-*.sh |
stdlib-version-drift | warn (fixable) | .skycache generated by a different Sky compiler version |
toml-unknown-section | info | sky.toml top-level keys outside the known set |
subapp-bin-missing | warn | [subapp] bin = "..." paths are executable |
gitignore-secrets / gitignore-missing | warn | in 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-smoke | info | reminder to run sky check when build is current |
govulncheck-* | info | flags 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.
- Warm the cache with
sky doctor --warm-cache— it compiles the runtime for native and js/wasm so the first real build is fast instead of a cold compile.sky upgraderuns this automatically for the new version. - Size is bounded. When the cache grows past a cap (default 10 GB, set
SKY_GO_CACHE_MAX_GBto change it), Sky removes the least recently used entries until it is at 80% of the cap, so it never fills your disk and the objects your recent builds use stay. (Before v0.27.9 it emptied the whole cache, and the next build compiled everything again.) - Shared safely across versions. A new compiler embeds a new runtime, and
its objects get new content-addressed keys, so two
skyversions (an installed release and a dev build, or an upgrade while an editor still runs the old one) share the cache without cleaning it for each other. The old version's entries are reclaimed by Go's own trim (unused for five days) and by the size cap. - Escape hatch. Set your own
GOCACHEand Sky uses it as-is and manages nothing (its size and lifetime become yours to control).
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:
| Path | What it holds |
|---|---|
~/.sky/go-build | Sky's Go build cache (or your GOCACHE, when you set one) |
~/go/pkg/mod | the Go module cache (go env GOMODCACHE) |
~/.cache/sky/precompress | the .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 verifydoes no scenario-driven HTTP assertion, and this section used to say it did. The removed text described hitting/plus "any routes declared inexamples/<n>/verify.json", checking status codes and body substrings, skipping GUI examples viaSKY_SKIP_GUI=1, printingruntime 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 scriptsreturns nothing from the verify path.Two consequences worth knowing:
- Four committed
verify.jsonfiles are dead inputs.examples/{15-http-server,30-sse-server-demo,32-sse-relay,33-websocket-echo}/verify.jsonare read by nothing.- GUI skipping is not env-gated. It is a hard-coded
skip-guirow inscripts/verify-cli.sh:71.The scenario-contract mechanism the old text described does exist — under a different name, in a different tool:
scripts/example-e2e.shreadsexamples/<n>/e2e.jsonand honoursexpectStatus(example-e2e.sh:113,:185). That is the behavioural tier indocs/rust-rewrite/11-testing-and-verification.md§1. To get scripted HTTP assertions on an example, write ane2e.json— not averify.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)
migraterewritessky.tomland the entry module, then tells you to review withgit diffand runsky check.--dry-runshows the moved / removed / changed key summary and the diff without writing any files.--checkis the CI gate: exit0when no legacy runtime keys remain, non-zero (listing them) when they do.--checkand--dry-runare mutually exclusive.
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.
sky db statusexits non-zero on drift (an applied migration whose SQL was edited) — use it as a CI schema-drift gate.sky db statusruns the app with its databases read-only (SKY_READ_ONLY_DB=status, v0.29.2), so it writes nothing. The app'smainruns up toDb.migrate, which prints the report and exits. A write beforeDb.migrate(a boot log row, aCREATE TABLE IF NOT EXISTS) therefore fails with "attempt to write a readonly database" (SQLite) or "cannot execute … in a read-only transaction" (PostgreSQL), and the error says so and names this mode. Move that write afterDb.migrate, or use file migrations (sky db init): withdb/migrations,sky db statusreads the files and the ledger and does not runmain. An app with noDb.migrate(one that migrates withStore.migrate, which creates and alters tables) has no migration status to report, and its first write fails the same way: compare it withsky db check, which reads the code'sStore.projectand runs no app code. A read-only SQLite connection keepsbusy_timeout, so it waits for a writer instead of failing with "database is locked".sky db migrateexits non-zero if a migration fails — run it as a pre-cutover deploy step so a bad migration blocks the rollout.- There is no
migrate <singlefile>: migrations are an ordered, checksum-tracked set;migratealways applies every pending one.
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.
sky db resetEMPTIES the data and resets autoincrement counters, but KEEPS the schema and the_sky_migrationsledger. On Postgres it runs oneTRUNCATE … RESTART IDENTITY CASCADE; on SQLite itDELETEs each table and clearssqlite_sequence(foreign-key enforcement is toggled off for the operation). The fast "wipe my dev data, keep the tables" loop.sky db dropremoves the tables. Dropping ALL declared tables also drops_sky_migrations, returning the database to a fresh "never ran migrate/push" state; a single-table drop (sky db drop users) leaves the ledger alone. UsesDROP TABLE IF EXISTS … CASCADE(Postgres) /DROP TABLE IF EXISTS …with FK enforcement off (SQLite).
Both are destructive, so both prompt before doing anything:
This will reset 3 table(s) in sqlite — type 'yes' to continue:
--yes/-yskips the prompt (scripts, CI, container entrypoints).- On a non-TTY without
--yes, the command refuses rather than guess. - In production (
ENV/SKY_ENVin{production, prod, staging}) it refuses unless--yesis passed explicitly.
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
- One cluster per project, in
.skydata/pg/(gitignored bysky init).rm -rf .skydataresets exactly one project, and two projects on different PostgreSQL majors never fight. - A unix socket, never a TCP port — so two
sky db starts cannot race over a port and nothing is exposed to the network. The socket lives in a short hashed directory outside the project ($XDG_RUNTIME_DIR/sky/<hash>/, else/tmp/sky-<hash>/), becausesockaddr_uncaps a socket path at ~107 bytes and a deeply nested project overflows it. - Tuned small —
shared_buffers = 32MBagainst PostgreSQL's 128MB default, so an idle project cluster costs tens of megabytes rather than hundreds. Only resource knobs are set; nothing that changes what a query means. - A machine-level registry at
~/.sky/clusters.jsonis what letssky db ps --allsee clusters this shell did not start. It is reconciled on every read: a dead pid is erased, and a vanished data dir is dropped. - Idempotent by design. Starting a running cluster and stopping a stopped one both succeed, so both are safe in a script or a shell trap.
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
- Verified before it is trusted. The release's
SHA256SUMSis fetched first, the downloaded archive is hashed on disk, and a mismatch installs nothing and says so. A corrupt or truncated download never reaches the cache. - Installed atomically — extracted to scratch and renamed into place, so an
interrupted provision leaves no half-populated
bin/for discovery to find. - Idempotent. Already provisioned is a fast success with no request made.
- Pinned in
sky.tomlas[database] postgresVersion, and discovery prefers that version, so a checkout on another machine gets the PostgreSQL the project states. - Offline-capable via
--from(with--checksum, or aSHA256SUMSbeside the archive).sky doctor --fixpre-warms the cache for a project with[database] embedded = true.SKY_POSTGRES_BUNDLE_URLpoints at a mirror.
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
- A database and a role per app, the role granted
CONNECTon its own database andPUBLIC's implicit access revoked. App A's credentials are refused by PostgreSQL — not by an application check — when pointed at app B. - Socket-only by default.
--listen <addr>adds a TCP listener withscram-sha-256on loopback; without it nothing is exposed to the network. - An OS service unit with
--service, generated into<state>/servicewith thesudolines to install it: a systemd unit on Linux, a launchd job plus a shutdown wrapper on macOS. Both stop PostgreSQL withSIGINT(fast shutdown); aSIGTERMmeans smart shutdown, which waits for every client for ever. - A backup timer with
--backup:pg_dump --format=customper app on a daily schedule (--backup-at HH:MM,--backup-keep <days>), reading the app list at run time so an app added later is included. - Run it as the account the cluster will run as —
sudo -u postgres sky db provision --shared. Running as root is refused, asinitdbrefuses. - Re-running
--appis idempotent and prints no DSN: the password is stored as a SCRAM verifier and cannot be read back, so a printed one would be invented.--rotate-passwordissues a new one.
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 initandsky db statusbelong to the migration engine documented above and are unchanged. The cluster verbs arestart/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:
- new table →
createTable; new required column →addColumn NOT NULL DEFAULT <zero>(backfills existing rows); newMaybecolumn → nullable. - dropped column / table / type change → quarantined in a
destructivearray in the migration file, never auto-applied (the "never silently lossy" rule). On a TTY, gen instead asks: a drop can be resolved as a(r)ename(rewritten to onerenameColumn, data preserved), a confirmed(d)rop, or(s)kip; a required new column can take a custom backfill default. Non-interactive (CI / piped) runs keep the safe quarantine defaults.
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:
sky-out/— compiled binary + Go source.skycache/— generated FFI bindings, lowered-module cache, incremental state.skydeps/— Sky source dependencies (if any)dist/— release archives
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):
- An undotted import head (
net/http,io) is stdlib → Go, no probe. - 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 itssky.toml→ Sky (the cloned tree is kept, no re-fetch). If it has no[lib](a Sky app, or asrc/-less Go repo) the tree is discarded and it falls through to Go. If the clone fails (a Go package subpath likegithub.com/stripe/stripe-go/v84/customer, or a vanity path likegolang.org/x/sync/errgroup, is not a clonable URL) it falls through to Go. - 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. - 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
- Pin-by-default: with no
@version,sky addrecords the exact resolved version — reproducible builds out of the box. Write@latest(or editsky.tomlto"latest") to opt into floating. - Re-adding upserts:
sky add pkg@v2whenpkgis already declared updates the recorded version (the most recentsky addwins), sosky.tomlnever disagrees with the regenerated surface. - The spec is passed straight to
go get pkg@<spec>—latest, an exactvX.Y.Z, a branch, or a commit SHA. Non-Go semver constraints (>=,~,^) are rejected (Go uses MVS, not constraint solving). - Go bindings return
Result Error a, not a Task. The Go call runs where the expression is evaluated, and a Go error, a nil or a recovered panic isErr. This is deliberate: handling the Result at each call site marks where the code leaves Sky's guarantees, so prefer the stdlib where it covers the job. To run a call later, offupdate, wrap it yourself:Task.lazy (\_ -> Pkg.call args) |> Task.andThen Task.fromResult. The generatedsky-ffi/<pkg>.skyilists each binding with itsResulttype. See boundary-philosophy.md.
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:
- A package gets no
Sky.Ffi([E1011]forFfi.kernel,Ffi.call,Ffi.callPure,Ffi.callTask, under any qualifier). A package is pure Sky and ships no Go kernel, so it calls the typed stdlib like an application does. - A package's Go FFI call is typed from the project's pinned surface
(
sky-ffi/<pkg>.kernel.json) and returnsResult Error a, as in your code.sky installdoes not install a package's Go dependencies; the project declares them. - A package that does not type-check under this compiler fails the build that uses it, at the package file.
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" }
- The directory decides the kind. A
go.modmakes it a Go module, recorded under its module path; the build addsrequire <module> v0.0.0andreplace <module> => <absolute dir>to the generatedgo.modon every build (the build rewritesgo.modeach time, so the wiring is re-applied fromsky.toml, never lost), then runsgo get <module>@v0.0.0so the module's owngoline and requirements reach the generatedgo.modandgo.sum.sky addinspects it for its FFI surface like any Go dependency, and records it insky.tomlonly when that succeeds: a module Go cannot load leavessky.tomlunchanged and the error names Go's own message. Its functions returnResult Error a. Asky.tomlor.skysources make it a Sky package, recorded under itsname(else the directory name); every build loads its modules from its source root. A directory that is both is a Sky package;--go/--skyforce the kind. - A Sky path dependency is checked as your code. Its modules are
parse-checked and type-checked by
sky check,sky buildandsky test, and a diagnostic names the file in the dependency relative to the project (../widgets/src/Widget.sky:8:5). A fetched registry package under.skydeps/is checked the same way, on every build (see A fetched package is checked as your code above). - Paths are relative to the project root, not the working directory, and are resolved against it at build time. An absolute argument is stored as given.
- Edits are picked up. A changed function body is compiled by the next
build, and
sky watchrebuilds when a path dependency's.sky,.goorgo.modfiles change. When a Go path dependency's exported API changes (a function added, removed or given a new signature), the nextsky build/sky check/sky testre-inspects the module and rewrites itssky-ffi/surface before it compiles, and says so (… changed its exported API → sky-ffi/<name>.* refreshed): a path dependency is your own code, so nosky installis needed. The build compares a fingerprint of the exported declarations (sky-ffi/<name>.pathsig), so a body edit does not re-inspect. A registry dependency keeps its pinned surface. - Drift is reported. A declared directory that no longer exists stops the
build with an error naming the dependency. A Go module whose
go.modnow declares a different module path is a build warning.sky doctorwarns about a missing directory, and about one outside the repository, which a CI checkout or a deploy that copies only the repository will not have. sky removetakes the recorded name or the path.sky installre-inspects a Go path dependency (it changes without a version bump).sky updateleaves a path dependency alone and says so.
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:
- Always overwrites
./AGENTS.mdand./CLAUDE.md(the files are AI context, not hand-edited project source). - Backs each prior file up to
<name>.bak, so an accidental run on a project that customised a file is recoverable. - Prints one line per file with the byte-count delta, then the
skyversion that produced the templates, so you can see at a glance whether a template changed.
$ 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):
SKY_CONSOLE_EMBED=off— opt-out of the auto-mount inside user apps (the standalone CLI still works).SKY_DEV_BANNER=off— opt-out of the floating "🔍" Sky Console tab (right edge, vertically centred) without disabling the mount.SKY_CONSOLE_URL=https://...— override the banner's href (e.g. to point at a remote shared dashboard).ENV=production(orSKY_ENV=…outside{dev, development, local}) — production-mode gate; suppresses console + banner entirely and gates/_sky/metricsbehind auth.
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
provisioninstalls the pinnedllama-serverbuild for this host into the AI home (withSKY_AI_LLAMA_BINset it checks that build and fetches nothing), and--dev-model/--model <ref>fetch and verify models. Run it in an image or at deploy, where fetching at run time is off.pulldownloads a GGUF file whose digest you do not know yet, stores it by its digest, and prints theLocal.huggingFace { … }value to pin in code.pslists the engines on this machine (running, ororphanedwhen the program that held one was killed);--alladds stale entries.startstarts a slot's local engine and holds it in the foreground; programs with the same model and settings use it instead of loading the model again.stopends it.
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>
promotere-applies the eval gate to the version's attached reports, compared with the newest report of the same suite on the version the alias serves now, and moves the alias on the first that passes, only while the alias still serves the version compared against (Registry.promoteCompared).--expectmoves it only while it still points at that version (PromotionConflictotherwise).--force --reasonmoves it without eval evidence and records the reason. A refused promotion exits non-zero with the typed failure (NotPromotable,GateFailed,PromotionConflict).rollbackreturns the alias to the version before the current one.lineageprints the version, its base model, dataset, metadata, aliases, attached reports and alias moves;--datasetlists every version trained on a dataset, named by its digest or by its registered version (support@3).--registry <url>wins overSKY_AI_REGISTRY.
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
evalruns the suite on the candidate (and on the alias's version with--against), compares, gates, writes JUnit (.sky/ai/eval/<suite>/junit.xmlby default) and exits 1 when the gate fails.--promote-topromotes only on a pass. With--format jsonstdout is one JSON object.data freeze <dataset>(a plain name) freezes one of the pipeline's datasets and registers it when it iswithRegistered; a path or a file name is the pipeline-free form above.runruns a task with the arguments after--;memberslists the pipeline's datasets, suites, slots and tasks.start <slot>for a slot the pipeline names starts it with its code defaults (--model/--contextare usage errors there);promotegates each suite's report with that suite's thresholds from the pipeline.- Each takes
--db <dsn>,--registry <url>,--format jsonand--test-mode(model calls answered fromtests/mocks/, assky testdoes). Withoutsrc/Ai.skythese verbs exit 2 and build nothing.
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>
provision --traininstalls a training toolchain (a pinned uv, a pinned CPython and a hash-locked set of wheels) under the AI home.--basealso downloads and verifies a base's weights for that backend.--baseisdev(the development base, the default),hf:<org>/<repo>@<commit>(a Hub repository at a 40-digit commit) orfile:<directory>(local safetensors weights). A malformed base is a typedInvalidSettingbefore anything trains. A base other thandevneeds--serving <model reference>, the pinned GGUF model that serves the adapter. See../ai/train.md. Run it in an image or at deploy, where fetching at run time is off.trainfine-tunes a LoRA adapter on the frozen dataset version--datanames (the newest when no digest is given) and the--base, in the foreground. Without--format jsonit prints the run id first. A Ctrl-C stops the watcher only: the trainer keeps training, and the same command, ortrain resume <run>, attaches to it again.--ggufconverts the adapter to GGUF,--mergedalso writes a merged model, and--registerregisters the adapter in the registry (--db,--registry).--detachreturns once the trainer runs. The durable journal is.sky/ai/train.dbunless--dbnames another database.train status <run>prints a run's status, step, losses, relaunches and last checkpoint.train statusortrain runslists every run in the work directory (--work-dir, default.sky/ai/runs).train resume <run>starts a failed or cancelled run again from its newest checkpoint.train cancel <run>asks the trainer to write a checkpoint and stop (it is killed after 60 seconds).export <run>writes the run's adapter as GGUF, or with--mergedthe merged model, and--outcopies it to a file.start <slot> --adapterserves a GGUF LoRA adapter, pinned by its digest, with the slot's model.
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.
train --backend vertexruns the job as a Vertex AI custom job on one L4. It plans first (the image digest, the bucket's region, the quota, the estimate against--budget) and launches nothing when the plan fails. Each flag falls back to itsSKY_AI_TRAIN_*variable.train cancel <run>cancels the cloud job too.registry publish <name>writes the registry's pointer objects to its store again (the tier reads only those).serveruns the tier on the development base, next to vLLM.serve --imagewrites the static linux/amd64 tier binary, its Dockerfile, and the Cloud Run service asservice.jsonandservice.yaml.deploycreates or updates the Cloud Run service, waits until it is ready and grantsroles/run.invokerto--invokeronly.--dry-runprints the service and changes nothing.teardowndeletes a tier's service, a training run's jobs and staging prefix, or (--all-sky) every job and service labelledsky-managed=true.cloud lslists what Sky made, by its labels.cloud pricesreads the Cloud Billing catalogue (the price book's source).image buildbuilds the trainer or the tier image with Cloud Build into your project's Artifact Registry and prints the reference pinned by digest.
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
provision --deviceinstalls theStd.Ai.Deviceengines (llama.cpp b11200 with Sky's engine core) under the AI home: the browser's WebGPU and CPU WebAssembly builds,SkyLlama.xcframework, orlibskyllama.sofor arm64-v8a and x86_64. It downloads the releasesky-llama-b11200and checks each archive's pinned SHA-256;--frominstalls a local build ofscripts/ai/device/build-device-bundles.sh(its output directory or an archive).--checkinstalls nothing and exits 1 when an engine is missing.--ai-web-enginepicks the engines a browser client stages next to its wasm (sky-ai-webgpu.<hash>.*,sky-ai-cpu.<hash>.*, and the workersky-ai-worker.<hash>.js). The default isbothwhen the web engines are installed and the client importsStd.Ai.Device;nonestages none, and device slots then answer from the server in a browser.--ai-embed <slot>builds the server first, asks it for the slot's offer as it would serve it (operator variables and the registry included), and puts the model and the adapter in the native app, which then never downloads them.
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):
- 4-space indent, no tabs.
- Leading commas for multi-line lists/records.
- Pipelines broken onto new lines.
- An operator chain breaks only at its loosest operator:
a == b || c == dbreaks before||, never insidea == b. - List patterns are spaced like list expressions:
[ x ],[ a, b ],[]. - A type annotation stays on one line, and an exposing list breaks only past
100 columns. A record type in an annotation stays on one line when it fits;
when it does not fit, or when it is a whole argument the source had broken,
the annotation breaks one argument per line (
name :, then each argument on its own line led by->). - An own-line comment stays where it was: above the branch, argument, pipeline step, binding or field it was written above.
- Refuses to overwrite if the formatter would lose more than one-third of the source lines (guards against partial-parse deletions).
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/