CLI verbs
Every verb below is a subcommand of the single mado binary, verified against
crates/mado/src/bin/mado.rs. Flags shown are the notable ones; run
mado <verb> --help for the complete, authoritative list.
mado init
Initialize a new mado repository + workspace in the current directory.
| Flag | Default | Meaning |
|---|---|---|
--workspace <name> | default | Workspace name to register. Must be unique per shared server. |
--store-format <fs|fjall> | fs | At-rest blob format for a local init. fs: loose files, shareable by concurrent processes. fjall: embedded LSM, exclusive to one process, the production/import format. Rejected for remote inits. |
--resume | off | This init is the target of a mado ws resume: skip the workspace-name collision probe (the name is expected to be registered). |
mado mount
Mount the working copy through the FUSE VFS (a daemon).
| Flag | Default | Meaning |
|---|---|---|
--mountpoint <dir> | required | Where to mount. Must differ from the workspace root. |
--no-auto-snapshot | off | Disable folding idle mount edits into @. |
--no-auto-checkpoint | off | Disable the remote auto-checkpointer (no effect on a local workspace). |
--checkpoint-interval <secs> | 30 | Auto-checkpoint cadence — the bounded off-box loss window. 0 disables. |
--allow-other | off | -o allow_other: let other uids access the mount (needs user_allow_other in /etc/fuse.conf). Required to re-export into a guest VM. |
--read-only | off | -o ro: kernel refuses writes before they reach the VFS. |
--scratch <dir> | none | Local backing dir for scratch redirections (off-snapshot build dirs). |
--redirect <path> | none | Mount-relative path to redirect into --scratch (repeatable; merged with .mado-redirections). |
--hydration-timeout-secs <secs> | 30 | Per-attempt deadline for a content fetch inside a FUSE read. |
--hydration-retries <n> | 2 | Extra fetch attempts after the first failure/timeout, then EIO. |
mado serve-virtiofs
Serve the working copy over virtiofs (vhost-user-fs) on a socket — the
native second transport, no virtiofsd and no /dev/fuse.
| Flag | Default | Meaning |
|---|---|---|
--socket <path> | required | vhost-user unix socket qemu attaches to. |
--no-auto-snapshot | off | Disable idle edit folding. |
--no-auto-checkpoint / --checkpoint-interval <secs> | / 30 | Inert here (the daemon holds no lease); present for CLI symmetry. |
--cache-timeout-secs <secs> | 1 | Guest attr/entry cache timeout (virtiofs has no active invalidation). Larger = faster, staler. |
--fresh | off | No caching (--cache-timeout-secs 0): host-side checkouts reflect instantly. |
--scratch <dir> / --redirect <path> | Scratch redirections, as for mount. | |
--hydration-timeout-secs / --hydration-retries | 30 / 2 | As for mount. |
mado snapshot
Fold edits made through the mount into @. Pulls the live overlay from the
running daemon over the control socket and amends @. Quiet, idempotent — the
manual equivalent of the daemon’s idle auto-snapshot. No flags.
mado materialize [PATH]
Prefetch (hydrate) the working copy’s file contents into the disk blob cache.
Walks @’s tree under PATH (default: the whole tree; a directory prefetches
its subtree) and fetches every file’s blobs with bounded concurrency. Requires a
remote-backed workspace (MADO_REMOTE_ADDR); a no-op on a local workspace.
mado pack
Build locality packs for a commit’s dense small-file subtrees and record the pack index.
| Flag | Default | Meaning |
|---|---|---|
-r, --revision <revset> | @ | Revision whose tree to pack (must resolve to one commit). |
--recursive | off | Build recursive-subtree (v2) packs instead of per-directory (v1). The measured-best default for real trees. |
Packs are a reclaimable cache, never a GC root. Building is idempotent.
mado pack-status
Report the running mount daemon’s locality-pack attach state (attached mode /
version / entry count / discovery source, or the not-attached reason). Requires
a live mado mount / serve-virtiofs in the workspace. No flags.
mado ws checkpoint
Record a workspace checkpoint: fold pending mount edits into @, snapshot
scratch, and bind (operation, scratch manifest, attr-table presence) into one
durable record.
| Flag | Meaning |
|---|---|
--scratch <dir> | Local backing dir of the scratch redirections. Omit if the mount runs without scratch. |
--redirect <path> | Extra path redirected into --scratch (repeatable; merged with .mado-redirections). |
mado ws pause
Pause this workspace so it can resume on another machine. Folds edits, snapshots
scratch, uploads the attr table, writes the checkpoint, and CAS-swaps the
server-side workspace head to it (the commit point). Blocks until everything is
remote-durable. Flags: --scratch <dir>, --redirect <path> (as for
checkpoint).
mado ws resume
Resume a paused workspace into this workspace. The target must be a fresh
mado init --workspace <name> --resume against the same server.
| Flag | Meaning |
|---|---|
--scratch <dir> | Local backing dir to restore scratch redirections into. Required when the checkpoint carries scratch entries. |
--force | Overwrite existing local workspace state (dirty workspace). |
--steal | Steal the workspace lease from a prior holder — succeeds only once the lease has expired on the server clock; bumps the epoch to fence the old holder. |
mado serve
Serve this repo’s blob store + op-log over gRPC (the networked backend). Blocks until killed. Core flags:
| Flag | Default | Meaning |
|---|---|---|
--addr <host:port> | 127.0.0.1:50051 | Bind address (:0 lets the OS pick, printed on startup). |
--op-heads-db <file> | none | Persist op-heads to SQLite (else ephemeral in-memory). Required for scheduled GC and git interop. |
--auth-token <token> | none | Require authorization: Bearer <token> on every RPC. |
--prod-blobstore | off | Store through the production composition (Prefix → Pack(zstd) → Multiplexed → Fs). Changes the at-rest format. |
--blob-prefix <p> | none | Namespace blobs under this prefix (implies prod composition). |
--gc-interval-secs <secs> | 0 | Run a server-side GC sweep every N seconds (0 = never). Requires --op-heads-db. |
--gc-min-age-secs <secs> | 3600 | Scheduled GC age grace period. |
--stats-interval-secs <secs> | 60 | Blob-traffic summary interval (0 disables). |
Online git interop flags (all require --op-heads-db): --git-ingest-url,
--git-ingest-ref (default master), --git-ingest-interval-secs (300),
--git-ingest-mirror, --git-ingest-scope, --git-ingest-threads;
--git-export-url, --git-export-staging, --git-export-refspec,
--git-export-bookmark, --git-export-scope, --git-export-interval-secs
(300), --git-export-force, --git-export-on-reject (retry|rebase|surface,
default retry), --git-export-fidelity (any|roundtrip-only, default
any); --git-interop-config <file> (named remotes, additive to the
single-remote flags); throttling --git-interop-max-serve-ops (0 =
unthrottled); server-held credentials --git-credential-token /
--git-credential-file (preferred) / --git-credential-username
(default x-access-token); event webhook --git-webhook-addr /
--git-webhook-secret / --git-webhook-secret-file. See
Operations and docs/design/online-git-interop.md.
mado sync-now
Wake a running mado serve’s online git interop tasks now (against
MADO_REMOTE_ADDR) instead of waiting for their poll interval.
| Flag | Meaning |
|---|---|
--remote <name> | An interop task label to wake (e.g. git-ingest[foo]); repeatable. Omitted = wake them all. |
mado gc
Garbage-collect unreachable blobs from .jj/repo/store. Dry run by default.
| Flag | Default | Meaning |
|---|---|---|
--op-heads-db <file> | required | Live-heads database defining what to retain. |
--scope <scope> | "" | Op-heads scope to read heads for. |
--sweep | off | Actually delete (else report only). |
--min-age-secs <secs> | 3600 | Age grace period; 0 disables (only safe when quiesced). |
--prod-blobstore / --blob-prefix <p> | Must match how the store is served. |
mado recover-op-heads
Rebuild the op-heads database from the blobstore journal.
| Flag | Meaning |
|---|---|
--out-db <file> | Where to write the reconstructed database. Must not already exist. |
--prod-blobstore / --blob-prefix <p> | Must match how the store is served. |
mado import-git
Convert a git repository’s history into this repo’s mado store and (unless
--no-publish) publish the imported tips. One-way boundary conversion, memoized
in git-map.sqlite (resumable; incremental on re-run after git fetch).
| Flag | Default | Meaning |
|---|---|---|
--git-repo <path> | required | Git repo (work tree or bare .git) to import. |
--ref <ref> | all local branches | A git ref to import (repeatable). |
--depth <n> | none | Shallow graft by generation count (explodes on merge-dense history — prefer --shallow-since). |
--shallow-since <when> | none | Time-bound shallow graft (YYYY-MM-DD, ISO timestamp, or epoch seconds). |
--no-publish | off | Convert objects but publish no operation (imports stay unreferenced). |
--op-heads-db <file> | none | Database to publish into. Required unless --no-publish. |
--scope <scope> | "" | Op-heads scope to publish under. |
--progress-every <n> | 1000 | Progress line cadence (0 = silent). |
--threads <n> | 0 | Conversion worker threads (0 = one per core). |
--pack-order <auto|on|off> | auto | Convert in pack-offset order (faster for large shallow clones). |
--prod-blobstore / --blob-prefix <p> | Must match how the store is served. | |
--no-packs | off | Skip building + publishing locality packs for imported head trees (on by default; recursive index, warm-local). |
mado export-git
Export this repo’s history (the current view’s bookmarks) into a git repository.
Shares git-map.sqlite with import: exports back into the original repo reuse
objects byte-identically; fresh exports of unsigned, gitlink-free history
reproduce the original commit ids. Conflicted commits refuse to export.
| Flag | Default | Meaning |
|---|---|---|
--git-repo <path> | required | Git repo to export into (initialized non-bare if absent). |
--bookmark <name> | all local bookmarks | A bookmark to export as the same-named branch (repeatable). |
--op-heads-db <file> | required | Database naming the view to export. |
--scope <scope> | "" | Op-heads scope to read the view from. |
--force | off | Move existing branch refs that point elsewhere. |
--progress-every <n> | 1000 | Progress line cadence (0 = silent). |
--prod-blobstore / --blob-prefix <p> | Must match how the store is served. |