Command reference

fend <command> is the default — anything that isn’t a known subcommand is dispatched to fend run <command>.

fend <cmd> (alias: fend run)

Run an arbitrary command inside the sandbox.

fend npm install
fend bun run dev
fend python train.py
fend --env DATABASE_URL=postgres://… npm run seed
fend --env-file .env.local npm test

Flag	Description
-e, --env KEY=VALUE	Inject one env var into the sandbox. Repeatable.
--env-file PATH	Load env vars from a .env-style file. Repeatable; later files win.

If the command is a known package-manager install (npm install, bun add, …), fend audits the lockfile against OSV.dev first. See [audit] in .fend.toml for policy.

fend audit

Audit the current project’s package-lock.json against OSV.dev.

fend audit               # report only
fend audit --fix         # apply safe in-range upgrades + npm overrides
fend audit --fix --force # also apply major-version bumps
fend audit --json        # structured output for CI

Flag	Description
--fix	Apply the safe portion of the upgrade plan.
--force	When fixing, also apply major-version bumps.
--include-prerelease	Consider RC / pre-release fix versions.
--dry-run	Print the plan without applying it.
-y, --yes	Skip prompts (CI-friendly).
--json	Emit structured JSON instead of a human-readable report.
--update-db	Re-query advisories even if the local cache is fresh.

fend claude [cmd]

Run a command with the Anthropic OAuth token from your macOS Keychain injected into the sandbox.

fend claude                 # runs `claude` with the token injected
fend claude my-script.sh    # runs anything else with the same env

The default fend <cmd> path never injects Anthropic credentials. This is opt-in by design.

fend init

Generate a .fend.toml for the current project. Detects the project kind (Node, Bun, pnpm, yarn, Python, generic) and writes a sensible default.

Flag	Description
--force	Overwrite an existing .fend.toml without prompting.

fend hook <shell>

Print shell integration code for eval-ing in your shell config.

echo 'eval "$(fend hook zsh)"' >> ~/.zshrc
echo 'eval "$(fend hook bash)"' >> ~/.bashrc

After installing the hook, use fend on / fend off to toggle the sandbox in the current shell session.

The hook shims: npm, npx, bun, bunx, yarn, pnpm, pnpx, node, python, python3, uv, uvx, deno.

fend on / fend off

Activate or deactivate the shell hook in the current session. These exist as shell functions installed by fend hook — invoking them as a binary subcommand prints a hint to install the hook first.

fend status

Show running VMs across all projects.

$ fend status
PROJECT                          STATE       UPTIME     PORTS
my-app                           running     12m 4s     3000
api                              paused      5m 30s

fend stop

Stop the VM for the current project. The VM will cold-boot again on the next command.

fend clean

Destroy the VM and per-project state for the current project, including the rootfs clone.

fend doctor

Check prerequisites and print system compatibility:

$ fend doctor
fend doctor
  macOS version: 14.5.0
  Architecture:  Apple Silicon (arm64)
  Kernel:        ~/.fend/runtime/vmlinuz
  Initrd:        ~/.fend/runtime/initrd
  Rootfs:        ~/.fend/runtime/rootfs.img
  Docker:        available
  Config:        node=auto bun=auto cpus=2 mem=2048MB

  All checks passed.

fend log

Tail the per-command audit log written to ~/.fend/log/. Each entry contains the command, args, env keys (not values), duration, exit code, audit summary, and any project-dir filesystem changes.

fend daemon start | stop

Manage the background daemon. fend <cmd> auto-starts the daemon on first use; you rarely need to run these directly.

Subcommand	Description
daemon start	Start the daemon (defaults to detached). --foreground keeps it attached.
daemon stop	Send SIGTERM to the daemon and clean up the pid/socket files.

.fend.toml configuration

Generated by fend init. Every field is optional:

[runtime]
node = "22"                          # pin Node.js inside the VM
bun  = "1.1"                         # pin Bun inside the VM

[vm]
cpus = 2
memory = "2GB"

[audit]
level = "strict"                     # strict | warn | off
rebuild = true                       # run `npm rebuild` after a clean audit
auto_approve_in_ci = false           # skip prompts when $CI is set
block = ["malware", "critical"]      # severities that halt the install
prompt = ["high"]                    # severities that require y/N confirmation
fix_on_install = true                # offer to apply safe fixes before install
include_prerelease = false           # consider pre-release versions when fixing