CLI reference

Vex CLI command surface

Task-oriented command shapes for the shipped CLI. Use --help on any command for the full flag list accepted by your installed version.

Auth and identity

  • vex login
  • vex logout
  • vex whoami

Repository import

  • vex import git https://git.example.com/team/repo.git --org <org> --path <root-path> --virtual-repo <slug> --yes
  • vex import git https://git.example.com/team/repo.git --org <org> --path <root-path> --virtual-repo <slug> --sync --sync-branch main --sync-mode bidirectional --yes
  • vex import git ../existing-repo/.git --org <org> --path <root-path> --virtual-repo <slug> --yes
  • vex import github <owner>/<repo> --org <org> --path <root-path> --virtual-repo <slug> --github-app-installation-id <id> --sync-branch main --sync-mode bidirectional --yes
  • vex import github <owner>/<repo> --org <org> --path <root-path> --virtual-repo <slug> --skip-sync --yes

Source control

  • vex clone <org>/<repo>
  • vex clone <org>/<repo> --fs virtual
  • vex init
  • vex repo
  • vex git push

Stacked review and merge queue

  • vex submit --target main
  • vex submit -r 'main..@' --reviewer <email> --draft
  • vex submit --dry-run --format json
  • vex sync
  • vex sync --dry-run --format json
  • vex sync --no-restack
  • vex stack log --format json
  • vex stack merge --count 2
  • vex queue status --target main
  • vex queue pause --target main
  • vex queue retry <entry-id> --target main

Virtual working copy

  • vex daemon status --format json
  • vex daemon capabilities --format json
  • vex daemon start --format json
  • vex mount <mount-path> --repo <repo-path> --rev @ --read-write --prefetch-path src --format json
  • vex changed-files --mount-path <mount-path> --format json
  • vex hash <workspace-path> --mount-path <mount-path> --format json
  • vex prefetch <workspace-path> --mount-path <mount-path> --format json
  • vex watch --mount-path <mount-path> --follow --json
  • vex snapshot --repo <repo-path> --overlay-root <overlay-root> --format json
  • vex goto <rev> --mount-path <mount-path> --format json
  • vex checkout <rev> --mount-path <mount-path> --format json
  • vex fsck --overlay-root <overlay-root> --format json
  • vex conflicts --overlay-root <overlay-root> --format json
  • vex unmount <mount-path> --format json

Cloud workspace handoff

  • vex cloud-workspace export --mount-path <mount-path> --export-root <dir> --key-id <id> --key-file <file> --format json
  • vex cloud-workspace inspect --manifest-uri <manifest> --key-id <id> --key-file <file> --format json
  • vex cloud-workspace restore --manifest-uri <manifest> --target-overlay-root <overlay-root> --key-id <id> --key-file <file> --format json

Hosting and registry

  • vex hosting
  • vex deploy create --app <app> --service web --env production --watch
  • vex deploy dashboard --app <app>
  • vex deploy logs --app <app> <allocation-id> --task web
  • vex sites
  • vex docker setup
  • vex hub login --registry registry.vex.sc
  • vex hub push <image> --org <org> --repo <item> --tag <tag>

Stack-first compatibility

vex submit and vex sync are the canonical whole-stack commands. vex stack submit and vex stack sync remain supported compatibility spellings and use the same idempotent server operations.

Sync fetches the exact target, drops a contiguous landed or abandoned prefix, and rebases the remaining selected JJ changes when it is safe. After submit or sync, status and supported JJ mutations print an offline hint from .jj/vex-stack-state.json only when local evidence identifies an active cached-stack change. Use vex stack log for one batched server annotation of the local stack.

Submit and sync dry runs use a live read-only preflight and the same native move planner as execution, but never mutate the working copy, object store, cache, or server. Their JSON distinguishes the request before restack from an exact, no_post_all_completed, or write-safe unknown_until_apply projected server request. vex stack log --dry-run is the offline cache-only inspection mode.

Virtual working-copy boundaries

Live daemon state is local to the machine running vexd. The CLI and desktop app can query the Unix socket, but browser docs only show the server-safe capability model.

Cloud workspace commands currently use a local encrypted handoff backend. Export, inspect, and restore validate manifests and encrypted objects, but live server-side recovery still needs object storage, auth/KMS, restore routing, and cross-machine handoff UX.

Managed deployment URLs

Public services managed by Vex do not need a --deployed-url when you create a deployment from the CLI. Vex creates the app domain from the app, environment, service, and target datacenter.

  • Default datacenter: <app>-<environment>-<service>.app.vex.so
  • Other datacenters: <app>-<environment>-<service>.<dc>.app.vex.so

The platform owns the wildcard DNS records and serves these hostnames over public TLS through the edge proxy after the API confirms the domain belongs to a Vex app service.