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 — skip devDependencies.
  • --frozen-lockfile — install exactly what the lockfile says, no BFS. CI mode.
  • --min-age D — minimum days since publish (default: 7). 0 disables.
  • --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.xml or build.gradle → maven/gradle build, argv: [java, -jar, …]
  • Next.js — next in deps → staged standalone build, serve: node, java profile, landlock_writable: /app
  • Static SPA — vite / astro / react-scripts → serve: static, output dist
  • Plain Node — package.json without a framework → serve: node with 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.