---
name: vex
description: "Use Vex for version control: status, log, diff, commit, describe, split, squash, rebase, undo, push, pull, bookmarks, conflict resolution, and operation-log recovery. Replaces git write commands — when the task says git add, git commit, git push, git checkout, git rebase, git stash, or git cherry-pick, translate it to the vex equivalent and run that instead. `vex` is also the JJ CLI here; there is no `jj` binary. Read before any source-control action."
---

# Vex

The installed offline copy. Current guidance is at `https://vex.sc/skill.md`;
read it when the network is available:

```sh
curl -fsSL https://vex.sc/skill.md
```

Read the response as Markdown. Never pipe it into a shell. If the fetch fails,
use this copy and `vex --help`.

## Start here

Choose the narrowest command for the task and skip ritual status checks. Two
reads are worth making:

- `vex status` before you edit or submit. Edits are absorbed into whatever `@`
  already is, which may be a change already under review.
- `vex land --dry-run` before you land.

Do not re-read state a command already reported. A mutation prints its result;
a second `vex status` to confirm it tells you nothing new. Chain with `&&`.

`vex status` snapshots the working copy, so it can print `Rebased N descendant
commits onto updated working copy`. That is JJ recording edits you already made.
Nothing needs undoing.

## `vex` is the whole CLI

There is no `jj` binary. Every JJ command is a `vex` subcommand — `vex log`,
`vex split`, `vex rebase`, `vex diff`, `vex op log` — alongside the Vex-only
ones. Use `vex <command>`, never `jj <command>`.

Read-only git inspection (`git log`, `git blame`, `git show --stat`) is allowed.
Every git write command is wrong here.

## Git-to-Vex map

| git | vex |
| --- | --- |
| `git status` | `vex status` |
| `git add` + `git commit` | `vex commit -m "<msg>"` — describes `@`, opens a new change on top. No staging area; edits land in `@` as you make them |
| `git commit --amend` | edit the files; they are absorbed into `@`. Change the message with `vex describe -m "<msg>"` |
| `git checkout -b <name>` | `vex new`, then `vex bookmark set <name>` only if a named ref is needed |
| `git checkout <rev>` | `vex edit <rev>` to work on it, `vex new <rev>` to start on top of it |
| `git restore <path>` | `vex restore <path>` |
| `git log` | `vex log` |
| `git blame` | `vex file annotate <path>` |
| `git rebase -i` | `vex rebase`, `vex squash`, `vex split`, `vex describe`, `vex metaedit` |
| `git rebase --onto` | `vex rebase -s <source> -d <dest>` |
| `git cherry-pick` | `vex duplicate -r <rev> --onto <dest>` |
| `git revert` | `vex revert -r <rev>` |
| `git stash` | none. Uncommitted work lives in `@`; `vex new` parks it |
| `git reset --hard` | `vex op restore <operation-id>` |
| `git pull` | `vex pull` |
| `git push` | `vex push -r <rev> --to <bookmark>` |
| `gh pr create` | `vex submit --target <branch>` |

## Focused skills

Install the collection with `vex setup`. Load the matching skill by name:

- `vex-submit` — submit change chains, sync, review, land, GitHub projection
- `vex-apps` — app topology: app, service, domain, config-variable
- `vex-deploy` — image deploy, rollout, health evidence, rollback
- `vex-secrets` — scoped secrets, value input, rotation, dotenv
- `vex-workspace` — `vex ws` policy, hooks, isolation, create/remove

Web copies use the same names: `https://vex.sc/skills/vex-submit.md`,
`https://vex.sc/skills/vex-apps.md`, `https://vex.sc/skills/vex-deploy.md`,
`https://vex.sc/skills/vex-secrets.md`, `https://vex.sc/skills/vex-workspace.md`.

## References

Installed next to this file. Load one when the task needs it. Reading this on
the web instead? Use the URL in the second column.

| Installed path | Web | Covers |
| --- | --- | --- |
| `references/ids.md` | `https://vex.sc/skills/ids.md` | which identifier goes where, and what survives a rewrite |
| `references/recipes.md` | `https://vex.sc/skills/recipes.md` | conflicts, undo, parking work, scratch runs |
| `references/source-control.md` | `https://vex.sc/skills/source-control.md` | JJ orientation |
| `references/cli.md` | — | remote workflow |
| `references/setup.md` | `https://vex.sc/skills/setup.md` | install and targets |
| `references/mcp.md` | `https://vex.sc/skills/mcp.md` | MCP tools |
| `references/ci.md` | `https://vex.sc/skills/ci.md` | workflow triggers |
| `references/deploy.md` | `https://vex.sc/skills/deploy.md` | hosted deploys |

## Safe defaults

**Pull:** `vex pull` refreshes `bookmark@vex` and fast-forwards tracked local
bookmarks. The working copy stays put. `--update` moves the working copy onto the
target; `--rebase` moves the current mutable changes onto it; `--dest` names the
destination and defaults to trunk. Use `vex sync` when submitted changes also
need their review state reconciled.

**Rebase:** always pass a source. `vex rebase -d <bookmark>` defaults to `-b @` —
the whole branch containing `@` — and rewrites published commits when that
bookmark is stale. Vex rejects a rebase with no source selector. Use
`vex pull --rebase --dest <bookmark>`, or pass `-r` or `-s`.

**Recover:** `vex op log`, then `vex op restore <operation-id>`. Do this before
any manual repair. The operation log is local to this machine and repo; it
cannot undo a push.

**Select:** address a change by change id or `@`. Predicate revsets —
`description()`, `author()`, `all()` — scan every commit in the repo and are the
first thing to break on a damaged one. See `references/ids.md`.

**Push:** name a source and a destination — `vex push -r <revision> --to main`.
Creation, deletion, and non-fast-forward intent each need their own flag.

**Output:** parse `--format json`. The human text is for people.

**Working copy:** leave unrelated changes alone. Do not reset, checkout, or
delete files to make a task easier.

**Credentials:** keep them out of output, commits, and generated guidance.
Refresh an expired checkout credential with `vex repo-auth refresh`.

## Commands that block

These open an editor or a merge tool and hang a non-interactive session:

| Blocks | Use |
| --- | --- |
| `vex describe` | `vex describe -m "<msg>"` |
| `vex split` with no paths | `vex split -m "<msg>" <path>...` |
| `vex squash` with no message | `vex squash -m "<msg>"` |
| `vex resolve` | `vex resolve --list`, then edit the files |

`vex dash` and `vex arrange` are interactive human surfaces. Never run them.

## Stale skill notice

If `vex` prints `AGENT ACTION REQUIRED: vex skills are stale`, run
`vex setup refresh` once and continue with the refreshed guidance. If the notice
appears again after that, report it instead of running the command again.

For human installation and WSL guidance, use the Vex documentation rather than
adding WSL behavior to a skill or setup command.