CLI reference

Use vex <command> --help for the full flag list accepted by your installed version. This page keeps the task-level command shapes together; the CLI changelog carries every released version’s notes.

Start here

vex login
vex whoami
vex clone <org>/<repo>
vex status

For a newly initialized or cloned Vex repository, use Vex-native commands. vex git remains available for deliberate Git interoperability work.

Repositories and changes

# Create and describe work.
vex new main
vex describe -m "Describe the change"

# Review and land it.
vex submit --target main
vex change show #42
vex land #42

# Bring your graph up to date.
vex pull
vex sync --target main

Import an existing source when you need it in a Vex Home repository:

vex repo import --org <org-slug>
vex import git https://git.example.com/team/repo.git \
  --org <org> --path apps/<slug> --virtual-repo <slug> --yes

See source control, remote Git sync, and the Git comparison for the workflow boundaries.

Clean up a working copy

A checkout that has been in use for a while accumulates residue: workspaces whose directory you deleted by hand, workspaces whose work has landed and that now hold only an empty commit, and empty undescribed commits from sessions that went nowhere. vex prune finds them.

Start by looking. On its own the command reports and changes nothing:

vex prune

Each candidate is listed under its category — stale (the working-copy directory is gone), landed (the working copy is empty and sits on trunk), and dangling (an empty, undescribed commit nothing points at) — with the reason it qualifies. A Left alone section lists what was examined and deliberately not offered.

Then remove what you want:

vex prune --interactive        # tick items in a picker: space, a for the group, enter
vex prune --yes                # take the whole plan
vex prune --only stale --yes   # one category at a time

Both paths apply in a single operation, so vex undo reverses a whole prune rather than one workspace of it.

For scripts and agents, the plan is machine-readable and the dry run is the default, so an unattended run cannot remove anything by accident:

vex prune --format json
vex prune --only dangling --older-than 30 --yes

Two boundaries worth knowing:

• Nothing on disk is deleted unless you pass --delete-files, which removes the working-copy directory of a landed workspace. That part is not covered by vex undo.
• A commit that cannot be read is never acted on. It is reported with the reason instead, so a repository with a damaged object stays prunable everywhere else.

Workspaces registered before Vex recorded workspace paths cannot be checked against the filesystem. They are reported rather than offered; --include-unlocatable offers them anyway when no directory of that name exists under your workspaces root.

Agents and context

vex setup --yes --targets codex,claude-code,cursor --with-mcp
vex setup doctor --format json
vex agent-checkpoints doctor
vex session doctor --remote --format json

Agent Context and MCP are explicit opt-ins. Use agent setup for the capability split and recovery checks.

Hosting and registry

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

See hosting for the managed runtime workflow and Vex Hub for container images.

Release notes

The CLI version is the version running on your machine:

vex --version

Read detailed notes and compatibility-relevant changes in the Vex CLI changelog.