Install the CLI
One-liner. Detects OS + architecture, downloads the matching static binary from stil.gitweave.run, and creates the stilr multicall symlink (≡ stil run):
$ curl -fsSL https://stil.gitweave.run/install.sh | bash
Environment variables the installer honors:
STIL_VERSION— pin a specific tag (default:latest).STIL_INSTALL_DIR— where the binary lands (default:~/.local/bin).STIL_RELEASE_BASE_URL— alternate download base.
stil install
Reads the cwd's package.json and resolves + downloads + links every dependency.
$ stil install [--no-dev] [--frozen-lockfile] [--min-age D] [--allow-scripts] [--jobs N] [--solver greedy|pubgrub]
--no-dev/--production/-P— skipdevDependencies.--frozen-lockfile— install exactly what the lockfile says, no BFS. CI mode.--min-age D— minimum days since publish (default: 7).0disables.--allow-scripts— opt in to running lifecycle scripts inside the Hull sandbox.--jobs N— parallel BFS workers (default:min(8, cpu_count)).--solver pubgrub— use the CDCL resolver instead of greedy BFS. Experimental.
If cwd lives inside a monorepo (some ancestor has "workspaces" in its package.json), stil chdirs to the root automatically and reports:
stil: in workspace 'utils', running install from monorepo root '/path/to/myrepo'
stil add
Add a package to the right package.json and re-run install. If the spec is a tag (latest, next) or exact version, stil resolves it and records ^X.Y.Z.
$ stil add <pkg>[@spec] [-D|-O|--peer] [-w <ws>]
-D/--save-dev— devDependencies.-O/--save-optional— optionalDependencies.--peer— peerDependencies.-w <ws>/--workspace <ws>— write into the named workspace's package.json instead of root.
stil remove
Drop a dependency from package.json and reinstall.
$ stil remove <pkg> $ stil rm <pkg> # alias
stil update
Re-resolves top-level deps to the latest version that satisfies both the constraint AND the age policy. Constraints in package.json are not rewritten (no auto-bump of ^X). Prints a name: oldVer → newVer diff.
$ stil update # every top-level dep $ stil update <pkg> # just one $ stil up <pkg> # alias $ stil upgrade <pkg> # alias
stil run
Execute a script from package.json with node_modules/.bin (local + monorepo root) prepended to PATH. With no args, lists available scripts.
$ stil run # list scripts $ stil run dev # run scripts.dev $ stil run build -- --mode=production # forward args after -- $ stil run dev --filter '@my/*' # run in every matching workspace $ stilr dev # `stilr` is the multicall for `stil run`
The --filter glob supports * and ?. In filter mode, workspaces missing the script are skipped silently.
stil why
Show the inverse dependency tree for a package — who pulled it in and why.
$ stil why react
stil audit
Walk the lockfile and verify sha512 integrity + age of every package.
$ stil audit
stil outdated
Compare installed versions against the latest published in the registry.
$ stil outdated
stil store
Manage the local content-addressed store.
$ stil store path # print current path $ stil store stats # size + entry count $ stil store prune # drop unreferenced entries
stil mentat init
Autodetects the project stack and generates an up.yaml — the
Mentat deploy manifest. It never
copies secrets: it lifts only the names of env vars from
.env.example/.env and leaves them as
<SET_ME> placeholders for you to fill in.
$ stil mentat init # detect stack, write up.yaml $ stil mentat init --force # overwrite an existing up.yaml
Detected stacks (in priority order):
- Java —
pom.xmlorbuild.gradle→ maven/gradle build,argv: [java, -jar, …] - Next.js —
nextin deps → staged standalone build,serve: node, java profile,landlock_writable: /app - Static SPA —
vite/astro/react-scripts→serve: static, outputdist - Plain Node —
package.jsonwithout a framework →serve: nodewith an entrypoint to fill in
The domain is generated as <name>.example.com with a
TODO; edit it before deploying with mt up up.yaml.
Workspaces
The monorepo root declares workspaces as a glob array in package.json:
{
"name": "myrepo",
"private": true,
"workspaces": ["packages/*", "apps/*", "tools/build"]
}
Supported patterns (v0.2): pkg/* (immediate-child dirs containing package.json) and exact paths. ** and other recursive globs are not supported.
The Yarn-classic object form is also accepted:
{
"workspaces": { "packages": ["packages/*"], "nohoist": ["..."] }
}
workspace: protocol
Cross-workspace deps use the workspace: prefix:
{
"dependencies": {
"@myrepo/utils": "workspace:*",
"@myrepo/ui": "workspace:^",
"@myrepo/icons": "workspace:~"
}
}
stil resolves these to a relative symlink at node_modules/<name> pointing at the workspace's directory. No registry round-trip, no duplicate entry in the store.
Hoist + nest
Regular deps are hoisted to the root node_modules when there's no version conflict; with conflicts, the first version wins the top level and the rest nest under <workspace>/node_modules/. Standard npm-style behavior.
Sandbox & scripts
By default stil does NOT execute any preinstall, install, postinstall, or prepare. The summary reports how many were skipped:
18 lifecycle scripts skipped (pass --allow-scripts to run inside Hull)
With --allow-scripts, scripts run inside a Hull microVM under a seccomp node profile:
- 32 syscalls allowed (the ones a legit build needs).
- No
connect()to network. - No access to
~/.ssh,~/.aws,~/.config. - Any syscall outside the profile triggers
SECCOMP_RET_KILL_PROCESS.
The per-package decision is persisted when you answer the approval prompt (allow/deny is remembered). The stil policy command for editing it from the CLI is not implemented yet.
Packages that rely on their postinstall (Prisma, better-sqlite3, esbuild, sharp…) generate code or binaries in that script. Since stil blocks it by default, the build may fail (e.g. Module not found: '.prisma/client'). Deny-by-default only applies to third-party scripts: your own package.json scripts run normally via stil run. Recommended flow:
$ stil install # deps + audit; third-party postinstalls blocked $ stil run db:generate # your script wrapping `prisma generate` $ stil run build
On Linux, stil install --allow-scripts runs the postinstall inside Hull and skips the manual step. On macOS there is no Hull (it's a Linux container runtime), so stil refuses to run third-party scripts outside the sandbox and skips them — use the flow above.
Age policy
By default stil blocks any version published less than 7 days ago. The point is a defense against supply-chain attacks where the attacker publishes a malicious version and advisories haven't flagged it yet.
The resolver falls back automatically: if the latest version satisfying the package.json constraint doesn't pass the age check, stil picks the next-newer one that does. Example: with "react": "^19.2.4" pointing at 19.2.6 (3 days) and 19.2.5 (10 days), stil installs 19.2.5.
Change the threshold with --min-age D. --min-age 0 disables the policy (useful in day-zero CI).
Lockfile v2
The stil-lock.json file has this shape (v2):
{
"lockfileVersion": 2,
"name": "myrepo",
"workspaces": { // empty in flat projects
"packages/utils": { "name": "@my/utils", "version": "1.0.0" },
"packages/ui": { "name": "@my/ui", "version": "0.4.0" }
},
"packages": {
"@my/utils@1.0.0": { // workspace entry
"workspace": "packages/utils"
},
"react@18.3.1": { // registry entry
"resolved": "https://...",
"integrity": "sha512-...",
"published_at": 1713873600,
"hasScripts": false
}
}
}
v1 lockfiles (no workspaces field, no per-entry workspace) still load — the migrator treats them as flat installs.
Environment variables
STIL_STORE— path of the content store (default:~/.stil-store). On macOS, put it on the same APFS volume as your projects so clonefile(2) can fast-path.STIL_REGISTRY— base URL of the registry (default:https://registry.npmjs.org). Also passable as--registry.STIL_CACHE— directory for the packument cache (default:~/.stil-cache).
Troubleshooting
"AgeBlocked" stops my install
That means every version satisfying your constraint is too new. Options: lower with --min-age 3, disable with --min-age 0, or wait a few days.
Vite/Next can't find native binaries (@rollup/rollup-darwin-arm64)
Make sure you're on stil v0.2.0+. Earlier versions didn't process optionalDependencies with os/cpu filters.
permission denied running a binary from node_modules/.bin
Fixed in v0.2.1. Plenty of packages publish their bin without the +x bit (prettier ships bin/prettier.cjs as 0644) and expect the package manager to set it; stil didn't, so the symlink pointed at a non-executable file. Run stil upgrade and reinstall the project's deps. Workaround on older versions: invoke the bin through node node_modules/<pkg>/bin/<file>.
Install slow on macOS, no hardlinks
Probably cross-volume: your project is on /Volumes/X but the store is on /. clonefile(2) and hardlinks don't cross APFS volumes — point STIL_STORE at the same volume.
The installed binary dies with exit 137 (macOS)
The com.apple.provenance xattr on macOS 26 can kill binaries copied with cp. Workaround: cat orig > dest && chmod +x dest. That recreates the file and clears the attribute.