The vertex CLI

The vertex binary is the entire toolchain: runner, test runner, compiler, and language server. This page is the command reference.

Overview

vertex <command> [options]

Command	Purpose
run	Run a .vtx file via JIT or on a Salesforce org
test	Run @Test functions in *_test.vtx files
build	Compile .vtx files in the project to Apex class files
check	Parse and type-check a .vtx file without executing it
docs	Browse the Vertex language reference offline
lsp	Start the Language Server on stdio

Flags:

Flag	Effect
--help, -h	Show help
--version, -v	Show version

vertex run

vertex run [options] <file>

Runs a .vtx file. Default mode is JIT (local execution); add --sf to run on a Salesforce org instead.

Flag	Effect
(none)	JIT mode. Execute locally, print debug output to stdout.
--sf	Salesforce mode. Generate Anonymous Apex and execute on the org.
--org <alias>	Salesforce org alias. Requires --sf.
--compare	Run both JIT and Salesforce and diff output line-for-line. --sf required.
--dump-apex	Print the generated Anonymous Apex to stdout and exit.
--help, -h	Show help for this command.

Standalone files. A file with no imports runs anywhere, no project required:

$ vertex run hello.vtx
hello, vertex!

Files that import other modules. When a file has import statements, Vertex looks up to find an sfdx-project.json and uses the project’s src/ directory as the module root:

my-project/
├── sfdx-project.json
└── src/
    ├── greet.vtx
    └── main.vtx      # import greet

Then:

$ vertex run src/main.vtx

See Project structure for the full layout rules.

--compare in practice. This is a development aid: it runs your file once via the JIT, once on the org, and diffs the two outputs. It exits 0 only when the output matches line-for-line.

$ vertex run --sf --org scratch --compare examples/hello.vtx
outputs match (1 line(s))

Note

--compare is a sanity check for codegen, not a normal dev tool. Most of the time vertex run <file> (JIT) is all you need.

vertex test

vertex test [options] [<file>]

Runs @Test functions. With no file argument, discovers every *_test.vtx file in the project’s src/ and runs them all.

Flag	Effect
--filter <name>	Only run tests whose name contains <name>.
--src <dir>	Source directory to search (default: src).
--no-color	Disable ANSI color in output.
--help, -h	Show help for this command.

Rules:

• Test files must end in _test.vtx.
• Test functions are marked @Test and take no parameters.
• Exit code is 0 when all tests pass, 1 when any test fails. Zero discovered tests is still a pass.

$ vertex test src/billing/invoice_test.vtx
✓ invoice totals include tax
✓ zero-line invoice is rejected
2 passed, 0 failed  (47ms)

$ vertex test --filter invoice

See Testing for the full guide.

vertex build

vertex build [options]

Compiles every .vtx file in the project’s source directory to Apex class files. Writes the .cls + .cls-meta.xml pair for each file to force-app/main/default/classes/.

Flag	Effect
--src <dir>	Source directory (default: src).
--help, -h	Show help for this command.

Run from the project root:

$ vertex build
Success! Built 3 class(es) to force-app/main/default/classes/

Then deploy with:

$ sf project deploy start --target-org <alias>

vertex check

vertex check <file>

Parses, resolves imports, and type-checks a .vtx file, then exits. No code is generated, no program is executed. This is the fast feedback loop for editors and for LLM agents writing Vertex: the same Elm-style diagnostics as vertex run, minus the run step.

Semantically it is to vertex run what cargo check is to cargo run.

Flag	Effect
--no-color	Disable ANSI color in diagnostics.
--help, -h	Show help for this command.

Exit codes. 0 when the file is valid (warnings are printed but do not fail the command). 1 when any parse, import, or type error is reported.

$ vertex check src/billing/invoices.vtx
$ echo $?
0

$ vertex check broken.vtx
broken.vtx:3:14
error[E100]: type mismatch: expected Int, found String
 --> 3:14
  |
3 | let n: Int = "oops"
                 ^
$ echo $?
1

The file:line:col header on the first line is deterministic, so an agent can parse diagnostics without regex-matching the colored body.

vertex docs

vertex docs                    # print the curated index
vertex docs list               # one slug per line (machine-readable)
vertex docs <topic>            # print a single reference page
vertex docs full               # print the full concatenated reference
vertex docs small              # print the compact reference (smaller context budget)
vertex docs bnf                # print the formal grammar
vertex docs search <query>     # substring search across every page

The full Vertex language reference, baked into the compiler binary. No network required. Useful both for humans at a terminal and for agents that want to feed a topic into a language model without a WebFetch round trip.

Content is regenerated from this site on every release, so the output of vertex docs always matches the docs site as of the release the binary was cut from. Each command prints a footer with the source commit SHA so drift against vertex-run.github.io is visible.

Topic resolution. Slugs match the URL paths on this site. A bare slug (pattern-matching) resolves to a unique full slug (reference/pattern-matching) when there is exactly one. When a slug is ambiguous (e.g. pattern-matching matches both reference/pattern-matching and guides/pattern-matching), the command lists the candidates and exits 1. Typos fall through to a fuzzy match with a “did you mean” suggestion.

$ vertex docs reference/stdlib/string
$ vertex docs search 'exhaustive match'
$ vertex docs list | grep stdlib

The web has the mirror artifacts at vertex-run.github.io/llms.txt and vertex-run.github.io/llms-full.txt, produced by starlight-llms-txt per llmstxt.org.

vertex lsp

vertex lsp

Starts the Language Server on stdin/stdout. This is what your editor invokes when you open a .vtx file. You do not usually run it directly. See Editor integration.

Exit codes

All commands follow the standard convention:

Code	Meaning
0	Success.
1	Failure (compile error, test failure, DML error, etc.).