Using packages
Find and add
vard search bar chart # by name, keywords, summary and exports
vard info charts # before adding: versions, capabilities, API, tests
vard add charts # exact name; writes vard.toml and vard.lock
vard doc charts # AGENT.md + the API generated by the compiler
$ vard search chart
charts 1.0.0 [lan] — Bar charts drawn with Vard elements
caps: none · exports: Badge BarChart · tests 1 ✓
details: vard info NAME · install: vard add NAME
$ vard add charts
added charts 1.0.0 (lan)
caps: none
api: 2 views — `vard doc charts`
vard.lock: + charts 1.0.0
vard.lock: + tailwind 1.0.0
next: vard check
Variants:
vard add charts@1.4 # minimum version 1.4.0 on the 1.x line
vard add auth --registry acme # from a specific registry
vard add ui --path ../ui # a local package (monorepo)
vard add charts --git https://github.com/acme/charts --tag v1.4.0 # straight from git
vard add firebase --allow native # approving a sensitive capability
vard remove charts
A typo never turns into installing something similar:
$ vard add chart
error P001: no package `chart` in registry `acme`; did you mean: charts?
fix: search instead of guessing: vard search chart
An app’s vard.toml
[app]
name = "shop"
[dependencies]
charts = "1.4" # >= 1.4.0, < 2.0.0
legacy = "0.3" # 0.x: the 0.3.* line (as in Cargo)
exact = "=2.1.3" # exactly this version
auth = { version = "2", registry = "acme" } # from the acme registry
ui = { path = "../ui" } # a local package
widgets = { git = "https://github.com/acme/widgets", tag = "v2.1.0" }
mono = { git = "../monorepo", branch = "main", dir = "packages/mono" } # rev = "…" also works
[policy]
allow = ["native", "push"] # approved sensitive capabilities
[registries]
acme = "https://vard.acme.dev" # http(s) or a directory
default = "acme" # where dependencies without registry= come from
The manifest can be edited by hand: any vard command (check, run, test, doc) notices that
vard.lock is stale and reinstalls, saying so in one line.
Registries are looked up in order: the project’s [registries] → ~/.vard/config.toml →
the public registry vard (vardemin/vard-registry,
served at https://vardemin.github.io/vard-registry) → builtin (the packages bundled with
the toolchain, available offline). The default registry is vard unless default (or the
VARD_REGISTRY variable) says otherwise; VARD_OFFLINE=1 removes the public registry and
makes builtin the default. Each dependency comes from
exactly one registry — its own registry = ... or the default — never “wherever it was
found”: this rules out dependency confusion attacks.
Git dependencies
{ git = URL, tag | rev | branch = "...", dir = "sub/dir" } takes a package straight from a
repository — any URL git understands, or a local path relative to vard.toml. The commit
the reference resolves to is pinned in vard.lock together with the content hash of the
package files, so a branch does not move under the project until vard update NAME
re-resolves it:
$ vard update charts
~ charts 1.0.0 -> 1.1.0 (git 3f2a9c1e0b7d -> 8c41d0a2e9f3)
Git packages go through the same capability policy as registry packages. A package that
depends on a git (or path) package cannot be published to a registry (P021): registries
only reference registry versions.
New packages are quarantined
A package from a remote registry whose first version was published less than 72 hours ago
is not installed without --allow-new (P024). Fresh packages are where look-alikes and
typosquats live, so a person confirms them after a look at vard info NAME (owner,
publication time, provenance — which CI run built the archive). vard search and the
registry’s web page mark such packages NEW. The MCP tool vard_add has no
--allow-new: an agent asks the user. Directory registries (your own) are not quarantined.
vard.lock
# vard.lock — written by `vard install`. Commit it; review caps= changes like code.
lock 1
root deps=charts
pkg charts 1.0.0 src=reg:acme sha256=100e077d… api=350f1ca96bc8 caps= deps=tailwind
pkg tailwind 1.0.0 src=builtin sha256=6d7a5aa6… api=386f0117f3f1 caps= deps=
One line per package, sorted — a diff reads like a review:
- a new
caps=value — the package gained a capability; - a new
sha256=under the same version — content substitution (the manager marks it!); api=— a short hash of the public API: equal hash = equal API.
Commit the lockfile. It does not choose versions — MVS does, from vard.toml.
Namespaces
After vard add, the package’s public names are visible in the app’s code without imports:
view App {
state data: [Int] = [10, 40, 25]
BarChart(values: data, max: 50)
}
| Situation | What happens |
|---|---|
| a name is both in your code and in a package | yours wins; the package keeps using its own internally |
| two direct dependencies export a name | E0231 — write charts.Badge(...) or tailwind.Badge(...) |
| a name from a transitive dependency | E0232 — add it explicitly (vard add NAME) |
a _ name from someone else’s package | E0230 — private |
a pkg.Name that does not exist | E0235, with a fix for a typo |
| two dependencies declare one native name | E0233 |
You can qualify views (ui.Card { }), types (state s: ui.Style), functions and constructors
(geo.distance(a, b), ui.Style(size: 2)); std.Button is the std view.
Capabilities and policy
| Capability | Meaning | Sensitive |
|---|---|---|
prefs | reads/writes preferences (pref, prefGet) | |
links | opens URLs in other apps | |
share | the system share sheet | |
deeplinks | receives deep links | |
secure | Keychain / Keystore | ✓ |
permissions | asks for runtime permissions | ✓ |
push | token, notifications, push events | ✓ |
network | loads remote resources (https:// in code) | ✓ |
native | declares extern fn/event: runs the package’s native code | ✓ |
Sensitive capabilities need approval in [policy] allow. Without it, installation is
refused:
error P008: not allowed by [policy]: firebase 1.0.0 needs native (declares extern fn/event: runs native code shipped with the package)
fix: a person approves this: add to vard.toml `[policy] allow = ["native"]` or rerun with --allow native
--allow records the approval in [policy] — it lands in the diff and goes through review.
The vard_add MCP tool does not accept --allow: the agent tells the user what the package
needs, and a person decides.
Upgrading
vard update # every dependency — to the newest compatible versions
vard update charts --major # across a major boundary
vard check --fix # the packages' migrations are applied to your code
vard test
$ vard update charts --major
~ charts 1.0.0 -> 2.0.0
API change: major
! ~ view BarChart: `max` removed, `scale` added
vard.lock: ~ charts 1.0.0 -> 2.0.0
next: vard check --fix (applies the packages' migrations), then vard test
$ vard check
app/app.vard:3:32 error E0234: `max` of `BarChart` was renamed to `scale` in charts 2.0.0
3 | BarChart(values: [10, 50], max: 80)
fix: `max` -> `scale` (auto: vard check --fix)
vard update changes the requirements in vard.toml (visible in the diff), then reinstalls.
Packages in headless mode
A package’s externs answer with values from its [sim] (for example, authCurrentUser →
nil); the rest stay pending until a test says resolve/send. mock in a test overrides
[sim]. That is why vard run works right after vard add — even for a package wrapping a
native SDK.
Diagnostics in package code
Package files are shown as @name/file.vard:LINE. Packages’ warnings are not printed (that
is the author’s business); errors are. vard check --fix never writes into package files:
they are inputs from the cache (~/.vard/cache/pkgs/).