CLI reference

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

Reuse eligible build actions within an isolated runtime

Usage: vanish action <COMMAND>

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

Build with Bazel on Linux using immutable workspace and runtime snapshots

Usage: vanish action bazel [OPTIONS] --store <STORE> --workspace <WORKSPACE> --runtime <RUNTIME> --output <OUTPUTS> -- <TARGETS>...

Arguments:
  <TARGETS>...

Options:
      --store <STORE>          local path, vanish://host:port, or managed HTTPS endpoint (token: VANISH_STORE_TOKEN)
      --workspace <WORKSPACE>  Complete immutable workspace token with vendored dependencies
      --runtime <RUNTIME>      Complete Linux filesystem token containing Bazel and its tools
      --output <OUTPUTS>       An output path under bazel-bin; repeat to return more outputs
      --env <ENVIRONMENT>      Public action environment assignment NAME=VALUE; repeat as needed
      --bazel <BAZEL>          [default: /usr/local/bin/bazel]
  -h, --help                   Print help

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

Train and publish a shared chunk dictionary for a tree

Usage: vanish dictionary <COMMAND>

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

Train a shared chunk dictionary over a tree and publish it

Usage: vanish dictionary train [OPTIONS] --source <SOURCE> --store <STORE>

Options:
  -s, --source <SOURCE>
          Directory whose chunks the dictionary is trained over

      --store <STORE>
          local path, vanish://host:port, or managed HTTPS endpoint (token: VANISH_STORE_TOKEN)

      --bytes <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 <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.

Authenticate for Vanish-managed compute

Usage: vanish login [OPTIONS]

Options:
      --token <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

Sign out: revoke this machine's token and delete the credential

Usage: vanish logout

Options:
  -h, --help  Print help

Examples:
  vanish logout

Restore an immutable snapshot into a regular directory

Usage: vanish materialize [OPTIONS] --snapshot <SNAPSHOT> --store <STORE> --destination <DESTINATION>

Options:
      --snapshot <SNAPSHOT>        The `vanish3:...` token printed by `vanish snapshot`
      --store <STORE>              local path, vanish://host:port, or managed HTTPS endpoint (token: VANISH_STORE_TOKEN)
      --destination <DESTINATION>  Directory to restore into; created if absent
      --prior <PRIOR>              A token whose unmodified materialization already sits at the destination: unchanged files are skipped in place
      --workers <WORKERS>          Concurrent fetch workers [default: 16]
      --output <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

Mount a snapshot lazily as a read-only Linux FUSE filesystem

Usage: vanish mount [OPTIONS] --snapshot <SNAPSHOT> --store <STORE> --cache <CACHE> --mountpoint <MOUNTPOINT>

Options:
      --snapshot <SNAPSHOT>
          The `vanish3:...` token to mount
      --store <STORE>
          local path, vanish://host:port, or managed HTTPS endpoint (token: VANISH_STORE_TOKEN)
      --psk <PSK>
          Pre-shared key for a vanish:// store
      --fallback <FALLBACK>
          fallback store, same URI forms as --store
      --cache <CACHE>
          Directory for the on-disk chunk cache
      --mountpoint <MOUNTPOINT>
          Where to mount the read-only filesystem
      --ready-pipe <READY_PIPE>
          Write one byte to this existing FIFO after mounting (worker internals)
      --metrics <METRICS>
          Where to write the metrics JSON; `-` is stdout [default: -]
      --prefetch <PREFETCH>
          Predictive chunk prefetch depth; 0 disables prefetch [default: 0]
      --max-fetches <MAX_FETCHES>
          Concurrent chunk fetches [default: 32]
      --cache-size <CACHE_SIZE>
          On-disk cache bound, bytes; 0 is unbounded [default: 0]
      --ram-cache <RAM_CACHE>
          RAM cache bound, bytes [default: 268435456]
      --fetch-all
          Download the whole snapshot up front instead of lazily
      --witness-plan <WITNESS_PLAN>
          Execution witness plan steering prefetch (worker internals)
      --witness-trace <WITNESS_TRACE>
          Where to record the access trace (worker internals)
      --toolchain <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 <TOOLCHAIN_ARCH>
          Architecture of `--toolchain`
      --debug
          Log every FUSE operation
      --kernel-backing <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 <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

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 <OPERATION>      Retry just this full operation ID; leave other records untouched
      --destination <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

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

Fold a staged result into the working tree and drop the staged copy

Usage: vanish results apply [OPTIONS] <TOKEN>

Arguments:
  <TOKEN>  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

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

Show the immutable input, delta and workspace roots retained for a Run

Usage: vanish results reference [OPTIONS] <TOKEN>

Arguments:
  <TOKEN>

Options:
      --json  Print the result as JSON instead of text
  -h, --help  Print help

Abandon an interrupted apply plan, preserving output, applied edits, and backups

Usage: vanish results replan [OPTIONS] <TOKEN>

Arguments:
  <TOKEN>

Options:
      --json  Print the result as JSON instead of text
  -h, --help  Print help

Hard-delete a staged result

Usage: vanish results rm [OPTIONS] <TOKEN>

Arguments:
  <TOKEN>  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

Preload a snapshot and serve it from RAM over one multiplexed TCP connection

Usage: vanish serve [OPTIONS] --store <STORE>

Options:
      --snapshot <SNAPSHOT>
          The `vanish3:...` token to preload into RAM; omit to serve every snapshot in the store on demand
      --store <STORE>
          local path, vanish://host:port, or managed HTTPS endpoint (token: VANISH_STORE_TOKEN)
      --listen <LISTEN>
          TCP listen address; a bare `:PORT` binds every interface [default: :7777]
      --psk <PSK>
          Pre-shared key clients must present; unset means unauthenticated
      --max-connections <MAX_CONNECTIONS>
          Concurrent client connections [default: 256]
      --ram-cache <RAM_CACHE>
          RAM cache bound, bytes [default: 1073741824]
      --inflight-bytes <INFLIGHT_BYTES>
          In-flight response bound, bytes [default: 1073741824]
      --preload-workers <PRELOAD_WORKERS>
          Workers preloading the snapshot into RAM [default: 32]
      --metrics <METRICS>
          Where to write the metrics JSON; `-` is stdout [default: -]
      --ready-file <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

Store a directory as an immutable content-addressed snapshot

Usage: vanish snapshot [OPTIONS] --source <SOURCE> --store <STORE>

Options:
  -s, --source <SOURCE>
          Directory to snapshot

      --store <STORE>
          local path, vanish://host:port, or managed HTTPS endpoint (token: VANISH_STORE_TOKEN)

      --workers <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 <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 <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)

Manage reproducible, lazily mounted toolchains

Usage: vanish toolchain <COMMAND>

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

Bake a named toolchain by observing an installer command

Usage: vanish toolchain bake [OPTIONS] <NAME> -- <SETUP>...

Arguments:
  <NAME>      Name to bake under; runs mount it with `--toolchain NAME`
  <SETUP>...  The installer command, after `--`; its filesystem writes become the toolchain

Options:
      --arch <ARCHITECTURE>  `x86_64` or `arm64`; empty bakes for the run default [default: ""] [possible values: "", arm64, x86_64]
      --cpu <CPU>            vCPUs for the bake worker [default: 4]
      --watchdog <WATCHDOG>  Hard stop for a hung bake, seconds [default: 3600]
      --disk <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

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

Remove every descriptor for a toolchain

Usage: vanish toolchain rm [OPTIONS] <NAME>

Arguments:
  <NAME>  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

Show every architecture descriptor for a toolchain

Usage: vanish toolchain show [OPTIONS] <NAME>

Arguments:
  <NAME>  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

Check for a newer release and apply it now

Usage: vanish update

Options:
  -h, --help  Print help

Examples:
  vanish update

Print the installed Vanish version

USAGE
  vanish version

EXAMPLES
  vanish version
  VERSION=$(vanish version)