# CLI reference (/docs/cli-reference) Command help from Vanish v0.4.13. ## vanish help [#vanish-help] ```text vanish - run local workspaces remotely without rebuilding them USAGE vanish [FLAGS] COMMAND [ARGS...] Put vanish in front of the command you already run. Your command starts at the first token that is not a vanish flag, and everything from there is sent verbatim. There is no `run` subcommand and no `--` separator. EXAMPLES vanish cargo test vanish make -j8 vanish pytest -k slow --maxfail=1 The default shape is served from a warm pool and reaches first output in about two seconds. Asking for more than the pool holds means waiting for an instance to boot, which took about 26 seconds when last measured, so raise --cpu and --mem when the work pays for the wait rather than by default. A bare word listed under SUBCOMMANDS is always the vanish subcommand; any token containing `/` is always a program. Nothing consults PATH or the working directory, so `vanish serve` is the subcommand and `vanish ./serve` is your program — the `make` versus `./make` convention. Piped or redirected stdin is streamed to the remote command, which sees end-of-file when the local pipe closes: `cat data | vanish ./process` means what it means locally. A terminal is not forwarded — the command reads EOF immediately, as under nohup. FLAGS --cpu N vCPUs the job needs [8] --mem GIB memory the job needs [16] --arch ARCH x86_64 or arm64 [arm64] --disk GIB worker root volume [100] --packages LIST system packages to install, comma or space separated --toolchain NAME baked toolchain to mount --source DIR workspace root [git root] --ignore LIST extra ignore patterns, comma separated --tunnel egress this run's network through this machine, so a server sees your address and your sessions --expose PORTS loopback ports on this machine the run may reach through the tunnel, as host.vanish.internal; implies --tunnel --watchdog SECS hard stop for a hung job [14400] --prefetch N chunk prefetch depth on the worker [2] --fetch-all download the whole snapshot up front --cache-size B worker chunk-cache bound, bytes [0 = unbounded] --no-local-trace skip the sandboxed local trace that seeds prefetch --dictionary ID compress uploads against a published chunk dictionary every reader must be a client new enough to know it --no-prefix-coding stop a segment's own first record compressing its siblings; on by default, off publishes segments an older client can still read --dry-run print the run plan locally, provision nothing --apply apply results if the workspace still matches submission --input-snapshot T use an existing immutable workspace token as input --from-result ID continue from a retained remote workspace --remote-results retain the full workspace remotely for another run --no-build-cache rebuild from an empty target/ instead of reusing this workspace's build artifacts; delete .vanish/build-cache to forget them --keep let a started run finish after a client error workers stop after the run; Ctrl-C still cancels --memoize replay an identical completed run instead of running it a memoized run does not execute, so it does not repeat what the command did outside its workspace: off by default --timings print phase and complete invocation timings -v, --verbose print what vanish consumed against what you sent Defaults come from the nearest .vanish.toml, then the built-ins above; a flag you type always wins. `vanish config` prints every effective value and where it came from. SUBCOMMANDS Everyday results list, apply and delete staged run results config print the effective configuration and its origins recover inspect or recover abandoned runs (--list, --operation ID) toolchain bake, list, show and remove baked toolchains login sign in (headless: set VANISH_TOKEN from the account page) update check for a newer release and apply it now logout revoke this machine's token version, help Snapshot engine, local and offline: no account, no cloud snapshot store a directory as an immutable snapshot materialize restore a snapshot into a directory dictionary train and publish a shared chunk dictionary (opt-in) Engine internals, for Linux workers and debugging them action reuse eligible build actions in an isolated Linux runtime mount mount a snapshot lazily as a read-only FUSE filesystem serve serve a snapshot from RAM over one connection Set VANISH_TIMINGS_JSON=/path/report.json for a complete timing artifact. Run `vanish SUBCOMMAND --help` for a subcommand's own flags. Help and community: https://discord.gg/n8pwXcqmAM ``` ## vanish action --help [#vanish-action---help] ```text Reuse eligible build actions within an isolated runtime Usage: vanish action Commands: bazel Build with Bazel on Linux using immutable workspace and runtime snapshots help Print this message or the help of the given subcommand(s) Options: -h, --help Print help ``` ## vanish action bazel --help [#vanish-action-bazel---help] ```text Build with Bazel on Linux using immutable workspace and runtime snapshots Usage: vanish action bazel [OPTIONS] --store --workspace --runtime --output -- ... Arguments: ... Options: --store local path, vanish://host:port, or managed HTTPS endpoint (token: VANISH_STORE_TOKEN) --workspace Complete immutable workspace token with vendored dependencies --runtime Complete Linux filesystem token containing Bazel and its tools --output An output path under bazel-bin; repeat to return more outputs --env Public action environment assignment NAME=VALUE; repeat as needed --bazel [default: /usr/local/bin/bazel] -h, --help Print help ``` ## vanish config --help [#vanish-config---help] ```text Print the effective configuration and where each value comes from Usage: vanish config [OPTIONS] Options: --json Print the settings as a JSON object instead of the table -h, --help Print help Examples: vanish config vanish config --json vanish config --json | jq .settings.cpu ``` ## vanish dictionary --help [#vanish-dictionary---help] ```text Train and publish a shared chunk dictionary for a tree Usage: vanish dictionary Commands: train Train a shared chunk dictionary over a tree and publish it help Print this message or the help of the given subcommand(s) Options: -h, --help Print help ``` ## vanish dictionary train --help [#vanish-dictionary-train---help] ```text Train a shared chunk dictionary over a tree and publish it Usage: vanish dictionary train [OPTIONS] --source --store Options: -s, --source Directory whose chunks the dictionary is trained over --store local path, vanish://host:port, or managed HTTPS endpoint (token: VANISH_STORE_TOKEN) --bytes Trained dictionary size, bytes. The 64 KiB default comes from a held-out measurement on this project's own source tree: trained on half the files and scored on the other half it saves 3.0% of published bytes and repays its own transfer after about six publications, while 16 KiB saves 2.1% and zstd's own 112 KiB `--train` default over-fits to 2.68% and costs 75% more to fetch. [default: 65536] --output Where to write the stats JSON (the id is `.id`); `-` is stdout [default: -] -h, --help Print help (see a summary with '-h') Examples: vanish dictionary train --source . --store /tmp/cas ID=$(vanish dictionary train --source . --store /tmp/cas | jq -r .id) vanish snapshot --source . --store /tmp/cas --dictionary "$ID" Training is out of band on purpose: it reads a bounded sample of the tree once, and publication never does it implicitly. Retrain when the corpus has drifted enough that published bytes stop shrinking; an old dictionary never becomes wrong, only less useful, and snapshots that named it keep working as long as the artifact stays in the store. ``` ## vanish login --help [#vanish-login---help] ```text Authenticate for Vanish-managed compute Usage: vanish login [OPTIONS] Options: --token Store a token without opening a browser --json Print a JSON result instead of text -h, --help Print help Examples: vanish login vanish login --token "$VANISH_TOKEN" VANISH_TOKEN=token-from-account vanish cargo test ``` ## vanish logout --help [#vanish-logout---help] ```text Sign out: revoke this machine's token and delete the credential Usage: vanish logout Options: -h, --help Print help Examples: vanish logout ``` ## vanish materialize --help [#vanish-materialize---help] ```text Restore an immutable snapshot into a regular directory Usage: vanish materialize [OPTIONS] --snapshot --store --destination Options: --snapshot The `vanish3:...` token printed by `vanish snapshot` --store local path, vanish://host:port, or managed HTTPS endpoint (token: VANISH_STORE_TOKEN) --destination Directory to restore into; created if absent --prior A token whose unmodified materialization already sits at the destination: unchanged files are skipped in place --workers Concurrent fetch workers [default: 16] --output Where to write the stats JSON; `-` is stdout [default: -] -h, --help Print help Examples: vanish materialize --snapshot "$TOKEN" --store /tmp/cas --destination ./out vanish materialize --snapshot "$NEW" --prior "$OLD" --store /tmp/cas --destination ./out ``` ## vanish mount --help [#vanish-mount---help] ```text Mount a snapshot lazily as a read-only Linux FUSE filesystem Usage: vanish mount [OPTIONS] --snapshot --store --cache --mountpoint Options: --snapshot The `vanish3:...` token to mount --store local path, vanish://host:port, or managed HTTPS endpoint (token: VANISH_STORE_TOKEN) --psk Pre-shared key for a vanish:// store --fallback fallback store, same URI forms as --store --cache Directory for the on-disk chunk cache --mountpoint Where to mount the read-only filesystem --ready-pipe Write one byte to this existing FIFO after mounting (worker internals) --metrics Where to write the metrics JSON; `-` is stdout [default: -] --prefetch Predictive chunk prefetch depth; 0 disables prefetch [default: 0] --max-fetches Concurrent chunk fetches [default: 32] --cache-size On-disk cache bound, bytes; 0 is unbounded [default: 0] --ram-cache RAM cache bound, bytes [default: 268435456] --fetch-all Download the whole snapshot up front instead of lazily --witness-plan Execution witness plan steering prefetch (worker internals) --witness-trace Where to record the access trace (worker internals) --toolchain Baked toolchain this snapshot is the root of (worker internals): prefetch what its earlier runs read before mounting, and record this run's reads for the next one --toolchain-arch Architecture of `--toolchain` --debug Log every FUSE operation --kernel-backing Serve file data through the kernel from verified backing files: `memory` for sealed memfds, or a directory on an unstacked fs-verity filesystem. Needs `CAP_SYS_ADMIN` in the initial user namespace (microVM guests); without it the mount serves from userspace as usual --kernel-backing-size Byte budget for kernel backing files; 0 picks the medium's default [default: 0] -h, --help Print help Examples: vanish mount --snapshot "$TOKEN" --store /tmp/cas --cache /mnt/nvme/vanish-cache --mountpoint /lower --prefetch 2 vanish mount --snapshot "$TOKEN" --store vanish://10.0.1.23:7777 --psk "$PSK" --cache /mnt/nvme/vanish-cache --mountpoint /lower ``` ## vanish recover --help [#vanish-recover---help] ```text Cancel abandoned runs recorded by this client Usage: vanish recover [OPTIONS] Options: --json Emit per-operation cleanup and result status as JSON --list Inspect pending operations without contacting workers or downloading results --operation Retry just this full operation ID; leave other records untouched --destination Stage recovered results in this existing directory --discard-results Forget this operation's pending output, while preserving required cleanup; without --operation, clear every permanently rejected record -h, --help Print help ``` ## vanish results --help [#vanish-results---help] ```text List, apply and delete staged run results Usage: vanish results [OPTIONS] [COMMAND] Commands: backups List recovery copies retained after applying deletions or type changes reference Show the immutable input, delta and workspace roots retained for a Run apply Fold a staged result into the working tree and drop the staged copy replan Abandon an interrupted apply plan, preserving output, applied edits, and backups rm Hard-delete a staged result help Print this message or the help of the given subcommand(s) Options: --json Print the result as JSON instead of text -h, --help Print help Examples: vanish results vanish results --json vanish results apply 7f3a91 --dry-run vanish results apply 7f3a91 --force --yes vanish results rm 7f3a91 --yes ``` ## vanish results apply --help [#vanish-results-apply---help] ```text Fold a staged result into the working tree and drop the staged copy Usage: vanish results apply [OPTIONS] Arguments: Job id, or any unambiguous prefix of one Options: --dry-run Print every create, replacement and unchanged entry without writing --json Print the result as JSON instead of text --force Permit replacement of existing workspace entries --yes Skip the confirmation prompt -h, --help Print help Examples: vanish results apply 7f3a91 --dry-run vanish results apply 7f3a91 --force --yes vanish results apply 7f3a91 --force --yes --json ``` ## vanish results backups --help [#vanish-results-backups---help] ```text List recovery copies retained after applying deletions or type changes Usage: vanish results backups [OPTIONS] Options: --json Print the result as JSON instead of text -h, --help Print help ``` ## vanish results reference --help [#vanish-results-reference---help] ```text Show the immutable input, delta and workspace roots retained for a Run Usage: vanish results reference [OPTIONS] Arguments: Options: --json Print the result as JSON instead of text -h, --help Print help ``` ## vanish results replan --help [#vanish-results-replan---help] ```text Abandon an interrupted apply plan, preserving output, applied edits, and backups Usage: vanish results replan [OPTIONS] Arguments: Options: --json Print the result as JSON instead of text -h, --help Print help ``` ## vanish results rm --help [#vanish-results-rm---help] ```text Hard-delete a staged result Usage: vanish results rm [OPTIONS] Arguments: Job id, or any unambiguous prefix of one Options: --dry-run Print the result that would be deleted without deleting it --json Print the result as JSON instead of text --yes Skip the confirmation prompt -h, --help Print help Examples: vanish results rm 7f3a91 --dry-run vanish results rm 7f3a91 --yes vanish results rm 7f3a91 --yes --json ``` ## vanish serve --help [#vanish-serve---help] ```text Preload a snapshot and serve it from RAM over one multiplexed TCP connection Usage: vanish serve [OPTIONS] --store Options: --snapshot The `vanish3:...` token to preload into RAM; omit to serve every snapshot in the store on demand --store local path, vanish://host:port, or managed HTTPS endpoint (token: VANISH_STORE_TOKEN) --listen TCP listen address; a bare `:PORT` binds every interface [default: :7777] --psk Pre-shared key clients must present; unset means unauthenticated --max-connections Concurrent client connections [default: 256] --ram-cache RAM cache bound, bytes [default: 1073741824] --inflight-bytes In-flight response bound, bytes [default: 1073741824] --preload-workers Workers preloading the snapshot into RAM [default: 32] --metrics Where to write the metrics JSON; `-` is stdout [default: -] --ready-file File created once the listener is ready, for supervisors to await -h, --help Print help Examples: vanish serve --snapshot "$TOKEN" --store /tmp/cas --listen :7777 --psk "$(openssl rand -hex 16)" vanish serve --store /tmp/cas --ready-file /run/vanish-serve.ready ``` ## vanish snapshot --help [#vanish-snapshot---help] ```text Store a directory as an immutable content-addressed snapshot Usage: vanish snapshot [OPTIONS] --source --store Options: -s, --source Directory to snapshot --store local path, vanish://host:port, or managed HTTPS endpoint (token: VANISH_STORE_TOKEN) --workers Upload workers; 0 picks a size from the tree [default: 0] --normalize-mtimes Store every file mtime as zero so identical content yields identical snapshots across checkouts --dictionary Compress this snapshot's chunks against a published chunk dictionary, named by the id `vanish dictionary train` printed. Off by default. Segments that keep a dictionary-compressed record carry a header older vanish clients refuse to read, so every reader of this snapshot must be new enough to know it. --no-prefix-coding Do not let a segment's own first record compress its siblings. Prefix coding is on by default: it needs no artifact, no training pass and no retention promise, unlike `--dictionary`. It does move the reader-version boundary — a client older than this release refuses a prefix-coded segment outright — so this flag exists for a tenant that still has old readers against the same store. --output Where to write the stats JSON (the token is `.token`); `-` is stdout [default: -] -h, --help Print help (see a summary with '-h') Examples: vanish snapshot --source . --store /tmp/cas --output stats.json TOKEN=$(vanish snapshot --source ./tree --store /tmp/cas | jq -r .token) ``` ## vanish toolchain --help [#vanish-toolchain---help] ```text Manage reproducible, lazily mounted toolchains Usage: vanish toolchain Commands: bake Bake a named toolchain by observing an installer command list List toolchains in your content store show Show every architecture descriptor for a toolchain rm Remove every descriptor for a toolchain help Print this message or the help of the given subcommand(s) Options: -h, --help Print help Examples: vanish toolchain list --json vanish toolchain show rust --json vanish toolchain bake rust -- cargo install cargo-nextest vanish toolchain rm rust --dry-run ``` ## vanish toolchain bake --help [#vanish-toolchain-bake---help] ```text Bake a named toolchain by observing an installer command Usage: vanish toolchain bake [OPTIONS] -- ... Arguments: Name to bake under; runs mount it with `--toolchain NAME` ... The installer command, after `--`; its filesystem writes become the toolchain Options: --arch `x86_64` or `arm64`; empty bakes for the run default [default: ""] [possible values: "", arm64, x86_64] --cpu vCPUs for the bake worker [default: 4] --watchdog Hard stop for a hung bake, seconds [default: 3600] --disk Bake worker root volume, GiB [default: 100] -h, --help Print help Examples: vanish toolchain bake rust -- sh -c 'curl https://sh.rustup.rs -sSf | sh -s -- -y' vanish toolchain bake node --arch x86_64 -- dnf install -y nodejs ``` ## vanish toolchain list --help [#vanish-toolchain-list---help] ```text List toolchains in your content store Usage: vanish toolchain list [OPTIONS] Options: --json Print a JSON array instead of a table -h, --help Print help Examples: vanish toolchain list vanish toolchain list --json ``` ## vanish toolchain rm --help [#vanish-toolchain-rm---help] ```text Remove every descriptor for a toolchain Usage: vanish toolchain rm [OPTIONS] Arguments: Toolchain name, as printed by `vanish toolchain list` Options: --dry-run Print the descriptors that would be deleted without deleting them --yes Skip the confirmation prompt --json Print a JSON result instead of text -h, --help Print help Examples: vanish toolchain rm rust --dry-run vanish toolchain rm rust --yes vanish toolchain rm rust --yes --json ``` ## vanish toolchain show --help [#vanish-toolchain-show---help] ```text Show every architecture descriptor for a toolchain Usage: vanish toolchain show [OPTIONS] Arguments: Toolchain name, as printed by `vanish toolchain list` Options: --json Print one JSON array containing every architecture descriptor -h, --help Print help Examples: vanish toolchain show rust vanish toolchain show rust --json ``` ## vanish update --help [#vanish-update---help] ```text Check for a newer release and apply it now Usage: vanish update Options: -h, --help Print help Examples: vanish update ``` ## vanish version --help [#vanish-version---help] ```text Print the installed Vanish version USAGE vanish version EXAMPLES vanish version VERSION=$(vanish version) ```