vercel-labs--zerolang/docs/articles/cli-reference.md

Use Commands By Workflow

The Zerolang CLI is organized around graph-first agent work. Humans ask for a task; agents inspect and patch the graph; projections are exported only for review or manual edits.

Most commands default to the current directory:

zero status
zero query
zero patch --op help
zero check
zero run -- <args>

Pass an explicit graph input or package when you are outside the project:

zero check examples/hello.graph
zero query examples/crm-api
zero run examples/json-api-router.graph -- $'GET /health\n\n'

Create A Project

Use zero init for all project creation.

zero init
zero init --template cli crm-tool
zero init --manifest toml --format binary --template package api-server

If no path is given, zero init creates the package in the current directory. For . or an omitted path, the package name comes from the directory name.

{
  "messages": [
    {
      "role": "user",
      "text": "start a cli here"
    },
    {
      "role": "assistant",
      "text": "I’ll initialize this directory and add the starting CLI shape."
    },
    {
      "role": "tools",
      "calls": [
        {
          "command": "zero init --template cli",
          "output": "graph project init ok\nwrote: ./zero.toml\nwrote: ./zero.graph"
        },
        {
          "command": "zero patch --op 'addMain'",
          "output": "program graph patch ok"
        }
      ]
    }
  ]
}

Inspect Before Editing

Agents should query for the exact thing they need instead of dumping the whole program.

zero status
zero query --fn main
zero query --find customer
zero query --refs handle
zero query --calls write
zero inspect --json
zero size --json
zero mem --json

Use plain text first. Use --json when a tool needs exact fields such as node ids, graph hashes, interfaceFingerprints, targetToolchains, usedStdlibHelpers, memoryBudgets, or releaseTargetContract.

Patch The Graph

Patch commands are checked graph edits:

zero patch --op 'addFunction name="add" ret="i32"'
zero patch --op 'addParam fn="add" name="x" type="i32"'
zero patch --op 'addParam fn="add" name="y" type="i32"'
zero patch --op 'addReturnBinary fn="add" name="+" left="x" right="y" type="i32"'

For larger edits, use a patch file under /tmp:

zero-program-graph-patch v1
expect graphHash "graph:a7f7e6899a73f3b4"
replaceFunctionBody main
  check world.out.write "hello\n"
end

Dry-run a repository graph patch without writing:

zero patch --check-only /tmp/main.patch
zero patch --dry-run --json /tmp/main.patch

Apply it:

zero patch /tmp/main.patch

To replace one function body without patch syntax, pass only the new body rows (exactly what zero view --fn <name> prints between the signature braces). --body-file - reads them from stdin, so a heredoc does the whole edit in one call:

zero patch --replace-fn main --body-file - <<'EOF'
  check world.out.write("hello agent\n")
EOF

A file path works as the alternative:

zero patch --replace-fn main --body-file /tmp/main.body

To change a few characters inside a function without retyping the body, --replace-in-fn replaces one unique literal occurrence of --old in the function's canonical body text (what zero view --fn <name> prints) with --new, then revalidates exactly like --replace-fn:

zero patch --replace-in-fn main --old 'limit + 1' --new 'limit + 2'

A missing or non-unique --old fails with the occurrence count. Inline --old/--new accept \n escapes for multi-line text; --old-file and --new-file <file|-> read the text from a file or stdin.

The patch step validates graph shape and repository metadata. A stale graph hash, missing required edge, sparse ordered child group, or invalid row body fails before the package store is updated.

Validate Only What You Need

Do not run every command after every patch. zero patch already reports whether the edit applied. Run the next command that proves the user-visible behavior.

zero check
zero test
zero test --json --filter add
zero run -- add 40 2

Use zero check --json when an editor, CI job, or agent needs stable diagnostic fields. Test JSON includes expectedFailures, fixtures, snapshotKey, and per-test results.

Run And Build

Use zero run for local behavior:

zero run -- help
zero run examples/hello.graph

Use zero build for artifacts:

zero build --emit exe --target linux-musl-x64 --out .zero/out/app
zero build --emit obj --target darwin-arm64 examples/direct-call-add.graph --out .zero/out/add.o
zero build --emit llvm-ir examples/hello.graph --out .zero/out/hello.ll

Build JSON reports profile and target readiness:

zero build --json --profile tiny --target linux-musl-x64 examples/hello.graph --out .zero/out/hello

Important fields include profileSemantics, profileBudget, releaseTargetContract, targetToolchains, compileTime, and repeat-build hash policy data for artifact determinism.

Review Projections

Projection commands are for humans:

zero export
zero verify-projection
zero import
zero diff
zero view

Use zero export when a human wants the current .0 projection. Use zero import after a human intentionally edits projection text. Use zero verify-projection to catch drift without writing.

{
  "messages": [
    {
      "role": "user",
      "text": "show me the projection before we keep going"
    },
    {
      "role": "assistant",
      "text": "I’ll export the current projection and verify it matches the graph."
    },
    {
      "role": "tools",
      "calls": [
        {
          "command": "zero export",
          "output": "repository graph export ok\nwrote: ./src/main.0"
        },
        {
          "command": "zero verify-projection",
          "output": "repository graph verify-projection ok"
        }
      ]
    }
  ]
}

Diagnose And Repair

zero explain NAM003
zero fix --plan --json
zero doctor
zero dev --json
zero dev --json --trace

zero dev --json is the editor-facing snapshot. It includes diagnostics, document symbols, hover data, completions, definition targets, and interfaceFingerprints.

Command Groups

Workflow	Commands
create	init
inspect	status, query, inspect, size, mem, doc, source-map
edit graph	patch, reconcile, merge
validate	check, test, verify-projection, validate, roundtrip
run/build	run, build, targets, abi
projection review	export, import, view, diff, fmt, tokens, parse
support	skills, explain, fix, doctor, clean, dev, time

Input Forms

Input	Meaning
project/	A package directory. Normal package commands compile from zero.graph.
zero.toml	Preferred package manifest. Takes precedence over zero.json for directory inputs.
zero.json	Compatibility manifest. Prefer zero.toml for new packages.
file.graph	Binary or text graph store/artifact.
file.0	Human-readable projection for formatting, import/export, and review workflows. It is not the normal compiler input.

JSON Rule

Humans and interactive agents should start with concise text output. Use JSON when a program needs exact structured data:

zero check --json
zero test --json
zero inspect --json
zero size --json
zero doctor --json

JSON is a contract for tools, not the default reading experience for humans.